Atoka API User Reference

v20240416.0917

Location Search

This API allows you to search for company locations. If what you are looking for are companies, you should try the Company Search API first, there are many filters to get companies based on their locations (see the location filters for more details). On the other hand, if what you need is full control on company locations, especially to overcome the limitations applied tot he Company Search API, this API is what will make your life easier.

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

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/locations"

Response

By default this API endpoint returns the list of locations 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 locations matched, or the search facets (or both!).

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

    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
    • base.* Enable all the facets of the package "base"
    • base.address.macroregion
    • base.address.municipality
    • base.address.postcode
    • base.address.province
    • base.address.region
    • base.company.ateco
    • base.company.legalForms
    • base.type
    • contacts.* Enable all the facets of the package "contacts"
    • contacts.phones
curl -G "https://api.atoka.io/v2/locations" -d "fields=items,facets" -d "facetFields=base.*"

Response modifications

When fields is items, the response will be:

{
"items": [
{
"id": "6da785b3adf219770c9e",
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)"
},
...
],
"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/locations" -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/locations" -d "fields=facets"

Data packages

This parameter allows you to control the information you want to retrieve about each location.

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 site 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 Location ID (and little more).

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

    Possible values are:

    • base
    • contacts
    • * (use all the data packages you have an active subscription for)
curl -G "https://api.atoka.io/v2/locations" -d "packages=*"

Response modifications

When packages is *, the response will be:

{
"items": [
{
"id": "6da785b3adf219770c9e",
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)",
},
...
],
"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/locations" -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:

    • atoka
    • distance
curl -G "https://api.atoka.io/v2/locations" -d "limit=10" -d "offset=30" -d "ordering=distance"

General info

Here are listed some base filters on Locations, such as their type or whether to return inactive locations as well as active ones.

Parameters

  • countries array,
    default is it

    Find locations based in the specified countries.

    For the moment the only country covered is Italy (it).

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

    Possible values are:

    • it
    • * matches for any value

  • ids array

    Search via already known Atoka Location IDs.

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

  • active string,
    default is "true"     base

    Find only active/inactive locations, or all. The default is to look for active locations only.

    Choose only one among:

    • true
    • false
    • * matches for any value

  • registered boolean base

    Find only registered addresses ("sede legale" in Italy), secondary locations, or both.

  • types array base

    Filter locations based on their types.

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

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

Address

Locations are places, and therefore have an address. With these filters you can find the place you are looking for, either from its municipality, province, etc, or even by some geographic coordinates.

Parameters

  • macroregions array base

    Match locations 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

    Match locations 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

    Match locations 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

    Match locations 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

    Match locations having specified postcodes.

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

  • lat number base

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

    Must be used together with lon and distance.

  • lon number base

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

    Must be used together with lat and distance.

  • distance integer base

    Match locations 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.

    Use a number bigger than 0.

curl -G "https://api.atoka.io/v2/locations" -d "lat=46.0804401" -d "lon=11.050316" -d "distance=30000"

Company info

You can filter locations by some company-related information. Please refer to the Company Search API if you need assistance on that side.

Parameters

  • companies array base

    Search via already known Atoka Company IDs.

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

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

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

  • companyAteco array base

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

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

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

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

  • companyAtecoExclude array base

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

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

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

curl -G "https://api.atoka.io/v2/locations" -d "companyAteco=62.09.09"

Contacts

Here you will find filters and information on how to contact a specific company location.

Parameters

  • 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 locations, 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
curl -G "https://api.atoka.io/v2/locations" -d "phones=*"

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/locations" -d "explain=true"

Response modifications

When explain is true, the response will be:

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

Response

The response of the location

{
"items": [
{
"id": "6da785b3adf219770c9e",
"fullAddress": "Via Garibaldi, 1, 01234, Roma (RM)",
},
...
],
"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
}
}
}