Atoka API User Reference

v20241018.0953

Company Search

Find the needle in the haystack!

We implemented dozens of filters to narrow down the several millions companies in our databases to the very few your are really looking for: find them via their location, their economics, social networks presence, or even via the version of their CMS. You can also use any officially registered information, and much more.

But what really sets our APIs apart is that all company information is distilled through our semantic analysis technologies (more at dandelion.eu), so that you can get well beyond traditional industry classifications (take a look at the Semantic Enrichment filters).

Plese note that, by default, this endpoint returns just the Atoka Company IDs (and little more): you normally need a separate call to the details endpoint (for each of them) to get the actual company data available. But you can also use the data packages parameter to get needed details in the same (single) API call.

https://api.atoka.io/v2/companies

All requests must be properly authenticated.

Authentication

Parameters

  • token string required

    All requests must be properly authenticated; see the Authentication section for more info

  • appUserId string Private parameter

    To properly authenticate each requests you should send the application id of the user sending the request, see the Authentication section for more info

curl -G "https://api.atoka.io/v2/companies"

Debug

Use these parameters when you need to understand how your request was evaluated by the API.

Parameters

  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

curl -G "https://api.atoka.io/v2/companies" -d "explain=true"

Response modifications

When explain is true, the response will be:

{
}
curl -G "https://api.atoka.io/v2/companies" -d "explain=true"

Response

By default this API endpoint returns the list of companies matching the selected criteria.

Using these parameters, you'll be able to customize the output you'll get from your searches.

Parameters

  • fields array,
    default is items

    Get just the list of companies matched, or the search facets (or both!).

    If you set this to value none, you'll get just the meta object, with count of companies matching your search criteria.

    Please notice that if you request the search facets, you need to provide the facetFields parameter as well.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • items
    • facets
    • none

  • facetFields array

    We want to keep our API as fast as possible, but facets are expensive to compute. To avoid slowing things down, you must explicitly state which facets you want when you request them. We want to make your life as simple as possible, though, that's why we support wildcards to be used in here; with them you will be able to have an initial look at the data, and to explicitly specify the facets you need once you start developing your application.

    This field is required when requesting the search facets through the fields parameter

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * Enable all the facets of all the requested packages
    • atokaIndicators.* Enable all the facets of the package "atokaIndicators"
    • atokaIndicators.innovation.categoryScore
    • atokaIndicators.innovation.score
    • atokaIndicators.reliabilityScore.class
    • atokaIndicators.webCentrality.categoryScore
    • atokaIndicators.webCentrality.score
    • base.* Enable all the facets of the package "base"
    • base.activityStatus.insolvencyProceeding
    • base.agcm.rating
    • base.allAtecoInfoCamere
    • base.ateco
    • base.atecoInfoCamere
    • base.founded
    • base.foundedYear
    • base.gov
    • base.govType
    • base.legalClass
    • base.legalForms
    • base.marketSectors
    • base.nace
    • base.noRea
    • base.noReaInfo.activities
    • base.noReaInfo.forms
    • base.pmiSize
    • base.registeredAddress.macroregion
    • base.registeredAddress.municipality
    • base.registeredAddress.postcode
    • base.registeredAddress.province
    • base.registeredAddress.region
    • and other 109 options... (see the whole list)

  • geoClusterLevel string Private parameter

    select the zoom level of geo clusters

    Choose only one among:

    • region
    • province
    • municipality
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8

  • geoClusterDiagonal integer Private parameter

    length in pixel of the map viewport diagonal

curl -G "https://api.atoka.io/v2/companies" -d "fields=items,facets" -d "facetFields=base.*"

Response modifications

When fields is items, the response will be:

{
"items": [
{
"id": "6da785b3adf219770c9e",
"ids": [
"foo",
...
],
"active": false,
"cervedId": 1015245,
"country": "it",
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)",
"name": "ACME S.p.A.",
"baby": false,
"obfuscated": false,
"score": 42
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/companies" -d "fields=items"

When fields is facets, the response will be:

{
"facets": {
},
"meta": {
"count": 34,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/companies" -d "fields=facets"

Data packages

For each item in search results, by default, we show just the Atoka Company ID (and little more).

By using the packages parameter you can fine tune the results to the level your application actually requires, or show all information available using all the data packages you subscribed to (with packages=*).

Remember: your subscription gives you access to different levels of detail in data returned!

If you have special needs and want to further customize the data returned, we can adapt the output to your specific needs: just get in touch with us at sales@atoka.io.

Please note: if a company has been obfuscated, the API will not return any data contained in the packages even if you request them. You can check if a company is obfuscated from the field obfuscated: true.

Parameters

  • packages array

    Fine tune the results to the level of detail your application actually requires.

    The extraction cost per single company will be multiplied to the number of results in your query (up to offset parameter value).

    To avoid using any package, don't pass this parameter and the results will contain just the Atoka Company ID (and little more).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • atokaIndicators
    • base
    • cervedIndicators
    • contacts
    • covid19
    • economics
    • economicsLite
    • entities
    • foreignMarket
    • govcontracts
    • groups
    • locations
    • notesToAccounts
    • people
    • publicFunding
    • shares
    • socials
    • technologies
    • web
    • * (use all the data packages you have an active subscription for)
curl -G "https://api.atoka.io/v2/companies" -d "packages=*"

Response modifications

When packages is *, the response will be:

{
"items": [
{
"id": "6da785b3adf219770c9e",
"ids": [
"foo",
...
],
"active": false,
"cervedId": 1015245,
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)",
"country": "it",
"name": "ACME S.p.A.",
"baby": false,
"obfuscated": false,
"score": 42,
},
...
],
"facets": {
},
"geoClusters": [
{
"id": "foo",
"geoBound": [
0.42,
...
],
"lat": 0.42,
"lon": 0.42,
"count": 42
},
...
],
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/companies" -d "packages=*"

Extended info

We enrich company records with data gathered from all over the web.

These parameters let you filter company records using additional data that give Web Super Powers to your queries!

Parameters

  • tagStart string,
    default is "<em>"

    Text that is prefixed to field highlights. Valid only if one of the highlightable field filters is passed.

  • tagEnd string,
    default is "</em>"

    Text that is appended to field highlights. Valid only if one of the highlightable field filters is passed.

  • govContracts array govContracts

    Filter on company relationships with public administrations.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • applied
    • not-applied matches if company has never applied for a contract
    • won matches if company won at least a contract
    • not-won matches if company has never won a contract

  • websitesDomains array web

    Match companies linked to one (or more) specific web site. Can contain protocol (optional) and usually a second level domain (spaziodati.eu).

    Can also be a third (blog.spaziodati.eu) or higher level (more specific) one.

    Use websitesDomains=* to find all companies having a website.

    Accepts multiple values, separated with , (comma) char.

  • websitesContent string web

    Match companies whose websites contain passed text.

  • websitesContentMatch string,
    default is "*"     web

    Whether to search websiteContent text only in a given document section. Valid only if websitesContent is passed.

    Choose only one among:

    • * search in the whole document
    • footer search only in the footer
    • body search only in the body

  • websitesContentTag boolean,
    default is false     web

    Whether to highlight websiteContent search results' matches or not. Valid only if websitesContent is passed.

  • websitesContentTagStart string web

    Text that is prefixed to web content highlights. Valid only if websitesContent and websitesContentTag are passed.

    This parameter is deprecated. Please use tagStart instead

  • websitesContentTagEnd string web

    Text that is appended to web content highlights. Valid only if websitesContent and websitesContentTag are passed.

    This parameter is deprecated. Please use tagEnd instead

  • oggettoSocialeContent string Private parameter base

    Match companies whose oggetto sociale contain passed text.

  • oggettoSocialeContentTag boolean,
    default is false     Private parameter base

    Whether to highlight oggettoSocialeContent search results' matches or not. Valid only if oggettoSocialeContent is passed.

  • oggettoSocialeContentTagStart string Private parameter base

    Text that is prefixed to web content highlights. Valid only if oggettoSocialeContent and oggettoSocialeContentTag are passed.

    This parameter is deprecated. Please use tagStart instead

  • oggettoSocialeContentTagEnd string Private parameter base

    Text that is appended to web content highlights. Valid only if oggettoSocialeContent and oggettoSocialeContentTag are passed.

    This parameter is deprecated. Please use tagEnd instead

  • businessDescriptionContent string Private parameter base

    Match companies whose business description contain passed text.

  • businessDescriptionContentTag boolean,
    default is false     Private parameter base

    Whether to highlight businessDescriptionContent search results' matches or not. Valid only if businessDescriptionContent is passed.

  • businessDescriptionContentTagStart string Private parameter base

    Text that is prefixed to web content highlights. Valid only if businessDescriptionContent and businessDescriptionContentTag are passed.

    This parameter is deprecated. Please use tagStart instead

  • businessDescriptionContentTagEnd string Private parameter base

    Text that is appended to web content highlights. Valid only if businessDescriptionContent and businessDescriptionContentTag are passed.

    This parameter is deprecated. Please use tagEnd instead

  • emails array contacts

    Match companies for which specific email addresses were found.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • administration
    • info
    • management
    • marketing
    • purchases
    • sales
    • support
    • technician
    • personal
    • other
    • * match for any kind of email found

  • phones array contacts

    Match for potential phone numbers found, and filters by type of phone

    To match all companies, with and without phone numbers, do not pass the parameter.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * matches for any kind of phone number
    • standard matches for standard phone numbers
    • whatsapp matches phone numbers for which we detected a whatsapp account
    • telegram matches phone numbers for which we detected a telegram channel

  • phonesExclude array contacts

    Filters excluding companies with a known phone numbers, or phone numbers of a specific type.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * matches for any value
    • standard
    • whatsapp
    • telegram

  • feeds boolean web

    A content syndication feed (RSS, Atom, etc.) was found.

    To match all companies, with and without a content syndication feeds, do not pass the parameter.

  • blog array technologies

    A blog site related to the company was found.

    You can use the Blogging platforms service to find possible values for this parameter.

    To match any platform, use blog=*.

    Accepts multiple values, separated with , (comma) char.

  • cms array technologies

    Match if a content management system was detected in one of the company websites.

    You can use the CMS platforms service to find possible values for this parameter.

    To match any platform, use cms=*.

    Accepts multiple values, separated with , (comma) char.

  • ecommerce array technologies

    Match if an online shop was detected in one of the company websites.

    You can use the E-commerce platforms service to find possible values for this parameter.

    To match any platform, use ecommerce=*.

    Accepts multiple values, separated with , (comma) char.

  • payments array technologies

    Match if a payment solution was detected in one of the company websites.

    You can use the Payment platforms service to find possible values for this parameter.

    To match any platform, use payments=*.

    Accepts multiple values, separated with , (comma) char.

  • analytics array technologies

    Match if an analytics solution was detected in one of the company websites.

    You can use the Analytics platforms service to find possible values for this parameter.

    To match any platform, use analytics=*.

    Accepts multiple values, separated with , (comma) char.

  • marketing array technologies

    Match if an online marketing tool was detected in one of the company websites.

    You can use the Marketing tools service to find possible values for this parameter.

    To match any tool, use marketing=*.

    Accepts multiple values, separated with , (comma) char.

  • apps array technologies

    Match companies whose website contains link to applications. Can filter by category of application

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • itunes
    • play
    • * match for any kind of application found

  • socials array socials

    If we detected presence on specified social networks.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • facebook
    • twitter
    • flickr
    • googleplus WARN: this value is DEPRECATED
    • instagram
    • linkedin
    • vimeo
    • youtube
    • pinterest

  • socialScoreLocalMin number socials

    Match companies whose socialScore (local = considering only latest 3 months) is greater than the given value. The value must be in the interval [0, 1].

    Use socialScoreLocalMin=0 to get all companies with known social score (local)

    Use a number between 0 and 1.

  • socialScoreLocalMax number socials

    Match companies whose socialScore (local = considering only latest 3 months) is smaller than the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • socialScoresLocal array socials

    Match companies whose socialScore (local = considering only latest 3 months) label is one of the given values. Cannot be used in combination with socialScoreLocalMin and socialScoreLocalMax

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • top
    • high
    • medium
    • low
    • * matches for any value

  • socialScoreGlobalMin number socials

    Match companies whose socialScore (global = considering latest 12 months) is greater than the given value. The value must be in the interval [0, 1].

    Use socialScoreLocalMin=0 to get all companies with known social score (global)

    Use a number between 0 and 1.

  • socialScoreGlobalMax number socials

    Match companies whose socialScore (global = considering latest 12 months) is smaller than the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • socialScoresGlobal array socials

    Match companies whose socialScore (gloabl = considering latest 12 months) label is one of the given values. Cannot be used in combination with socialScoreGlobalMin and socialScoreGlobalMax

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • top
    • high
    • medium
    • low
    • * matches for any value

  • socialPresenceScoreMin number socials

    Match companies whose social presence score is greater than or equal to the given value. The value must be in the interval [0, 1].

    Use socialPresenceScoreMin=0 to get all companies with known social presence score

    Use a number between 0 and 1.

  • socialPresenceScoreMax number socials

    Match companies whose social presence score is smaller than or equal to the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • facebookScoreLocalMin number socials

    Match companies whose facebook score (local = considering only latest 3 months) is greater than the given value. The value must be in the interval [0, 1].

    Use facebookScoreLocalMin=0 to get all companies with known facebook score (local)

    Use a number between 0 and 1.

  • facebookScoreLocalMax number socials

    Match companies whose facebook score (local = considering only latest 3 months) is smaller than the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • facebookScoreGlobalMin number socials

    Match companies whose facebook score (global = considering latest 12 months) is greater than the given value. The value must be in the interval [0, 1].

    Use facebookScoreLocalMin=0 to get all companies with known facebook score (global)

    Use a number between 0 and 1.

  • facebookScoreGlobalMax number socials

    Match companies whose facebookScore (global = considering latest 12 months) is smaller than the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • twitterScoreLocalMin number socials

    Match companies whose twitter score (local = considering only latest 3 months) is greater than the given value. The value must be in the interval [0, 1].

    Use twitterScoreLocalMin=0 to get all companies with known twitter score (local)

    Use a number between 0 and 1.

  • twitterScoreLocalMax number socials

    Match companies whose twitter score (local = considering only latest 3 months) is smaller than the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • twitterScoreGlobalMin number socials

    Match companies whose twitter score (global = considering latest 12 months) is greater than the given value. The value must be in the interval [0, 1].

    Use twitterScoreLocalMin=0 to get all companies with known twitter score (global)

    Use a number between 0 and 1.

  • twitterScoreGlobalMax number socials

    Match companies whose twitterScore (global = considering latest 12 months) is smaller than the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • blogScoreMin number socials

    Match companies whose blog score is greater than or equal to the given value. The value must be in the interval [0, 1].

    Use blogScoreMin=0 to get all companies with known blog score

    Use a number between 0 and 1.

  • blogScoreMax number socials

    Match companies whose blog score is smaller than or equal to the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • webCentralityScores array Private parameter atokaIndicators

    Match companies whose web centrality score label is one of the given values. Cannot be used in combination with webCentralityScoreMin and webCentralityScoreMax

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • top
    • high
    • medium
    • low
    • * matches for any value

  • webCentralityScoreMin number Private parameter atokaIndicators

    Match companies whose web centrality score is greater than or equal to the given value. The value must be in the interval [0, 1].

    Use webCentralityScoreMin=0 to get all companies with known webCentrality score

    Use a number between 0 and 1.

  • webCentralityScoreMax number Private parameter atokaIndicators

    Match companies whose web centrality score is smaller than or equal to the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • webCentralityCategoryScores array Private parameter atokaIndicators

    Match companies whose web centrality category score label is one of the given values. Cannot be used in combination with webCentralityCategoryScoreMin and webCentralityCategoryScoreMax

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • top
    • high
    • medium
    • low
    • * matches for any value

  • webCentralityCategoryScoreMin number Private parameter atokaIndicators

    Match companies whose web centrality category score is greater than or equal to the given value. The value must be in the interval [0, 1].

    Use webCentralityCategoryScoreMin=0 to get all companies with known web centrality category score

    Use a number between 0 and 1.

  • webCentralityCategoryScoreMax number Private parameter atokaIndicators

    Match companies whose web centrality category score is smaller than or equal to the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • innovationScores array atokaIndicators

    Match companies whose innovation score label is one of the given values. Cannot be used in combination with innovationScoreMin and innovationScoreMax

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • top
    • high
    • medium
    • low
    • * matches for any value

  • innovationScoreMin number atokaIndicators

    Match companies whose innovation score is greater than or equal to the given value. The value must be in the interval [0, 1].

    Use innovationScoreMin=0 to get all companies with known innovation score

    Use a number between 0 and 1.

  • innovationScoreMax number atokaIndicators

    Match companies whose innovation score is smaller than or equal to the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • innovationCategoryScores array atokaIndicators

    Match companies whose innovation category score label is one of the given values. Cannot be used in combination with innovationCategoryScoreMin and innovationCategoryScoreMax

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • top
    • high
    • medium
    • low
    • * matches for any value

  • innovationCategoryScoreMin number atokaIndicators

    Match companies whose innovation category score is greater than or equal to the given value. The value must be in the interval [0, 1].

    Use innovationCategoryScoreMin=0 to get all companies with known innovation category score

    Use a number between 0 and 1.

  • innovationCategoryScoreMax number atokaIndicators

    Match companies whose innovation category score is smaller than or equal to the given value. The value must be in the interval [0, 1].

    Use a number between 0 and 1.

  • exportScores array Private parameter foreignMarket

    Match companies whose export propensity score label is one of the given values.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • minimum
    • low
    • medium
    • high
    • very high
    • certain
    • * matches for any value

  • certifications array Private parameter certifications

    Match companies whose certifications_type label is one of the given values. If you want to query this field by name, you should retrieve a state code using the Certifications service.

    Accepts multiple values, separated with , (comma) char.

    This parameter is deprecated. Please use certificationCategoryCodes instead

  • certificationCategories array Private parameter certifications

    Match companies whose certification category is one of the given values. If you want to query this field by label, you should retrieve a code using the Certifications Codes service.

    Accepts multiple values, separated with , (comma) char.

  • certificationCategoriesExclude array Private parameter certifications

    Match companies not having a certification with this category code. If you want to query this field by label, you should retrieve a code using the Certifications Codes service.

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/companies" -d "websitesDomains=*" -d "websitesContentMatch=*" -d "emails=administration,info" -d "phones=*" -d "phonesExclude=*" -d "feeds=true" -d "blog=*" -d "ecommerce=*" -d "payments=*" -d "apps=itunes" -d "socials=flickr,instagram"

Ordering & Pagination

To download long lists of results you can paginate returned items using these parameters.

You can also decide the order in which items are returned.

Parameters

  • limit integer,
    default is 10

    This is the number of individual objects that are returned in each page.

    Use a number between 0 and 50.

  • offset integer,
    default is 0

    This offsets the start of each page by the number specified.

    Use a number between 0 and 9950.

  • ordering string,
    default is "atoka"

    Selects the order in which results are returned.

    Choose only one among:

curl -G "https://api.atoka.io/v2/companies" -d "limit=10" -d "offset=30" -d "ordering=revenue"

General info

You can search for company records in all the countries we support.

Some filters work only in specific countries, but the following ones can always be used, even when searching within more than one country at the same time (for example when countries=it,fr).

Parameters

  • countries array,
    default is it

    Restrict matches to those valid in specific countries.

    If you are interested in accessing data from European countries: just get in touch with us at sales@atoka.io.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • it
    • no
    • at
    • be
    • ch
    • cz
    • de
    • dk
    • es
    • fr
    • gb
    • gr
    • hu
    • ie
    • nl
    • pl
    • pt
    • ro
    • se
    • si
    • sk
    • * matches for any value

  • active array,
    default is true

    Find only active/inactive companies or all of them. The default is to look for active companies only.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • true
    • false
    • unknown
    • * matches for any value

  • activeAtoka boolean Private parameter

    Find only companies identified as operative / not operative using our custom algorithm

  • regNumbers array base

    If you have any kind of official registration number associated to the company, use this parameter.

    For Italian companies (countries=it) this matches against Partita IVA, Codice Fiscale and REA. For REA, you can provide both CCIAA (camera di commercio) and REA number with regNumbers=TN210089.

    Accepts multiple values, separated with , (comma) char.

  • vat array base

    Search for company's V.A.T. code.

    For Italy (countries=it), it uses Partita IVA.

    Accepts multiple values, separated with , (comma) char.

  • taxIds array base

    Search for company's tax identification number.

    For Italy (countries=it), it uses Codice Fiscale.

    Accepts multiple values, separated with , (comma) char.

  • ids array

    Search via already known Atoka Company IDs.

    Accepts multiple values, separated with , (comma) char.

  • idsExclude array

    Exclude results via already known Atoka Company IDs.

    Accepts multiple values, separated with , (comma) char.

  • validIdentifiers boolean Private parameter base

    Match companies that have at least one valid identifiers accordingly to the country (e.g. vat or taxId for Italian companies).

    Cannot be used when filtering on multiple countries.

  • lists array Private parameter

    Search via already known Atoka List IDs.

    Accepts multiple values, separated with , (comma) char.

  • listsMatch string,
    default is "any"     Private parameter

    Decide whether to match companies contained in any of the lists (logic OR), or in all the lists (logic AND) specified with the lists parameter.

    Choose only one among:

    • any
    • all

  • listsExclude array Private parameter

    Exclude results via already known Atoka List IDs.

    Accepts multiple values, separated with , (comma) char.

  • name string base

    Will lookup provided text in company name.

  • namePrefix string base

    Will lookup provided text at the beginning of company name.

  • nameTag boolean,
    default is false

    Whether to highlight name search results' matches or not. Valid only if namePrefix or name is passed.

  • signs string Private parameter base

    Match companies whose signs matches given query input.

    Note: we only show the first 20 signs available in the API response. The signs output order is fixed, therefore is not related to the relevance with the given query

  • ageMin integer base

    Match companies older than the specified amount of months (based on value of founded field).

    If you need to exclude all companies with unknown establishment date, just pass this parameter and set it to zero (ageMin=0).

    Mutually exclusive with foundedFrom and foundedTo parameters: they cannot be used together.

    When used with ageMax, if the value of both filters is X, only companies founded exactly X months ago are returned (with precision of one day).

    Use a number bigger than 0.

  • ageMax integer base

    Match companies not older than the specified amount of months (based on value of founded field).

    Also excludes all companies for which the date of establishment is unknown.

    Mutually exclusive with foundedFrom and foundedTo parameters: they cannot be used together.

    When used with ageMin, if the value of both filters is X, only companies founded exactly X months ago are returned (with precision of one day).

    Use a number bigger than 0.

  • ageUnknown boolean base

    Match all companies with known (ageUnknown=false) or unknown (ageUnknown=true) age.

    When set to true and combined with ageMin and/or ageMax, matches companies with age in the specified range OR unknown.

  • foundedFrom string base

    Match companies founded in or after the given date.

    Mutually exclusive with ageMin and ageMax parameters: they cannot be used together.

  • foundedTo string base

    Match companies founded in or before the given date.

    Mutually exclusive with ageMin and ageMax parameters: they cannot be used together.

  • ageYearMin integer base

    Match companies older than the specified amount of years (based on value of foundedYear field).

    If you need to exclude all companies with unknown establishment date, just pass this parameter and set it to zero (ageYearMin=0).

    Mutually exclusive with foundedYearFrom and foundedYearTo parameters: they cannot be used together.

    Use a number bigger than 0.

  • ageYearMax integer base

    Match companies not older than the specified amount of years (based on value of foundedYear field).

    Also excludes all companies for which the date of establishment is unknown.

    Mutually exclusive with foundedYearFrom and foundedYearTo parameters: they cannot be used together.

    Use a number bigger than 0.

  • foundedYearFrom integer base

    Match companies founded in or after the given year.

    Mutually exclusive with ageYearMin and ageYearMax parameters: they cannot be used together.

  • foundedYearTo integer base

    Match companies founded in or before the given year.

    Mutually exclusive with ageYearMin and ageYearMax parameters: they cannot be used together.

  • insolvencyProceedings array base

    Match companies with one of these insolvency proceedings.

    You can use the Insolvency Proceedings service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • insolvencyProceedingsExclude array base

    Match companies that don't have any of these insolvency proceedings.

    You can use the Insolvency Proceedings service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • types array Private parameter base

    High level classification of legal type of business.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • soletrader
    • limited
    • partnership
    • others

    THIS FEATURE IS NOT IMPLEMENTED, YET. If you need it, just get in touch with us at sales@atoka.io

  • legalForms array base

    Filter by legal form of business (country specific).

    You can use the Legal Forms service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • legalFormsExclude array base

    Exclude by legal form of business (country specific).

    You can use the Legal Forms service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • legalClasses array base

    Filter by class of legal form of business (country specific).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • Società Di Capitale
    • Società Di Persone
    • Impresa Individuale
    • Altre Forme

  • legalClassesExclude array base

    Exclude by class of legal form of business (country specific).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • Società Di Capitale
    • Società Di Persone
    • Impresa Individuale
    • Altre Forme

  • nace array base

    Match companies with NACE activity code starting with provided value (for example: 68 matches 68 and also 68.01).

    Mutually exclusive with naceExclude parameter: they cannot be used together.

    You can use the NACE service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • naceExclude array base

    Exclude companies with NACE activity code starting with provided value (for example: 68 will exclude 68 and also 68.01).

    Mutually exclusive with nace parameter: they cannot be used together.

    Accepts multiple values, separated with , (comma) char.

  • pmiSizes array base

    Match companies whose PMI size is one of the given values.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • micro
    • small
    • medium
    • * matches for any value

  • pmiSizesExclude array base

    Match companies whose PMI size is not one of the given values.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • micro
    • small
    • medium
    • * matches for any value

  • pmiSizesIncludeAll boolean,
    default is false     base

    A filter modifier for switching the include definition from "broad" (true) to "narrow" (false).

  • groupIds array Private parameter groups

    Comma separated list of group IDs to filter. Return companies belonging to one of the groups (identified by Group IDs from the list).

    Accepts multiple values, separated with , (comma) char.

  • groupIdsExclude array Private parameter groups

    Comma separated list of group IDs to exclude. Return companies belonging to none of the groups (identified by Group IDs from the list).

    Accepts multiple values, separated with , (comma) char.

  • noReaActivities array Private parameter base

    Match companies with one of these no rea activities

    You can use the No Rea Activities service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • noReaActivitiesExclude array Private parameter base

    Match companies that don't have any of these no rea activities

    You can use the No Rea Activities service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • noReaForms array Private parameter base

    Match companies with one of these no rea form

    You can use the No Rea Forms service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • noReaFormsExclude array Private parameter base

    Match companies that don't have any of these no rea forms

    You can use the No Rea Forms service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • cigsStates array cigs

    Match companies whose CIGS measure is one of the given statuses.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • approving
    • active
    • none
    • active-in-the-past
    • * matches for any value

  • cigsStatesExclude array cigs

    Match companies whose CIGS measure is not one of the given states.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • approving
    • active
    • none
    • active-in-the-past
    • * matches for any value

  • cigsReasons array cigs

    Match companies whose CIGS measure is one of the given reasons.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • S
    • CA
    • R
    • EC
    • PC
    • O

  • cigsReasonsExclude array cigs

    Match companies whose CIGS measure is not one of the given reasons.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • S
    • CA
    • R
    • EC
    • PC
    • O
curl -G "https://api.atoka.io/v2/companies" -d "countries=it" -d "regNumbers=02241890223" -d "ageMin=6" -d "ageMax=24" -d "foundedTo=2012-02-12" -d "ageYearMin=2" -d "ageYearMax=6" -d "foundedYearFrom=2020" -d "foundedYearTo=2022" -d "nace=68"

Italy only

These filters can be used only for searches whithin italian companies: usage of any of these parameters also implies countries=it.

If used together with other country specific parameters, or when searching in more than one country (for example: countries=it,fr) will raise an error.

Parameters

  • cervedIds array Private parameter

    Return companies with matching Cerved IDs.

    Accepts multiple values, separated with , (comma) char.

  • cciaa array base

    Search for company using Codice CCIAA, local registry office branch code.

    The only possibility right now is to match for existence of CCIAA: we'll soon enable more fine grained filters. If you need it, just get in touch with us at sales@atoka.io.

    Possible values are:

    • * matches for any CCIAA

    Accepts multiple values, separated with , (comma) char.

  • rea string base

    Search for company using Numero REA, local registry office registration number.

    Must be used together with cciaa.

    THIS FEATURE IS NOT IMPLEMENTED, YET. If you need it, just get in touch with us at sales@atoka.io

  • gov boolean base

    Match companies that are a public administration.

  • govTypes array base

    Filter on certain kind of government related companies.

    For values containing , (comma) char, please wrap them with double apices "

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * matches for any kind of company
    • Istituti di Istruzione Statale di Ogni Ordine e Grado
    • Comuni e loro Consorzi e Associazioni
    • Federazioni Nazionali, Ordini, Collegi e Consigli Professionali
    • Unioni di Comuni e loro Consorzi e Associazioni
    • Aziende Pubbliche di Servizi alla Persona
    • Altri Enti Locali
    • Gestori di Pubblici Servizi
    • Comunita' Montane e loro Consorzi e Associazioni
    • Consorzi tra Amministrazioni Locali
    • Aziende Sanitarie Locali
    • Parchi Nazionali, Consorzi e Enti Gestori di Parchi e Aree Naturali Protette
    • Camere di Commercio, Industria, Artigianato e Agricoltura e loro Unioni Regionali
    • Aziende Ospedaliere, Aziende Ospedaliere Universitarie, Policlinici e Istituti di Ricovero e Cura a Carattere Scientifico Pubblici
    • Automobile Club Federati ACI
    • Istituzioni per l'Alta Formazione Artistica, Musicale e Coreutica - AFAM
    • Province e loro Consorzi e Associazioni
    • Enti Pubblici Non Economici
    • Enti Pubblici Produttori di Servizi Assistenziali, Ricreativi e Culturali
    • Universita' e Istituti di Istruzione Universitaria Pubblici
    • Enti di Regolazione dei Servizi Idrici e o dei Rifiuti
    • Regioni, Province Autonome e loro Consorzi e Associazioni
    • Consorzi di Bacino Imbrifero Montano
    • Agenzie ed Enti per il Turismo
    • Societa' in Conto Economico Consolidato
    • Enti e Istituzioni di Ricerca Pubblici
    • Agenzie, Enti e Consorzi Pubblici per il Diritto allo Studio Universitario
    • Aziende e Consorzi Pubblici Territoriali per l'Edilizia Residenziale
    • Consorzi Interuniversitari di Ricerca
    • Agenzie ed Enti Regionali per la Formazione, la Ricerca e l'Ambiente
    • and other 20 options... (see the whole list)

  • govTypesExclude array base

    Filter excluding on certain kind of government related companies.

    For values containing , (comma) char, please wrap them with double apices "

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * matches for any kind of company
    • Istituti di Istruzione Statale di Ogni Ordine e Grado
    • Comuni e loro Consorzi e Associazioni
    • Federazioni Nazionali, Ordini, Collegi e Consigli Professionali
    • Unioni di Comuni e loro Consorzi e Associazioni
    • Aziende Pubbliche di Servizi alla Persona
    • Altri Enti Locali
    • Gestori di Pubblici Servizi
    • Comunita' Montane e loro Consorzi e Associazioni
    • Consorzi tra Amministrazioni Locali
    • Aziende Sanitarie Locali
    • Parchi Nazionali, Consorzi e Enti Gestori di Parchi e Aree Naturali Protette
    • Camere di Commercio, Industria, Artigianato e Agricoltura e loro Unioni Regionali
    • Aziende Ospedaliere, Aziende Ospedaliere Universitarie, Policlinici e Istituti di Ricovero e Cura a Carattere Scientifico Pubblici
    • Automobile Club Federati ACI
    • Istituzioni per l'Alta Formazione Artistica, Musicale e Coreutica - AFAM
    • Province e loro Consorzi e Associazioni
    • Enti Pubblici Non Economici
    • Enti Pubblici Produttori di Servizi Assistenziali, Ricreativi e Culturali
    • Universita' e Istituti di Istruzione Universitaria Pubblici
    • Enti di Regolazione dei Servizi Idrici e o dei Rifiuti
    • Regioni, Province Autonome e loro Consorzi e Associazioni
    • Consorzi di Bacino Imbrifero Montano
    • Agenzie ed Enti per il Turismo
    • Societa' in Conto Economico Consolidato
    • Enti e Istituzioni di Ricerca Pubblici
    • Agenzie, Enti e Consorzi Pubblici per il Diritto allo Studio Universitario
    • Aziende e Consorzi Pubblici Territoriali per l'Edilizia Residenziale
    • Consorzi Interuniversitari di Ricerca
    • Agenzie ed Enti Regionali per la Formazione, la Ricerca e l'Ambiente
    • and other 20 options... (see the whole list)

  • govCodes array base

    Filter on certain kind of government related companies by IPA code.

    Accepts multiple values, separated with , (comma) char.

  • ateco array base

    Match companies with ATECO 2007 activity code starting with provided value (for example: 12.34 matches 12.34.56 and also 12.34.87.90).

    You can use the ATECO service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • atecoExclude array base

    Exclude companies with ATECO activity code starting with provided value (for example: 47.11 will exclude 47.11.01 and also 47.11.55.07).

    Accepts multiple values, separated with , (comma) char.

  • atecoInfoCamere array base

    Match companies ATECO 2007 activity code starting with provided value (for example: 12.34 matches 12.34.56 and also 12.34.87.90).

    Differently from the ateco parameter, which works on reclassified ATECOs that should better represent the activity of the company, with this you can filter on ATECO codes that companies officially submitted to InfoCamere.

    You can use the ATECO service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • atecoInfoCamereExclude array base

    Exclude companies ATECO 2007 activity code starting with provided value (for example: 12.34 matches 12.34.56 and also 12.34.87.90).

    Differently from the atecoExclude parameter, which works on reclassified ATECOs that should better represent the activity of the company, with this you can exclude on ATECO codes that companies officially submitted to InfoCamere.

    Accepts multiple values, separated with , (comma) char.

  • atecoInfoCamereMatch string,
    default is "primary"     Private parameter base

    Decide whether to filter on all ATECO InfoCamere or only on the primary one.

    Choose only one among:

    • primary
    • * matches for any value

  • startup boolean base

    Match companies officially registered as Startup Innovativa.

  • agcmRatingMin number Private parameter base

    Match companies with at least the specified value for AGCM rating.

    The value is represented as "<nr_stars>.<nr_plus>"

    If you need to exclude all companies with unknown AGCM rating, just pass this parameter and set it to zero (agcmRatingMin=0)

    When used with agcmRatingMax, if the value of both filters is X, only companies with exactly X rating are returned.

    Use a number between 0 and 3.

  • agcmRatingMax number Private parameter base

    Match companies with at most the specified value for AGCM rating.

    The value is represented as "<nr_stars>.<nr_plus>"

    Use a number between 0 and 3.

  • fiduciaria boolean Private parameter shares

    Match fiduciaria companies.

  • soaCertificationCategories array soaCertifications

    Filter on SOA certifications having this category code and classification

    Accepts multiple values, separated with , (comma) char.

  • soaCertificationCategoriesExclude array soaCertifications

    Filter on SOA certifications to exclude this category code and classification

    Accepts multiple values, separated with , (comma) char.

  • noRea boolean base

    Match companies that are not registered to the italian Chamber of Commerce .

  • sircSectors array Private parameter base

    Match companies with SIRC sector code starting with provided value (for example: A.B will match A.B.01 and and also A.B.02).

    Accepts multiple values, separated with , (comma) char.

  • sircSectorsExclude array Private parameter base

    Excludes companies with SIRC sector code starting with provided value (for example: A.B will exclude A.B.01 and and also A.B.02).

    Accepts multiple values, separated with , (comma) char.

  • marketSectors array Private parameter base

    Match companies with the provided Market Sector / division / industry code.

    You can use the Market Sectors service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • marketSectorsExclude array Private parameter base

    Excludes companies with the provided Market Sector / division / industry code.

    You can use the Market Sectors service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • marketSectorsMatch string,
    default is "any"     Private parameter base

    Decide whether to match companies that have any of the market sectors (logic OR), or in all the sectors (logic AND) specified with the marketSectors parameter.

    Choose only one among:

    • any
    • all
curl -G "https://api.atoka.io/v2/companies" -d "cciaa=*" -d "gov=true" -d "govTypes=*" -d "govTypesExclude=*" -d "govCodes=c_l378" -d "ateco=62.09.09" -d "atecoInfoCamere=62.09.09" -d "atecoInfoCamereExclude=62.09.09" -d "atecoInfoCamereMatch=primary" -d "startup=true" -d "fiduciaria=true" -d "soaCertificationCategories=*" -d "soaCertificationCategoriesExclude=*" -d "noRea=true"

Economics

Use these filters to find companies with economics data matching selected criteria.

Parameters

  • employeesMin integer economics
     economicsLite

    Match companies with number of employees greater than the specified amount.

    Use a number bigger than 0.

  • employeesMax integer economics
     economicsLite

    Match companies with number of employees smaller than the specified amount.

    Use a number bigger than 0.

  • employeesUnknown boolean economics

    Match all companies with known (employeesUnknown=false) or unknown (employeesUnknown=true) number of employees.

    When set to true and combined with employeesMin and/or employeesMax, matches companies with number of employees in the specified range OR unknown.

  • employeesSource string economics
     economicsLite

    With this filter it is possible to determine the value on which employeesMin and employeesMax are based. By default only the official employees number is considered, but it is possible to take in consideration also the estimated number for those companies where the official number is not available.

    employeesSource=* is not available for italian companies.

    Choose only one among:

    • official
    • * matches for any value

  • employeesRanges array economicsLite

    Match companies with number of employees within one of the given ranges; employees ranges are predefined and cannot be personalized:

    • 0 - 2 (set employeesRanges=0)
    • 2 - 10 (set employeesRanges=2)
    • 10 - 50 (set employeesRanges=10)
    • 50 - 250 (set employeesRanges=50)
    • 250 - * (set employeesRanges=250)

    This filter is not supported for Italy and United Kingdom, and cannot be used in combination with other employees filters

    Accepts multiple values, separated with , (comma) char.

  • seasonal boolean Private parameter economics

    Match seasonal companies.

  • revenueMin number economics
     economicslite

    Match companies with at least this revenue.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

  • revenueMax number economics
     economicslite

    Match companies with revenue lower than specified amount.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

  • revenueUnknown boolean economics
     economicslite

    Match all companies with known (revenueUnknown=false) or unknown (revenueUnknown=true) revenue.

    When set to true and combined with revenueMin and/or revenueMax, matches companies with revenue in the specified range OR unknown.

  • revenueSource string economics
     economicslite

    With this filter it is possible to determine the value on which revenueMin and revenueMax are based. By default only the official revenue is considered, but it is possible to take in consideration also the estimated revenue for those companies where the official revenue is not available, or a value that represents the range.

    revenueSource == * is not available for italian companies.

    Choose only one among:

    • official
    • * matches for any value

  • revenueTrends array economics

    Match companies on revenue trend (based last two officially registered company revenue records).

    Can be decreasing (< -5%), stable (btw -5% and +5%), increasing (>= 5%) or incalculable if the value is not available

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • increasing
    • stable
    • decreasing
    • incalculable

  • revenueRanges array economicsLite

    Match companies with latest known revenue within one of the given ranges; revenue ranges are predefined and cannot be personalized:

    • 0 - 500000 (set revenueRanges=0)
    • 500000 - 1000000 (set revenueRanges=500000)
    • 1000000 - 2000000 (set revenueRanges=1000000)
    • 2000000 - 3000000 (set revenueRanges=2000000)
    • 3000000 - 5000000 (set revenueRanges=3000000)
    • 5000000 - 10000000 (set revenueRanges=5000000)
    • 10000000 - 25000000 (set revenueRanges=10000000)
    • 25000000 - 50000000 (set revenueRanges=25000000)
    • 50000000 - 100000000 (set revenueRanges=50000000)
    • 100000000 - 250000000 (set revenueRanges=100000000)
    • 250000000 + (set revenueRanges=250000000)

    The currency depends on the countries parameter. This filter is not supported for Italy and United Kingdom, and cannot be used in combination with other revenue filters

    Based on latest officially registered company revenue records.

    Accepts multiple values, separated with , (comma) char.

  • ebitdaMin integer Private parameter economics

    Match companies with at least this EBITDA

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

  • ebitdaMax integer Private parameter economics

    Match companies with EBITDA lower than specified amount.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

  • ebitdaUnknown boolean Private parameter economics

    Match all companies with known (ebitdaUnknown=false) or unknown (ebitdaUnknown=true) EBITDA.

    When set to true and combined with ebitdaMin and/or ebitdaMax, matches companies with EBITDA in the specified range OR unknown.

    Based on latest officially registered company revenue records.

  • assetsMin number economics

    Match companies with at least these assets.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

    If you need to exclude for all companies with unknown assets, just set this parameter equal to zero (assetsMin=0).

    For Italian companies a special agreement with our data provider is required to use this filter.

  • assetsMax number economics

    Match companies with assets lower than the specified amount.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

    For Italian companies a special agreement with our data provider is required to use this filter.

  • balanceSheets array Private parameter balanceSheets

    Match companies with balance sheets data that match the given query.

    You can provide multiple filters on many balance sheets items, and a company is valid only if it satisfies all the conditions given in input. Each filter should be a valid JSON object following this format:

    {
  "field": "<balance_sheet_field_name>",
  "min": <min_value>,
  "max": <max_value>,
  "currency": "<currency>"
}

    Only field and one of min or max are mandatory for each filter specified. If you provide a value for min, the API will return the companies with that balance sheet item value greater or equal to the given value, and similarly the max value will match companies with field value smaller or equal to the given value.

    The list of allowed field names is:

    Field Description (IT) Description (EN)
    EBIT Utile corrente ante gestione finanziaria Current profit before interest and taxes
    EBITDA Utili prima degli interessi, delle imposte, del deprezzamento e degli ammortamenti Earnings before interest, taxes, depreciation and amortization
    active Attivo Active
    adjustedProfitBeforeTaxes Risultato rettificato ante imposte Adjusted profit before taxes
    advancesReceived Anticipi da clienti e fatture sospese Advances received
    bankLoansLongTerm Debiti finanziari verso banche oltre esercizio successivo Bank loans; long term
    bankLoansShortTerm Debiti finanziari verso banche entro esecizio successivo Bank loans; short term
    cashAndCashEquivalents Liquidità Cash and cash equivalents
    cashFlow Flusso di cassa Cash flow
    cashOnHandsAndBanks Disponibilità liquide Cash on hands and banks
    changesInInventoriesOfRawMaterialsAndConsumables Variazione rimanenze materie prime, sussidiarie, merci Changes in inventories of raw materials and consumables
    changesInStockOfFinishedGoodAndWorkInProgress Variazione rimanenze immobiliari Changes in stok of finished good and work in progress
    consolidatedProfitLoss Risultato netto di consolidato Consolidated profit (loss)
    consolidatedRoe ROE consolidato Consolidated ROE - return on equity
    currentProfit Utile corrente Current profit
    currentProfitBeforeFinancialCharges Utile corrente ante oneri finanziari Current profit before financial charges
    deferredChargesAndRemainingAssetsShortTerm Altre attività entro esercizio successivo Deferred charges and remaining assets; short term
    depreciationOfIntangibleAssets Ammortamenti immbilizzazioni immateriali Depreviation of intangible assets
    depreciationOfTangibleFixedAssets Ammortamenti immobilizzazioni in uso proprio Depreciation on tangible fixed assets
    dividendsOnProfitOfTheYear Distribuzioni e destinazioni deliberate Dividends on profit of the year
    equity Patrimonio netto Equity
    financeCharges Interessi passivi Finance charges
    financialAndOtherAssetsLongTerm Attivo finanziario immobilizzato Financial and other assets; long term
    financialAssetsShortTerm Attività finanziarie Financial assets; short term
    financialIncome Proventi finanziari Financial income
    financialsReceivablesShortTerm Crediti finanziari verso terzi Financial receivables; short term
    fixedAssets Totale attivo immobilizzato Fixed assets
    grossOperatingProfit MOL - margine operativo lordo Gross operating profit
    grossOperatingProfitGrowthRate Variazione % MOL - margine operativo lordo Gross operating profit growth rate
    grossTangibleAssets Immobilizzazioni materiali lorde Gross tangible assets
    incomeTaxPaid Imposte nette sul reddito Income tax paid
    intangibleAssets Immobilizzazioni immateriali Intangible assets
    inventories Rimanenze Inventories
    investmentsAndShares Immobilizzazioni in partecipazioni Investments and shares
    issuedCapital Capitale Issued capital
    longTermDebts Debiti consolidati Long-term debts
    longTermLiabilities Totale capitali permanenti Long-term liabilities
    marginBeforeFinancialChargesNetRevenues Margine ante oneri finanziari / ricavi netti Margin before financial charges/net revenues
    netAdjustedProfit Risultato netto rettificato Net adjusted profit
    netFinancialCosts Saldo netto oneri-proventi e perdite finanziarie Net financial costs
    netFinancialPosition PFN - posizione finanziaria netta Net financial position
    netOperatingProfit MON - margine operativo netto Net operating profit
    netWorkingCapital Capitale circolante netto Net working capital
    operatingAddedValue Valore aggiunto operativo Operating added value
    operatingProvisionsForRisksAndCharges Accantonamenti operativi per rischi e oneri (netti) Provisions for risks and charges
    otherFinancialCreditorsLongTerm Debiti finianziari verso altri finanziatori oltre esercizio successivo Other financial creditors; long term
    otherFinancialCreditorsShortTerm Debiti finanziari verso altri finanziatori entro esercizio successivo Other financial creditors; short term
    otherLiabilitiesShortTerm Altre passività Other liabilities; short term
    otherOperatingCosts Costi per servizi e godimento beni terzi Other operating costs
    otherOperatingIncomeOrExpenses Salto ricavi/oneri diversi Other operating income/expenses
    otherReceivablesShortTerm Crediti diversi entro esercizio successivo Other receivables; short term
    otherReserves Altre riserve Other reserves
    paymentsOnAccountAndAssetsInConstruction Immobilizzazioni materiali in corso Payments on account and assets in construction
    postEmploymentBenefitObligations Fondo trattamento fine rapporto oltre esercizio successivo Post employment benefit obligations
    profitLossOfTheYear Utile (perdita) dell'esercizio Profit (loss) of the year
    provisionsForRisksAndCharges Fondi per rischi ed oneri oltre esercizio successivo Provisions for risks and charges
    purchasesOfRawMaterialsAndConsumables Acquisti netti Purchases of raw materials and consumable
    receivablesTurnover Giorni credito clienti Receivable turnover in days
    reserves Riserve nette Reserves
    returnOnAssets ROA - Ritorno sulle attività ROA - return on assets
    returnOnEquity ROE - Ritorno sul capitale proprio ROE - return on equity
    returnOnInvestedCapital ROI - Ritorno sugli investimenti ROI - return on invested capital
    revenue Fatturato Revenue
    revenueTrend Trend fatturato Revenue trend from the last economics record
    sharePremium Riserva sovrapprezzo azioni Share premium
    shortTermAssets Totale attivo a breve termine Short term assets
    shortTermLiabilities Totale passivo a breve termine Short term liabilities
    staffCosts Costo del lavoro Staff costs
    tangibleAssets Immobilizzazioni materiali in esercizio Tangible assets
    taxesOnWealthAnOtherTaxes Imposte patrimoniali e diverse Taxes on wealth and other taxes
    thirdPartyAssets Patrimonio di terzi Third party assets
    thirdPartyProfitLoss Utile (perdita) di terzi Third party profit (loss)
    totalLiabilities Passivo Total liabilities
    totalOperatingRevenues Valore della produzione Total operating revenues
    tradeCreitorsShortTerm Debiti verso fornitori Trade creditors; short term
    tradeReceivables Crediti commerciali entro esercizio successivo Trade receivables; short term
    valueAdjustmentsOnCurrentAssets Svalutazioni del circolante Value adjustments on current assets
    consolidatedRevenue Ricavi consolidati Consolidated revenue

    To specifiy multiple values, repeat the parameter.

    SCHEMA:
    {
    "field": "foo",
    "min": 0.42,
    "max": 0.42
    }

  • consolidated string,
    default is "false"     Private parameter balanceSheets
     balanceSheetsIV

    Shows only consolidated balance sheets (contained in the package balanceSheets or balanceSheetsIV)

    Choose only one among:

    • true
    • false
    • unknown
    • * matches for any value

  • balanceSheetsYears array Private parameter balanceSheets
     balanceSheetsIV

    Filters balanceSheets and balanceSheetsIV packages content to only balance sheets data from the given years

    Accepts multiple values, separated with , (comma) char.

  • balanceSheetsCodes array Private parameter balanceSheets
     balanceSheetsIV

    Filters balanceSheets and balanceSheetsIV packages content to list only the given fields; you will need to provide each field code to specify what you need. This parameter can help you drastically reduce the payload returned by the API, making it considerably faster to serve the response.

    Accepts multiple values, separated with , (comma) char.

  • public boolean economics

    Match companies that are listed in the stock exchange

  • ebitdaMargin array Private parameter economics

    Match companies whose EBITDA margin label is one of the given values.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • less than -50%
    • from -50% to 0%
    • from 0% to 5%
    • from 5% to 10%
    • from 10% to 15%
    • from 15% to 20%
    • from 20% to 30%
    • from 30% to 40%
    • from 40% to 50%
    • from 50% to 70%
    • more than 70%
    • * matches for any value

  • groupConsolidatedRevenueMin number groups

    Match companies that belong to groups with at least this consolidated revenue.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

  • groupConsolidatedRevenueMax number groups

    Match companies that belong to groups with at most this consolidated revenue.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

  • groupComputedRevenueMin number groups

    Match companies that belong to groups with at least this computed revenue.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

  • groupComputedRevenueMax number groups

    Match companies that belong to groups with at most this computed revenue.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

  • groupComputedTotalOperatingRevenueMin number Private parameter groups

    Match companies that belong to groups with at least this total operating revenue.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

  • groupComputedTotalOperatingRevenueMax number Private parameter groups

    Match companies that belong to groups with at most this total operating revenue.

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

  • groupEmployeesMin number Private parameter groups

    Match companies that belong to groups with at least this number of employees.

  • groupEmployeesMax number Private parameter groups

    Match companies that belong to groups with at most this number of employees.

curl -G "https://api.atoka.io/v2/companies" -d "employeesMin=100" -d "employeesMax=1000" -d "seasonal=true" -d "revenueMin=50000" -d "ebitdaMin=50000" -d "assetsMin=50000" -d "balanceSheets={"field": "ebitda", "min": 10000, "year": 2015}" -d "public=true"

Indicators

These filters allow you to search by companies based on some indicators.

Parameters

  • negativities boolean Private parameter cervedIndicators

    Match companies that have some negative events (Italy only); the kind of event depends on the company type.

    For società:

    For ditte:

    • protesti on the company itself or on any connected person;
    • pregiudizievoli on the company itself or on any connected person;
    • procedure concorsuali on the company ifself or on any connected one;
    • crisis events on the company;

    For non-registered companies:

  • cgrC4 array Private parameter cervedIndicators

    Match companies that have the given cgr C4 score values. The CgrC4 is a score computed over negative events for each company and its related shareholders and companies

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • 0.0
    • 1.0
    • 2.0
    • 3.0
    • 4.0

  • cgsValueMin integer Private parameter cervedIndicators

    Match companies with cgs equal or greater than the specified amount.

    Use a number between 0 and 100.

  • cgsValueMax integer Private parameter cervedIndicators

    Match companies with cgs equal or smaller than the specified amount.

    Use a number between 0 and 100.

  • cgsValueUnknown boolean Private parameter cervedIndicators

    Match all companies with known (cgsValueUnknown=false) or unknown (cgsValueUnknown=true) cgs.

    When set to true and combined with cgsValueMin and/or cgsValueMax, matches companies with cgs in the specified range OR unknown.

  • reliabilityScoreClass array atokaIndicators

    Match companies that have the given Reliability Score class value. The Reliability Score is a predictive measurement of the health of a company; the score measures the likelihood of a company to not fail over the next 12 months.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • A
    • B
    • C
    • D
    • E
    • * matches for any value

  • covid19BanksCgs array covid19

    Match companies with covid19 cerved score (for banks) is in the given categories.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10

  • covid19BanksCgsHard array covid19

    Match companies with covid19 cerved score (for banks) is in the given categories.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10

  • covid19BanksCgsSoft array covid19

    Match companies with covid19 cerved score (for banks) is in the given categories.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10

  • covid19CorporateCgs array covid19

    Match companies with covid19 cerved score (for corporates) is in the given categories.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8

  • covid19CorporateCgsHard array covid19

    Match companies with covid19 cerved score (for corporates) is in the given categories.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8

  • covid19CorporateCgsSoft array covid19

    Match companies with covid19 cerved score (for corporates) is in the given categories.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8

  • covid19SectorTrendHard array covid19

    Match companies with covid19 sector trend in the given categories (hard scenario).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • Forte contrazione
    • Contrazione
    • Leggera contrazione
    • Stabile
    • Crescita
    • Forte crescita

  • covid19SectorTrendSoft array covid19

    Match companies with covid19 sector trend in the given categories (soft scenario).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • Forte contrazione
    • Contrazione
    • Leggera contrazione
    • Stabile
    • Crescita
    • Forte crescita
curl -G "https://api.atoka.io/v2/companies" -d "cgsValueMin=100" -d "cgsValueMax=1000"

Location

Use these filters to find companies located in a specific place, either by name, or within a distance from passed coordinates.

Parameters

  • locationsMin integer locations

    Match companies with at least this number of locations.

    This filter works on the totalCount field, therefore takes into account both headquarters and secondary locations.

    Use a number bigger than 0.

  • locationsMax integer locations

    Match companies with at most this number of locations.

    This filter works on the totalCount field, therefore takes into account both headquarters and secondary locations.

    Use a number bigger than 0.

  • anyAddress boolean,
    default is false     locations

    By default, location based filters apply only to registered address.

    If you set this parameter to true, they will be applied to any known company location, not just to the officially registered one.

  • macroregions array base
     locations

    Match companies with at least one location in this macro-region.

    Accepts multiple values, separated with , (comma) char.

  • macroregionsExclude array base
     locations

    Match companies with no location in this macro-region.

    Accepts multiple values, separated with , (comma) char.

  • regions array base
     locations

    Match companies with at least one location in this region.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • regionsExclude array base
     locations

    Match companies with no location in this region.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • provinces array base
     locations

    Match companies with at least one location in this province.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • provincesExclude array base
     locations

    Match companies with no location in this province.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • municipalities array base
     locations

    Match companies with at least one location in this municipality.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • municipalitiesExclude array base
     locations

    Match companies with no location in this municipality.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • postcodes array base
     locations

    Match companies with at least one location having specified postcodes.

    Accepts multiple values, separated with , (comma) char.

  • postcodesExclude array base
     locations

    Match companies with no location having specified postcodes.

    Accepts multiple values, separated with , (comma) char.

  • lat number base
     locations

    Match companies located within a certain distance from the point identified by specific geographic coordinates.

    Must be used together with lon and distance.

    Each item in response will have inside package locations the property distance, representing the distance from the input coordinates

    Use a number between -90 and 90.

  • lon number base
     locations

    Match companies located within a certain distance from the point identified by specific geographic coordinates.

    Must be used together with lat and distance.

    Each item in response will have inside package locations the property distance, representing the distance from the input coordinates

    Use a number between -180 and 180.

  • distance integer base
     locations

    Match companies located within a certain distance from the point identified by specific geographic coordinates.

    It's expressed in meters.

    Must be used together with lat and lon.

    Each item in response will have inside package locations the property distance, representing the distance from the input coordinates

    Use a number bigger than 0.

  • geoBound array base
     locations

    Match companies located within a certain bounding box. You should specify the geographic bounding box providing the coordinates of the top-left and bottom-right points.

    Coordinates must be provided separated by commas and in this order top (latitude), left (longitude), bottom (latitude), right (longitude).

    Accepts multiple values, separated with , (comma) char.

  • validDeliveryAddress boolean Private parameter base

    Match companies that have a registered address valid for delivery purposes, according to a comprehensive set of checks.

curl -G "https://api.atoka.io/v2/companies" -d "locationsMin=2" -d "locationsMax=10" -d "anyAddress=true" -d "lat=46.0804401" -d "lon=11.050316" -d "distance=30000"

Semantic Enrichment

What really sets our APIs apart is that all company information is distilled through our Semantic Analysis technologies (more at dandelion.eu), so that you can get well beyond traditional industry classifications.

As the base of our algorithms, we use a Knowledge Graph that currently uses the DBpedia Knowledge Graph, built on top of Wikipedia pages.

Parameters

  • entities array entities

    Include companies with matching entities.

    We currently support referencing Wikipedia/DBpedia entities, but in the future we'll extend to other Knowledge Graphs.

    You can pass either the full Wikipedia URI (https://it.wikipedia.org/wiki/Consulenza) or a shortcut made using just the language code, the colon char and the Wikipedia page title (it:Consulenza).

    In the latter form, if you omit the language selection prefix (it:), we'll look at the Accept-Language headers in your request, and decide accordingly. If even those are missing we'll use the value of countries parameter, or default to en if that is set to the default value *.

    You can also get all companies with entities extracted in a certain language using the special value it:*, en:* (or any of the supported languages: it, en, de, fr or pt).

    PLEASE NOTE: if you pass more than one entity at a time, they must be all in the same language (this is a temporary limitation that will be removed in the future).

    The entities fields are automatically extracted from several firm digital properties and documents such as the company websites, social accounts, statements of incorporations, etc. In atoka entities are displayed in the company details page under the property "Keywords" (or "Parole Chiave" in Italian version)

    You can use the Entities service to find possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • entitiesMatch string,
    default is "any"     Private parameter entities

    Decide whether company matches on any passed entity (logic OR), or whether presence of all of them is required to match (logic AND).

    Choose only one among:

    • any
    • all
curl -G "https://api.atoka.io/v2/companies" -d "entities=it:Consulenza,https://it.wikipedia.org/wiki/Direzione_aziendale"

Foreign Market

This section groups together the filters used inside the foreignMarket package.

Parameters

  • foreignMarketContinents array Private parameter foreignMarket

    Match companies with areas in the given continent, identified by its code. If you want to query this field by name, you should retrieve a continent code using the AdminDiv service.

    You can limit the query to official data only by means of the foreignMarketOfficial parameter.

    Accepts multiple values, separated with , (comma) char.

  • foreignMarketSubRegions array Private parameter foreignMarket

    Match companies with areas in the given sub-region, identified by its code. If you want to query this field by name, you should retrieve a sub-region code using the AdminDiv service.

    You can limit the query to official data only by means of the foreignMarketOfficial parameter.

    Accepts multiple values, separated with , (comma) char.

  • foreignMarketIntermediateRegions array Private parameter foreignMarket

    Match companies with areas in the given intermediate region, identified by its code. If you want to query this field by name, you should retrieve an intermediate region code using the AdminDiv service.

    You can limit the query to official data only by means of the foreignMarketOfficial parameter.

    Accepts multiple values, separated with , (comma) char.

  • foreignMarketStates array Private parameter foreignMarket

    Match companies with areas in the given state, identified by its code. If you want to query this field by name, you should retrieve a state code using the AdminDiv service.

    You can limit the query to official data only by means of the foreignMarketOfficial parameter.

    Accepts multiple values, separated with , (comma) char.

  • foreignMarketOfficial boolean Private parameter foreignMarket

    Match companies with areas coming from official sources only.

curl -G "https://api.atoka.io/v2/companies"

Notes to Accounts

This section groups together the filters used inside the notes to accounts package.

Parameters

  • hasProfitDistributionToShareholders boolean notesToAccounts

    Match companies that contain information, in the last notes to accounts available, about distributing profits to shareholders. This info is extracted from section "Proposta Destinazione Utili / Copertura Perdite" of the notes to accounts.

  • businessCategoriesGeneratingRevenue array notesToAccounts

    Match companies by business categories generating revenue, extracted from the last notes to accounts available for this company. Categories are read from the breakdown of net revenue by business category (in Italian "suddivisione dei ricavi delle vendite e delle prestazioni per categoria di attività").

    It is possible to query the list of possible categories by querying the Business Categories Generating Revenue API.

    Accepts multiple values, separated with , (comma) char.

  • businessCategoriesGeneratingRevenueExclude array notesToAccounts

    Exclude companies by business categories generating revenue, extracted from the last notes to accounts available for this company. Categories are read from the breakdown of net revenue by business category (in Italian "suddivisione dei ricavi delle vendite e delle prestazioni per categoria di attività").

    It is possible to query the list of possible categories by querying the Business Categories Generating Revenue API.

    Accepts multiple values, separated with , (comma) char.

  • notesToAccountsContent string notesToAccounts

    Match companies whose notes to accounts contain passed text.

  • notesToAccountsContentQuery string notesToAccounts

    Match companies whose notes to accounts match passed query.

  • notesToAccountsContentTag boolean,
    default is false     notesToAccounts

    Whether to highlight notesToAccountsContent search results' matches or not. Valid only if notesToAccountsContent is passed.

  • notesToAccountsContentTagStart string notesToAccounts

    Text that is prefixed to web content highlights. Valid only if notesToAccountsContent and notesToAccountsContentTag are passed.

    This parameter is deprecated. Please use tagStart instead

  • notesToAccountsContentTagEnd string notesToAccounts

    Text that is appended to web content highlights. Valid only if notesToAccountsContent and notesToAccountsContentTag are passed.

    This parameter is deprecated. Please use tagEnd instead 

curl -G "https://api.atoka.io/v2/companies" -d "hasProfitDistributionToShareholders=true" -d "businessCategoriesGeneratingRevenue=vendite merci" -d "businessCategoriesGeneratingRevenueExclude=vendite merci"

Public Funding

This section groups together the filters used inside the public funding package.

Parameters

  • publicFunding boolean publicFunding

    Match companies that we know received some public funding.

  • publicFundingCovidRelated boolean publicFunding

    Match companies that we know received some public funding due to Covid 19.

  • publicFundingReceivedNominalMin number publicFunding

    Match companies that received at least this amount in granted public fundings.

    When used in combination of publicFundingReceivedTheme the filter will consider only public fundings associated to the given theme.

    WARN: this behaviour is now deprecated; please use publicFundingReceivedNominalMinForTheme instead.

  • publicFundingReceivedNominalMax number publicFunding

    Match companies that received at most this amount from granted public fundings.

    When used in combination of publicFundingReceivedTheme the filter will consider only public fundings associated to the given theme.

    WARN: this behaviour is now deprecated; please use publicFundingReceivedNominalMinForTheme instead.

  • publicFundingReceivedTheme string publicFunding

    Match companies that were granted public funding associated to this theme.

    Choose only one among:

    • attractions
    • competitiveness
    • digitalAgenda
    • education
    • energy
    • environment
    • inclusion
    • occupation
    • PA
    • renovation
    • researchInnovation
    • transportation
    • unknown

  • publicFundingReceivedNominalMinForTheme number publicFunding

    Match companies that received at least this amount in granted public fundings, limited to the given theme.

    Must be used in combination with publicFundingReceivedTheme.

  • publicFundingReceivedNominalMaxForTheme number publicFunding

    Match companies that received at most this amount from granted public fundings, limited to the given theme.

    Must be used in combination with publicFundingReceivedTheme.

  • publicFundingGrantedFramework string publicFunding

    Match companies that were granted public funding associated to this framework.

    Choose only one among:

    • covid
    • deMinimis
    • deMinimisSieg
    • exemption
    • notification
    • sieg
    • ukraine
    • other

  • publicFundingGrossGrantEquivalentMin number publicFunding

    Match companies that received at least this amount in granted public fundings.

  • publicFundingGrossGrantEquivalentMax number publicFunding

    Match companies that received at most this amount from granted public fundings.

  • publicFundingGrossGrantEquivalentMinForFramework number publicFunding

    Match companies that received at least this amount in granted public fundings, limited to the given framework.

    Must be used in combination with publicFundingGrantedFramework.

  • publicFundingGrossGrantEquivalentMaxForFramework number publicFunding

    Match companies that received at most this amount from granted public fundings, limited to the given framework.

    Must be used in combination with publicFundingGrantedFramework.

  • publicFundingGrossGrantEquivalentDeMinimisLast3YearsMin number publicFunding

    Match companies that received at least this amount in granted public fundings, limited to the "De Minimis" framework, and only related to the last 3 financial years.

  • publicFundingGrossGrantEquivalentDeMinimisLast3YearsMax number publicFunding

    Match companies that received at most this amount in granted public fundings, limited to the "De Minimis" framework, and only related to the last 3 financial years.

  • publicFundingGrossGrantEquivalentDeMinimisLast3YearsUnknown boolean publicFunding

    Match all companies with known (publicFundingGrossGrantEquivalentDeMinimisLast3YearsUnknown=false) or unknown (publicFundingGrossGrantEquivalentDeMinimisLast3YearsUnknown=true) amount in granted public funding for the "De Minimis" framework in the last 3 financial years.

    When set to true and combined with publicFundingGrossGrantEquivalentDeMinimisLast3YearsMin and/or publicFundingGrossGrantEquivalentDeMinimisLast3YearsMax, matches companies with amount received in the specified range OR unknown.

  • publicFundingAvailableCovidMin number publicFunding

    Match companies with amount available for Covid-19 public fundings equal or greater than the specified amount.

  • publicFundingAvailableCovidMax number publicFunding

    Match companies with amount available for Covid-19 public fundings equal or smaller than the specified amount.

  • publicFundingDescriptionsContent string publicFunding

    Match companies whose public funding descriptions contain passed text.

  • publicFundingDescriptionsContentTag boolean,
    default is false     publicFunding

    Whether to highlight publicFundingDescriptionsContent search results' matches or not. Valid only if publicFundingDescriptionsContent is passed.

  • publicFundingDescriptionsContentTagStart string publicFunding

    Text that is prefixed to description content highlights. Valid only if publicFundingDescriptionsContent and publicFundingDescriptionsContentTag are passed.

    This parameter is deprecated. Please use tagStart instead

  • publicFundingDescriptionsContentTagEnd string publicFunding

    Text that is appended to description content highlights. Valid only if publicFundingDescriptionsContent and publicFundingDescriptionsContentTag are passed.

    This parameter is deprecated. Please use tagEnd instead

  • publicFundingAvailableCovid array publicFunding

    Match companies with amount available for Covid-19 public fundings by the given remaining capacity.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • emptyAvailability
    • partialAvailability
    • fullAvailability
    • * matches for any value
curl -G "https://api.atoka.io/v2/companies" -d "publicFunding=true" -d "publicFundingCovidRelated=true" -d "publicFundingReceivedNominalMin=100000" -d "publicFundingReceivedNominalMax=100000" -d "publicFundingReceivedTheme=occupation" -d "publicFundingReceivedNominalMinForTheme=100000" -d "publicFundingReceivedNominalMaxForTheme=100000" -d "publicFundingGrantedFramework=covid" -d "publicFundingGrossGrantEquivalentMin=100000" -d "publicFundingGrossGrantEquivalentMax=100000" -d "publicFundingGrossGrantEquivalentMinForFramework=100000" -d "publicFundingGrossGrantEquivalentMaxForFramework=100000" -d "publicFundingGrossGrantEquivalentDeMinimisLast3YearsMin=100000" -d "publicFundingGrossGrantEquivalentDeMinimisLast3YearsMax=100000" -d "publicFundingAvailableCovid=fullAvailability"

Real Estate

Filter Atoka companies using information about real estate they own.

Parameters

  • realEstateCategories array realestate

    Match companies having a real estate with this category code

    You can use the Cadastral Category service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * matches for any value
    • A/1
    • A/2
    • A/3
    • A/4
    • A/5
    • A/6
    • A/7
    • A/8
    • A/9
    • A/10
    • A/11
    • B/1
    • B/2
    • B/3
    • B/4
    • B/5
    • B/6
    • B/7
    • B/8
    • C/1
    • C/2
    • C/3
    • C/4
    • C/5
    • C/6
    • C/7
    • D/1
    • D/2
    • D/3
    • and other 29 options... (see the whole list)

  • realEstateCategoriesExclude array realestate

    Match companies not having a real estate with this category code

    You can use the Cadastral Category service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * matches for any value
    • A/1
    • A/2
    • A/3
    • A/4
    • A/5
    • A/6
    • A/7
    • A/8
    • A/9
    • A/10
    • A/11
    • B/1
    • B/2
    • B/3
    • B/4
    • B/5
    • B/6
    • B/7
    • B/8
    • C/1
    • C/2
    • C/3
    • C/4
    • C/5
    • C/6
    • C/7
    • D/1
    • D/2
    • D/3
    • and other 29 options... (see the whole list)
curl -G "https://api.atoka.io/v2/companies"

Custom Data

Filter Atoka using your own data.

These parameters let you filter company records using additional data that you provided!

Parameters

  • customData array customData

    Using this parameter you will be able to use your custom data imported in Atoka to filter the database.

    The parameter is a json object with this structure

    • customData (string): string identifier of your custom data collection
    • field (string): name of the field that you want to filter
    • unknown (bool): false will give you all the objects with this field populated (no matter the value), true will filter only the ones without any value
    • includes (list): a list of exact values for this field, can be either strings or numbers depending on the field datatype. The values will be combined using OR operator
    • ranges (list): available only for numeric and date fields. list of ranges, combined in or. Each range is represented as a json object with any of these properties: gt, gte, lt, lte.
    • excludes (list): a list of exact values to exclude for this field, can be either strings or numbers depending on the field datatype. The values will be combined using AND operator

    You can filter on more than one field by repeting the parameter for each filter you want to add. Filters on different fields will be combined in AND.

    To specifiy multiple values, repeat the parameter.

    SCHEMA:
    {
    "customData": "foo",
    "field": "foo",
    "includes": undefined,
    "excludes": undefined,
    "unknown": false,
    "ranges": [
    {
    "gt": undefined,
    "gte": undefined,
    "lt": undefined,
    "lte": undefined
    },
    ...
    ]
    }
curl -G "https://api.atoka.io/v2/companies" -d "customData={"customData": "data_id", "field": "field_name", "includes": ["my_value"]}"

Response

Through the autentication credentials (the token) you are given, we are able to adapt the data available in API responses to your specific needs.

Moreover, depending on your subscription plan, you'll be able to retrieve different levels of details from the API calls.

{
"items": [
{
"id": "6da785b3adf219770c9e",
"ids": [
"foo",
...
],
"active": false,
"cervedId": 1015245,
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)",
"country": "it",
"name": "ACME S.p.A.",
"baby": false,
"obfuscated": false,
"score": 42,
},
...
],
"facets": {
},
"geoClusters": [
{
"id": "foo",
"geoBound": [
0.42,
...
],
"lat": 0.42,
"lon": 0.42,
"count": 42
},
...
],
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}

Company Details

Show full details of a company.

By default we show all information available using all the data packages you subscribed to. Use the package parameter to fine tune the output format.

If you have special needs and want to further customize the data returned, we can adapt the output to your specific needs: just get in touch with us at sales@atoka.io.

https://api.atoka.io/v2/companies/{id}

Replace {id} with the Atoka Company ID you want details for (as returned by the [Company Search](#companies) or the [Company Match](#companies_match) API endpoints).

All requests must be properly authenticated.

Authentication

Parameters

  • token string required

    All requests must be properly authenticated; see the Authentication section for more info

curl -G "https://api.atoka.io/v2/companies/{id}"

Response

Using these parameters, you'll be able to customize the output you'll get from your search.

Parameters

  • allowExpensive array

    Some fields could expensive to be computed and returned; either they are computationally costly (like calling and external API), or they are charged extra fees, or both. Such fields must be explicitly enabled through this parameter.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • cervedIndicators.cgs
    • cervedIndicators.cgr
    • cervedIndicators.negativities
    • cervedIndicators.procurement
curl -G "https://api.atoka.io/v2/companies/{id}" -d "allowExpensive=cervedIndicators.cgs"

Data Packages

Differently from the Company Search API, by default here in the Company Details API we will return all the information you are allowed to see; this may become expensive, of course.

To avoid getting data you don't need, you can use the packages parameter to fine tune the results to the level your application actually requires; if you want to explicitly get all the data, feel free you use our preferred wildcard: packages=*.

Remember: your subscription gives you access to different levels of detail in data returned!

If you have special needs and want to further customize the data returned, we can adapt the output to your specific needs: just get in touch with us at sales@atoka.io.

Remember: your subscription gives you access to different levels of detail in data returned!

Parameters

  • packages array,
    default is *

    By using this parameter you can fine tune the results to the level of detail your application actually requires.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • atokaIndicators
    • base
    • cervedIndicators
    • contacts
    • covid19
    • economics
    • economicsLite
    • entities
    • foreignMarket
    • govcontracts
    • groups
    • locations
    • notesToAccounts
    • people
    • perimeters
    • publicFunding
    • realEstate
    • shares
    • socials
    • technologies
    • web
    • * use all the data packages you have an active subscription for
curl -G "https://api.atoka.io/v2/companies/{id}" -d "packages=*"

Response modifications

When packages is *, the response will be:

{
"item": {
"id": "6da785b3adf219770c9e",
"ids": [
"foo",
...
],
"active": false,
"cervedId": 1015245,
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)",
"country": "it",
"name": "ACME S.p.A.",
"baby": false,
"obfuscated": false,
"score": 42,
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}
curl -G "https://api.atoka.io/v2/companies/{id}" -d "packages=*"

Economics

Use these filters to change economics data returned for the company.

Parameters

  • consolidated string,
    default is "false"     Private parameter balanceSheets
     balanceSheetsIV

    Shows only consolidated balance sheets (contained in the package balanceSheets or balanceSheetsIV)

    Choose only one among:

    • true
    • false
    • unknown
    • * matches for any value

  • balanceSheetsYears array Private parameter balanceSheets
     balanceSheetsIV

    Filters balanceSheets and balanceSheetsIV packages content to only balance sheets data from the given years

    Accepts multiple values, separated with , (comma) char.

  • balanceSheetsCodes array Private parameter balanceSheets
     balanceSheetsIV

    Filters balanceSheets and balanceSheetsIV packages content to list only the given fields; you will need to provide each field code to specify what you need. This parameter can help you drastically reduce the payload returned by the API, making it considerably faster to serve the response.

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/companies/{id}"

Debug

Use these parameters when you need to understand how your request was evaluated by the API.

Parameters

  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

curl -G "https://api.atoka.io/v2/companies/{id}" -d "explain=true"

Response modifications

When explain is true, the response will be:

{
}
curl -G "https://api.atoka.io/v2/companies/{id}" -d "explain=true"

Response

Through the autentication credentials (the token) you are given, we are able to adapt the data available in API responses to your specific needs.

Moreover, depending on your subscription plan, you'll be able to retrieve different levels of details from the API calls.

{
"item": {
"id": "6da785b3adf219770c9e",
"ids": [
"foo",
...
],
"active": false,
"cervedId": 1015245,
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)",
"country": "it",
"name": "ACME S.p.A.",
"baby": false,
"obfuscated": false,
"score": 42,
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}

Company Match

Use this service when you need to match some data you already have with the detailed information in our database, for example to enrich your archives, or to ensure you have up-to-date data.

Each response contains a list of companies that could possibly match with data provided, ordered by confidence. The confidence associated with each company is a score between 0 and 1 computed as a combination of the fields matched or not matched with the provided data, and represents how well the result satisfies the filters provided (0 = no match, 1 = best match)

You can customize the minimum value of confidence that the results should have using the parameter minConfidence

In order to get the most accurate results you should use as many filter as you can, remembering to include at least one of these, which are called relevant filters:

If the only filters that you have are location or economic related, you are probably interested in the more general Company Search API

If no data was found, or no match is higher than minConfidence, we just return an empty list.

Remember: the more parameters you pass, the higher the probabilities of a successful match! 

https://api.atoka.io/v2/companies/match

All requests must be properly authenticated.

Authentication

Remember: the more parameters you pass, the higher the probabilities of a successful match!

Parameters

  • token string required

    All requests must be properly authenticated; see the Authentication section for more info

curl -G "https://api.atoka.io/v2/companies/match"

Response

By default this API endpoint returns the list of companies matching the selected criteria.

Using these parameters, you'll be able to customize the output you'll get from your searches.

Parameters

  • fields array,
    default is items

    Get just the list of companies matched, or the search facets (or both!).

    If you set this to value none, you'll get just the meta object, with count of companies matching your search criteria.

    Please notice that if you request the search facets, you need to provide the facetFields parameter as well.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • items
    • facets
    • none

  • facetFields array

    We want to keep our API as fast as possible, but facets are expensive to compute. To avoid slowing things down, you must explicitly state which facets you want when you request them. We want to make your life as simple as possible, though, that's why we support wildcards to be used in here; with them you will be able to have an initial look at the data, and to explicitly specify the facets you need once you start developing your application.

    This field is required when requesting the search facets through the fields parameter.

    Please notice that filters on the Match API are not strict by default; if you want to build a UI using the facets we provide, you should therefore make facet filters strict by using the enforce parameter. For example, if you show to the user the active facet, and the user clicks on the item of only active companies, you should submit your query to the API adding both active=true and enforce=active so that the information will not only be used for scoring, but will be strictly required for all the returned items.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • * Enable all the facets of all the requested packages
    • base.* Enable all the facets of the package "base"
    • base.active
    • economicsLite.* Enable all the facets of the package "economicsLite"
    • economicsLite.revenueRange
    • locations.* Enable all the facets of the package "locations"
    • locations.anyAddress.municipalities
    • locations.anyAddress.provinces
curl -G "https://api.atoka.io/v2/companies/match" -d "fields=items,facets" -d "facetFields=base.*"

Response modifications

When fields is items, the response will be:

{
"items": [
{
"id": "6da785b3adf219770c9e",
"ids": [
"foo",
...
],
"active": false,
"cervedId": 1015245,
"country": "it",
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)",
"name": "ACME S.p.A.",
"baby": false,
"obfuscated": false,
"score": 42
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/companies/match" -d "fields=items"

When fields is facets, the response will be:

{
"facets": {
},
"meta": {
"count": 34,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/companies/match" -d "fields=facets"

Data packages

For each item in search results, by default, we show just the Atoka Company ID (and little more).

By using the packages parameter you can fine tune the results to the level your application actually requires, or show all information available using all the data packages you subscribed to (with packages=*).

Remember: your subscription gives you access to different levels of detail in data returned!

If you have special needs and want to further customize the data returned, we can adapt the output to your specific needs: just get in touch with us at sales@atoka.io.

Parameters

  • packages array

    Fine tune the results to the level of detail your application actually requires.

    The extraction cost per single company will be multiplied to the number of results in your query (up to offset parameter value).

    To avoid using any package, don't pass this parameter and the results will contain just the Atoka Company ID (and little more).

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • atokaIndicators
    • balanceSheetsIV
    • base
    • cervedIndicators
    • contacts
    • covid19
    • economics
    • economicsLite
    • entities
    • foreignMarket
    • govcontracts
    • groups
    • leadEvents
    • locations
    • notesToAccounts
    • people
    • perimeters
    • publicFunding
    • realEstate
    • shares
    • socials
    • technologies
    • web
    • * (use all the data packages you have an active subscription for)
curl -G "https://api.atoka.io/v2/companies/match" -d "packages=*"

Response modifications

When packages is *, the response will be:

{
"items": [
{
"id": "6da785b3adf219770c9e",
"ids": [
"foo",
...
],
"active": false,
"cervedId": 1015245,
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)",
"country": "it",
"name": "ACME S.p.A.",
"baby": false,
"obfuscated": false,
"score": 42,
},
...
],
"facets": {
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}
curl -G "https://api.atoka.io/v2/companies/match" -d "packages=*"

N. of Results

You can control the number of returned items with these parameters; pagination is not allowed.

Parameters

  • limit integer,
    default is 10

    This is the number of individual objects that are returned in each page.

    Use a number between 0 and 50.

  • minConfidence number,
    default is 0.5

    Show any result with match confidence above this threshold.

    Use a number between 0 and 1.

  • enforce array

    By default filters of the Match API are not strict, because we assume input data may contain wrong or outdated information (after all, this is why we need a Match API, right?).

    With this parameter it is possible to change this behaviour, making a filter strict and therefore enforcing it. You can list here all the filters for which you are sure the data you are providing is correct, so that to narrow down the results and improve the match process.

    Please notice that filters should be enforced when using facets (through the fields and facetFields parameters), otherwise facets will not appear to be enabled.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • active
    • provinces
    • municipalities
    • postcodes
    • revenueRange
    • address
    • emails
    • websitesDomains

  • fuzziness integer,
    default is 0

    This parameter allows you to enable "fuzzy search" on some fields; a fuzzy search allows to "have mistakes" in the data at the level of single character; this is handy when data is read from paper and analyzed with OCR techniques.

    The parameter value represents the maximum Levenshtein Distance allowed, which is the maximum number of edit operations (additions, removals, and changes) on the characters of the string itself.

    This parameter will impact any search on taxID, vat or company name.

    Use a number between 0 and 2.

curl -G "https://api.atoka.io/v2/companies/match" -d "limit=10" -d "minConfidence=0.5"

General info

You can search for company records in all the countries we support, even multiple countries at a time, with the exception of Italy: countries=it can't be queried in combination with any other country, at the moment.

Some filters work only in specific countries, but the following ones can always be used, even when searching within more than one country at the same time (for example when countries=de,fr).

Parameters

  • countries array,
    default is it

    Find companies based in the specified countries.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • it
    • no
    • at
    • be
    • ch
    • cz
    • de
    • dk
    • es
    • fr
    • gb
    • gr
    • hu
    • ie
    • nl
    • pl
    • pt
    • ro
    • se
    • si
    • sk
    • * matches for any value

  • name array base

    Will lookup provided text in company name.

    To specifiy multiple values, repeat the parameter.

  • nameQuality number,
    default is 0.66     Private parameter base

    This parameter allows to specify the quality of your input data on names. It influences the minimum amount of token that the input data should share with the name we store in the index. Can be used in combination with fuzziness

    Use 1 if you want to get only companies whose names match all the input query tokens, otherwise use lower values to allow matches only on some tokens.

    If you use nameQuality <= 0.1 the name query will not be enforced and you will have to use other relevant filters or enforce non-relevant filter. This parameter will only impact on company name search.

    Use a number between 0 and 1.

  • regNumbers array base

    If you have any kind of official registration number associated to the company, use this parameter.

    For Italian companies (countries=it) this matches against Partita IVA, Codice Fiscale and REA. For REA, you can provide both CCIAA (camera di commercio) and REA number with regNumbers=TN210089.

    Accepts multiple values, separated with , (comma) char.

  • vat array base

    Search for company's V.A.T. code.

    For Italy (countries=it), it uses Partita IVA.

    Accepts multiple values, separated with , (comma) char.

    THIS FEATURE IS NOT IMPLEMENTED, YET. If you need it, just get in touch with us at sales@atoka.io

  • taxIds array base

    Search for company's tax identification number.

    For Italy (countries=it), it uses Codice Fiscale.

    Accepts multiple values, separated with , (comma) char.

    THIS FEATURE IS NOT IMPLEMENTED, YET. If you need it, just get in touch with us at sales@atoka.io

  • active array,
    default is true

    Match companies on their activity status. The default is to boost active companies in favour of inactive ones.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • true
    • false
    • unknown
    • * matches for any value

  • groupIds array Private parameter groups

    Comma separated list of group IDs to filter. Return companies belonging to one of the groups (identified by Group IDs from the list).

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/companies/match" -d "regNumbers=02241890223"

Economics

Use these filters to find companies with economics data matching selected criteria.

Parameters

  • revenueRange integer economicsLite

    Match companies with latest known revenue within the given range; revenue ranges are predefined and cannot be personalized:

    • 0 - 500000 (set revenueRange=0)
    • 500000 - 1000000 (set revenueRange=500000)
    • 1000000 - 2000000 (set revenueRange=1000000)
    • 2000000 - 3000000 (set revenueRange=2000000)
    • 3000000 - 5000000 (set revenueRange=3000000)
    • 5000000 - 10000000 (set revenueRange=5000000)
    • 10000000 - 25000000 (set revenueRange=10000000)
    • 25000000 - 50000000 (set revenueRange=25000000)
    • 50000000 - 100000000 (set revenueRange=50000000)
    • 100000000 - 250000000 (set revenueRange=100000000)
    • 250000000 + (set revenueRange=250000000)

    The currency depends on the countries parameter: for countries=it it is Euro.

    Based on latest officially registered company revenue records.

curl -G "https://api.atoka.io/v2/companies/match" -d "revenueRange=500000"

Location

Use these filters to find companies located in a specific place, either by name, or within a distance from passed coordinates.

Parameters

  • regions array base

    Match companies with at least one location in this region.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

    THIS FEATURE IS NOT IMPLEMENTED, YET. If you need it, just get in touch with us at sales@atoka.io

  • provinces array base
     locations

    Match companies with at least one location in this province.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • municipalities array base
     locations

    Match companies with at least one location in this municipality.

    You can use the AdminDiv service to get possible values for this parameter.

    Accepts multiple values, separated with , (comma) char.

  • postcodes array base
     locations

    Match companies with at least one location having specified postcodes.

    Accepts multiple values, separated with , (comma) char.

  • address array base

    Use this field to pass the address you have.

    To specifiy multiple values, repeat the parameter.

  • territories array base

    If you have just generic information about the company location, and canont match it against a specific parameter, this filter will look for passed data within any available geographical field (region, province and municipality).

    Accepts multiple values, separated with , (comma) char.

    THIS FEATURE IS NOT IMPLEMENTED, YET. If you need it, just get in touch with us at sales@atoka.io

  • useFullAddress boolean,
    default is false     locations
     base

    By default, address filter apply only to short addresses (e.g. Viale Olivetti, 1).

    If you set this parameter to true, they will be applied to full addresses location (e.g. Viale Olivetti, 1 38100 Trento TN).

curl -G "https://api.atoka.io/v2/companies/match" -d "address=Via Olivetti 13" -d "territories=Trento,Trentino Alto Adige" -d "useFullAddress=true"

Extended info

We enrich company records with data gathered from all over the web.

These parameters let you filter company records using additional data that give Web Super Powers to your queries!

Parameters

  • phones array contacts

    Use to match on phone numbers.

    Accepts multiple values, separated with , (comma) char.

  • websitesDomains array web

    Match companies linked to one (or more) specific web site. Can contain protocol (optional) and usually a second level domain (spaziodati.eu).

    Can also be a third (blog.spaziodati.eu) or higher level (more specific) one.

    Accepts multiple values, separated with , (comma) char.

  • emails array contacts

    Use to match on email address.

    Accepts multiple values, separated with , (comma) char.

  • socials array socials

    Use to match on social accounts.

    Accepts multiple values, separated with , (comma) char.

curl -G "https://api.atoka.io/v2/companies/match" -d "phones=050 55 25 74,+39 (050) 552-574" -d "websitesDomains=spaziodati.eu" -d "emails=hello@spaziodati.eu" -d "socials=https://www.facebook.com/spaziodati.eu,atoka_io,http://www.linkedin.com/company/spaziodati"

Debug

Use these parameters when you need to understand how your request was evaluated by the API.

Remember: the more parameters you pass, the higher the probabilities of a successful match!

Parameters

  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

curl -G "https://api.atoka.io/v2/companies/match" -d "explain=true"

Response modifications

When explain is true, the response will be:

{
}
curl -G "https://api.atoka.io/v2/companies/match" -d "explain=true"

Response

The response is structured in the same exact way as when using fields=items for Company Search service (no package can be used, though).

{
"items": [
{
"id": "6da785b3adf219770c9e",
"ids": [
"foo",
...
],
"active": false,
"cervedId": 1015245,
"confidence": 0.76,
"country": "it",
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)",
"name": "ACME S.p.A.",
"baby": false,
"obfuscated": false,
},
...
],
"facets": {
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
],
"meta": {
"ordering": "default",
"count": 57,
"limit": 10,
"offset": 30,
"info": [
"foo",
...
],
"obfuscated": {
"foo": undefined,
"bar": undefined,
"baz": undefined
}
}
}

Company Location Search

This API allows to retrieve all the locations of a company. It is a shorthand for the Location Search API with a filter on the given company already in place, which means that you could use that API instead, correctly filtered, and obtain exactly the same results.

Please refer to the documentation of the Location Search API if you want to know more.

https://api.atoka.io/v2/companies/{id}/locations

Replace {id} with company id.

All requests must be properly authenticated.

Company People Search

This API allows to retrieve all the people that have a position in a specific company. It is a shorthand for the People Search API with a filter on the given company already in place, which means that you could use that API instead, correctly filtered, and obtain exactly the same results.

Please refer to the documentation of the People Search API if you want to know more.

https://api.atoka.io/v2/companies/{id}/people

Replace {id} with company id.

All requests must be properly authenticated.

Company Public Funding Search

This API allows to retrieve all the public funding that have been granted to a specific company. It is a shorthand for the Public Funding Search API with a filter on the given company already in place, which means that you could use that API instead, correctly filtered, and obtain exactly the same results.

Please refer to the documentation of the Public Funding Search API if you want to know more.

https://api.atoka.io/v2/companies/{id}/publicfunding

Replace {id} with company id.

All requests must be properly authenticated.

Company Notes to Accounts Search

This API allows to retrieve all the notes to accounts of a specific company. It is a shorthand for the Notes to Accounts API with a filter on the given company already in place, which means that you could use that API instead, correctly filtered, and obtain exactly the same results.

Please refer to the documentation of the Notes to Accounts API if you want to know more.

https://api.atoka.io/v2/companies/{id}/notestoaccounts

Replace {id} with company id.

All requests must be properly authenticated.

Company CIGS measures Search

This API allows to retrieve all the CIGS measures of a specific company. It is a shorthand for the CIGS API with a filter on the given company already in place, which means that you could use that API instead, correctly filtered, and obtain exactly the same results.

Please refer to the documentation of the CIGS API if you want to know more.

https://api.atoka.io/v2/companies/{id}/cigs

Replace {id} with company id.

All requests must be properly authenticated.

Company Trademarks Search

This API allows to retrieve all the registered trademarks measures of a specific company. It is a shorthand for the Trademarks API with a filter on the given company already in place, which means that you could use that API instead, correctly filtered, and obtain exactly the same results.

Please refer to the documentation of the Trademarks API if you want to know more.

https://api.atoka.io/v2/companies/{id}/trademarks

Replace {id} with company id.

All requests must be properly authenticated.

Company Annotator

Our unique semantic tool that let you annotate text with companies and people drawn from Atoka DB.

This endpoint consumes JSON: it expects a valid JSON object to be sent in a POST request

https://api.atoka.io/v2/companies/annotate

All requests must be properly authenticated.

JSON schema

  • text string required

    The content to be annotated, plain text that doesn't need any pre-processing

  • people boolean,
    default is true

    Whether or not to annotate also people related to mentioned companies

curl -XPOST -H "Content-Type: application/json" "https://api.atoka.io/v2/companies/annotate" -d '{"text":"Titolo Ferrari NV in lieve aumento di 0,04% a 282.7 Euro per azione.","people":true}'

Response

Companies and people annotations.

{
"time": 42,
"annotations": [
{
"start": 42,
"end": 42,
"spot": "foo",
"title": "foo",
"id": "foo",
"confidence": 0.42,
"ner_types": [
"ORG",
...
],
"type": "Company",
"ner_scores": {"foo": "bar"}
},
...
]
}