Atoka API User Reference

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.

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
  • token string required

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

  • 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
    • arval.* Enable all the facets of the package "arval"
    • arval.cluster
    • atokaIndicators.* Enable all the facets of the package "atokaIndicators"
    • atokaIndicators.innovation.categoryScore
    • atokaIndicators.innovation.score
    • atokaIndicators.webCentrality.categoryScore
    • atokaIndicators.webCentrality.score
    • base.* Enable all the facets of the package "base"
    • base.agcm.rating
    • base.ateco
    • base.founded
    • base.govType
    • base.legalClass
    • base.legalForms
    • base.nace
    • base.okved2014
    • base.registeredAddress.macroregion
    • base.registeredAddress.municipality
    • base.registeredAddress.postcode
    • base.registeredAddress.province
    • base.registeredAddress.region
    • base.sicUk
    • base.startup
    • cervedIndicators.* Enable all the facets of the package "cervedIndicators"
    • cervedIndicators.negativities
    • cervedIndicators.scoreProperty
    • contacts.* Enable all the facets of the package "contacts"
    • contacts.emails
    • contacts.phones
    • and other 57 options... (see the whole list in the JSON schema)
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": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific company
"country": "string",
"name": "string", // Cleaned name of the company
"fullAddress": "string", // Full address of the company
},
...
],
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
}
}
curl -G "https://api.atoka.io/v2/companies" -d "fields=items"

When fields is facets, the response will be:

{
"facets": {
},
"meta": { // Meta information on results
"count": int, // Total number of objects returned
"info": [ // A list of information messages, if any.
"string",
...
]
}
}
curl -G "https://api.atoka.io/v2/companies" -d "fields=facets"

Debug

Use these parameters when you need to undestand 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"

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
    • base
    • cervedIndicators
    • cervedGroups
    • contacts
    • economics
    • economicsLite
    • entities
    • govcontracts
    • groups
    • jobs
    • locations
    • people
    • 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": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific company
"fullAddress": "string", // Full address of the company
"country": "string", // Full address of the company
"name": "string", // Cleaned name of the company
},
...
],
"facets": {
},
"profile": {
},
"queryExplanation": [
{ // Submitted query explanation.
"engine": "string",
"text": "string",
"json": object
},
...
],
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
}
}
curl -G "https://api.atoka.io/v2/companies" -d "packages=*"

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,uk,ru).

Please note: right now only Italy (countries=it), U.K. (countries=uk) and Russia (countries=ru) are available, but we'll soon expand data coverage to more countries.

Parameters
  • countries array,
    default is it

    Restrict matches to those valid in specific countries.

    For the moment the only countries covered are Italy (it), U.K. ('uk') and Russia (ru), but we will soon extend it with more countries.

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

    Possible values are:

    • it
    • uk
    • ru
    • * matches for any value
  • active string,
    default is "true"

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

    Choose only one among:

    • true
    • false
    • unknown
    • * matches for any value
  • 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.

    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.

  • name string base

    Will lookup provided text in company name.

  • namePrefix string base

    Will lookup provided text at the beginning of company name.

  • 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).

  • 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).

  • 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 on or after the given date

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

  • foundedTo string base

    Match companies founded on or before the given date

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

  • 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.

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 "nace=68"

profile

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.

Parameters
  • relevanceCoverage number

    Used in combination with fields=profile. Defines the coverage of relevance w.r.t. the whole detected features we aim to obtain in selecting the most relevant features.

    Use a number between 0 and 1.

curl -G "https://api.atoka.io/v2/companies" -d "relevanceCoverage=0.85"

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,uk) will raise an error.

Parameters
  • 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

  • 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 in the JSON schema)
  • 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 in the JSON schema)
  • 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.

  • startup boolean base

    Match companies officially registered as Startup Innovativa.

curl -G "https://api.atoka.io/v2/companies" -d "cciaa=*" -d "govTypes=*" -d "govTypesExclude=*" -d "govCodes=c_l378" -d "ateco=62.09.09" -d "startup=true"

Extended info

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

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

Parameters
  • 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
  • jobs boolean jobs

    Match companies having open job ads.

    You can use Job Ads Search API to get full information about job ads.

  • 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.

  • websitesContentTag boolean,
    default is false
    web

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

  • websitesContentTagStart string,
    default is "<em>"
    web

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

  • websitesContentTagEnd string,
    default is "</em>"
    web

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

  • 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
    • * match for any kind of email found
  • phones array contacts

    Match for potential phone numbers found.

    The only possibility right now is to match for any kind of phone number: we'll soon enable more fine grained filters.

    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
  • 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
    • * 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
    • instagram
    • linkedin
    • vimeo
    • youtube
  • 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)

  • 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].

  • 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)

  • 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].

  • 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

  • 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].

  • 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)

  • 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].

  • 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)

  • 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].

  • 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)

  • 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].

  • 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)

  • 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].

  • 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

  • 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].

  • 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

  • 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].

  • 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

  • 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].

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

Economics

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

Parameters
  • employeesMin integer economics

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

  • employeesMax integer economics

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

  • 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.

  • 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.

  • revenueTrends array economics

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

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

    Possible values are:

    • increasing
    • stable
    • decreasing
    • incalculable
  • 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.

  • 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.

curl -G "https://api.atoka.io/v2/companies" -d "employeesMin=100" -d "employeesMax=1000" -d "revenueMin=50000" -d "assetsMin=50000"

Indicators

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

Parameters
  • scoreProperties array cervedIndicators

    Match companies on their score property, a Cerved indicator about the stability of the company.

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

    Possible values are:

    • CGP_1 high stability (green light)
    • CGP_2 mid-high stability (green light)
    • CGP_3 moderate stability (yellow light)
    • CGP_4 low stability (red light)

    THIS FEATURE REQUIRES A SPECIAL AGREEMENT WITH OUR PARTNER. If you need it, just get in touch with us at sales@atoka.io

  • negativities boolean 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:

    THIS FEATURE REQUIRES A SPECIAL AGREEMENT WITH OUR PARTNER. If you need it, just get in touch with us at sales@atoka.io

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

Location

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

Parameters
  • 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: will match on any value (logic OR).

    Possible values are:

    • nord-ovest
    • nord-est
    • sud
    • centro
    • isole
  • macroregionsExclude array base
    locations

    Match companies with no location in this macro-region.

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

    Possible values are:

    • nord-ovest
    • nord-est
    • sud
    • centro
    • isole
  • 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.

curl -G "https://api.atoka.io/v2/companies" -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.

  • similarityLimit integer,
    default is 10
    similarity

    This is the number of companies returned by the similarity service

    Use a number between 0 and 50.

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

Custom Data

Filter atoka using your own data.

These parameters lets 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.

    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.

curl -G "https://api.atoka.io/v2/companies" -d "customData={"customData": "data_id", "field": "field_name", "includes": ["my_value"]}"

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), the [Company Match](#companies_match) or the [News Search](#news) API endpoints).

All requests must be properly authenticated.

response

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.

Parameters
  • token string required

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

  • 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
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:

    • arval
    • atokaIndicators
    • balanceSheets
    • base
    • cervedIndicators
    • cervedGroups
    • contacts
    • customData
    • economics
    • economicsLite
    • entities
    • govcontracts
    • groups
    • jobs
    • locations
    • people
    • 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": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific company
"fullAddress": "string", // Full address of the company
"country": "string", // Full address of the company
"name": "string", // Cleaned name of the company
},
"queryExplanation": [
{ // Submitted query explanation.
"engine": "string",
"text": "string",
"json": object
},
...
]
}
curl -G "https://api.atoka.io/v2/companies/{id}" -d "packages=*"

Debug

Use these parameters when you need to undestand 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"

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.

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
  • token string required

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

  • 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": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific company
"country": "string",
"name": "string", // Cleaned name of the company
"fullAddress": "string", // Full address of the company
},
...
],
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
}
}
curl -G "https://api.atoka.io/v2/companies/match" -d "fields=items"

When fields is facets, the response will be:

{
"facets": {
},
"meta": { // Meta information on results
"count": int, // Total number of objects returned
"info": [ // A list of information messages, if any.
"string",
...
]
}
}
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
    • base
    • cervedIndicators
    • cervedGroups
    • contacts
    • economics
    • economicsLite
    • entities
    • govcontracts
    • groups
    • jobs
    • locations
    • people
    • 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": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific company
"fullAddress": "string", // Full address of the company
"country": "string", // Full address of the company
"name": "string", // Cleaned name of the company
},
...
],
"facets": {
},
"queryExplanation": [
{ // Submitted query explanation.
"engine": "string",
"text": "string",
"json": object
},
...
],
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
}
}
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
  • 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" -d "enforce=0.5"

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,uk,ru).

Parameters
  • countries array,
    default is it

    Find companies based in the specified countries.

    For the moment the only countries covered are Italy (it), U.K. (uk) and Russia (ru), but we will soon extend it with more countries.

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

    Possible values are:

    • it
    • uk
    • ru
    • * matches for any value
  • name array base

    Will lookup provided text in company name.

    To specifiy multiple values, repeat the parameter.

  • 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.

    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 string,
    default is "true"

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

    Choose only one among:

    • true
    • false
    • unknown
    • * matches for any value
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"

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.

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

Parameters
  • similarityLimit integer,
    default is 10
    similarity

    This is the number of companies returned by the similarity service

    Use a number between 0 and 50.

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

Extended info

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

These parameters lets 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 undestand 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/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"

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

All requests must be properly authenticated.

Response

The response of the location

{
"items": [
{
"id": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific company
"fullAddress": "string", // Full address of the company
},
...
],
"facets": {
},
"queryExplanation": [
{ // Submitted query explanation.
"engine": "string",
"text": "string",
"json": object
},
...
],
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
}
}

Company Contract Search

This API allows to retrieve all the contracts where the specific company applied to. It is a shorthand for the Contract 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 Contract Search API if you want to know more.

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

All requests must be properly authenticated.

Response

The response of the contract

{
"items": [
{
"id": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific contract
"subject": "string", // The subject of the contract it self
},
...
],
"facets": {
},
"queryExplanation": [
{ // Submitted query explanation.
"engine": "string",
"text": "string",
"json": object
},
...
],
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
}
}

Company Job Ads Search

This API allows to retrieve all the job ads published by a specific company applied to. It is a shorthand for the Job Ads 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 Job Ads Search API if you want to know more.

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

All requests must be properly authenticated.

Response

The response of the job ad

{
"items": [
{
"id": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific job ad
"subject": "string", // The subject of the job ad
},
...
],
"facets": {
},
"queryExplanation": [
{ // Submitted query explanation.
"engine": "string",
"text": "string",
"json": object
},
...
],
"meta": { // Meta information on search results
"ordering": "string", // Requested sorting algorithm.
"count": int, // Total number of records matching search query.
"limit": int, // As per search parameters, maximum number of records fetched per request.
"offset": int, // As per search parameters, number of records skipped.
"info": [ // A list of information messages, if any.
"string",
...
]
}
}

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

All requests must be properly authenticated.

Response

The response of the people

{
"items": [
{
"id": "string", // Unique ID that you can use throughout the API endpoints to reference to a specific person
"country": "string",
"name": "string", // The full name of the person
"obfuscated": boolean, // true iff this person was obfuscated, so that it is not possible to know anything personal about him or her. Relationships with companies are still kept, with roles or shares amounts.
},
...
],
"facets": {