Atoka API Tutorial

How to use Atoka API in the best way

1. Introduction
2. Get the name and registered office of a company having the VAT ID
3. How is the information organized in Packages and what are the endpoints to get there
4. Using social networks as the number of employees changes: faceting
5. Automatic completion of a company form [Javascript]
6. Make suggestions for names of municipalities and see companies on a map [Javascript]
7. Use the Company Match API to correct and enrich approximate data
8. Finding businesses around

 


1. Introduction

Atoka, the database with more than 21 million Italian and British companies (about 6 million active today) and 13 million verified contacts, allows access to their data through these APIs. This tutorial introduces the basic concepts to be able to use, showing practical examples that you can try.

SuperQuick reference

The complete and official documentation of the API: https://developers.atoka.io/v2/
The base address, shared by all endpoints: https://api.atoka.io/v2/.
Every API follows the REST architecture and responds in JSON format.

Access Token

The API needs authentication, through a token passed to each call, similar to this xuao1d61b5234c1e912b11856c3f4de3. If you don’t have any of these, write to us at sales@atoka.io, we would be happy to create a trial one for you.

 


 

 

2. Get the name and registered office of a company having the VAT ID

 

To do this, just query the endpoint companies, with the vat parameter of the base package, with your TOKEN, like this:

 

https://api.atoka.io/v2/companies?packages=base&vat=02241890223&token=TOKEN

 

"items": [
   {
            "id": "6da785b3adf2", 
            "name": "SPAZIODATI S.R.L.",
            "country": "it",
            "fullAddress": "Viale Adriano Olivetti, 13, 38122, Trento (TN)"
            "base": {
                "legalName": "SPAZIODATI S.R.L.",
                "startup": true,
                "vat": "02241890223",
                "active": true,
                "founded": "2012-02-13",
                "ateco": [ /*omesso */ ],
                "legalForms": [ /* omesso */ ] ,
                "registeredAddress": { /* omesso */ }             
            },
        }
    ],
    "meta": {
        "ordering": "atoka",
        "count": 1,
        "offset": 0,
        "limit": 10
    }

 

The answer modified for brevity, contains:

  • items: è is the list of results, companies, which in this case, looking for VAT, has only one item
  • meta: contains number of results, order, limit and offset. Useful to paginate and order
  • id: is the ID that Atoka uses to identify the company, used by many other APIs
  • name, fullAddress: the information, we were looking for!
  • base: contains all the information provided by the basic package, detail of the address, NACE code, company type, date of foundation and more

 

3. How is the information organized in Packages and what are the endpoints to get there

The APIs of Atoka are divided in several endpoints, among which:

And also contracts, jobs, people.

Within each endpoint, data is organized in multiple packages, which are nothing more than logical grouping units. In the example, using the base package we have retrieved the master and some basic information of the company. Other packages of the endpoint companies are:

  • contacts: telephone and email
  • economics: number of employees, financial data on revenues, seasonality
  • web: data extracted from the web such as description, logos, controlled websites, RSS feeds, keywords, and more
  • govContracts: contracts and tenders with public administrations, to which companies have participated or who have won
  • people: information about exponents (managers and administrators) and their respective roles in the company
  • shares: who owns who and what, with the amount and percentages

And also economicsLite, groups, jobs, locations, socials, technologies, entities, cervedIndicators.

The package parameter allows you to select what you want to get in the answer, and state which parameters you are using to build your request.

4. Using social networks as the number of employees changes: faceting

We want quantitative information, divided into 4 segments by size. What and how many social networks are used by up to 5 employees? How many 6 to 10? 11-100? And over 100?

Social

We want to find out that around 4% of the companies that employ up to 5 employees use social networks, 13% of those with a staff of between 6 and 10, 19% in the 11-100 range, and 31% of those over 100 employees.

Which Social Network

We also want to find out that with the rise in the size of the companies, Facebook becomes relatively less dominant, going almost in line with the second and third most used social network, when it comes to very large companies.

To get this type of count you can use the facet!

Using the fields=facet parameter the responses will no longer contain business data, but the aggregations tell us how many companies match the criteria of the request. Let's specify in what field to do faceting, ie where to get aggregates, using facetFields, in our case with socials.*.

To interact with social networks and the number of company employees we will need the socials and economics packages. The number of employees is filterable through employeesMin and employeesMax.

 

Up to 5 employees:

 

https://api.atoka.io/v2/companies?packages=socials,economics&fields=facets&facetFields=socials.*&employeesMax=5&token=TOKEN

 

 "meta": { "count": 3800034 },
    "facets": {
        "socials": {
            "facebook": { "count": 145637 },
            "twitter": { "count": 35509 },
            "googleplus": { "count": 22678 },
            "youtube": { "count": 17581 },
            "instagram": { "count": 13936 },
            "linkedin": { "count": 9777 },
            "vimeo": { "count": 1648 },
            "flickr": { "count": 1290 },
        }
    }
  • meta.count tells us how many companies match filters, companies up to 5 employees
  • facets.socials contains the facet list: for each value, the aggregate number is reported. About 145,000 people use Facebook, 35,000 Twitter and so on

 

 

From 6 to 10 employees:

https://api.atoka.io/v2/companies?packages=socials,economics&fields=facets&facetFields=socials.*&employeesMin=5&employeesMax=10&token=TOKEN

 

 "meta": { "count": 376793 },
    "facets": {
        "socials": {
            "facebook": { "count": 49002 },
            "twitter": { "count": 11234 },
            "googleplus": { "count": 7499 },
            /* omesso */
        }
    }

 

 

From 11 to 100 employees:

https://api.atoka.io/v2/companies?packages=socials,economics&fields=facets&facetFields=socials.*&employeesMin=10&employeesMax=100&token=TOKEN

 

 "meta": { "count": 234119 },
    "facets": {
        "socials": {
            "facebook": { "count": 44633 },
            "twitter": { "count": 14005 },
            "youtube": { "count": 10894 },
            /* omesso */
        }
    }

 

 

More than 100 employees:

https://api.atoka.io/v2/companies?packages=socials,economics&fields=facets&facetFields=socials.*&employeesMin=100&token=TOKEN

 

  "meta": { "count": 13503 },
    "facets": {
        "socials": {
            "facebook": { "count": 4199 },
            "twitter": { "count": 2335 },
            "youtube": { "count": 2267 },
        }
    }

 

 

In other words, the data says that Facebook is the most widely used social network by all Italian companies, followed by Twitter, which is in second place. Google Plus wins third place, but only among the companies with up to 10 employees, after this threshold companies tend to prefer YouTube. Thanks to the data of these 4 calls, the graphs above were drawn.

By following the same procedure and using APIs in a very similar way, it is possible to analyze and segment companies from Lombardy, those with turnover more than 10 million euros, those that exist for more than 10 years or the startups. Or any combination of these and so many other criterias!

5. Automatic completion of a company form [Javascript]

Starting from a VAT number we want to get the company register: company name, ATECO code, company type, registered office, revenues, employees, web site, email and telephone contacts.

The full code is here: https://jsfiddle.net/simone_/w2dsLamb/ (The bottom right pane is working, enter your token, click go... et-voilà!) The HTML and CSS are not very interesting, some input, a bit of margins, two colors. The Javascript code instead calls the API and populates the results.

 

When you click the button, this handler runs:

$('#vai').click(function() {
    let token = $('#token').val(),
        piva = $('#piva').val(),
        url = `https://api.atoka.io/v2/companies?token=${token}`;


    $.post(url, {
        vat: piva,
        packages: 'base,economics,contacts,web'
    }).done(displayData);


    return false;
});

 

 

Tokens and VAT numbers are being read and they generate the URL of the API. Note that the token is entered in the string query and not in the call body.

An AJAX call is made in POST mode, passing the vat and packages parameters. To get the data we need, we will need basic, economics contacts and web. You have to use the POST method to circumvent the CORS security controls.

The result of the call is handled by the displayData function, of which we report an extract:

function displayData(data) {
    let azienda = data.items[0];
    console.log('Atoka data:', azienda);

    $('#ragioneSociale').html(azienda.name);
    $('#sedeLegale').html(azienda.fullAddress);
    $('#ateco').html(
        azienda.base.ateco[0].code + ': ' + 
        azienda.base.ateco[0].description
    );

    // ecc

    if (azienda.contacts.phones) {
        $('#telefono').html(
            azienda.contacts.phones[0].number +
            ' (' + azienda.contacts.phones.length + ' in totale)'
        );
    }
}

 

 

...that does nothing but use the JSON to put the various pieces in place.

The result of this endpoint is still an array of items, but since we filter by VAT we can be sure that the result is only one (or no one, if the VAT match does not exist), the first element of the data array .items [0].

Note the last block with the if: before printing the phone number we verify that company.contacts.phones is truthy, that is, present in the object. Also, being phones in an array, we can decide whether to show them all or just the most significant (the first) and simply give them visibility of their total number.

6. Make suggestions for names of municipalities and see companies on a map [Javascript]

We want to create a simple search field that allows you to select a community, then see the locations of the top 30 companies on a map. We want the search field to suggest municipalities while typing the user. For example, entering "tren" will suggest "Trento", "Trentinara", "Trenta", but also "Tione di Trento" etc.

The complete code is here: https://jsfiddle.net/simone_/4esemece/ (The bottom right box is working, enter your token, write something and click a suggestion ... et-voilà!)

The problem can be divided into two steps:

  • get the list of communities to suggest
  • get the list of companies for a common one

For the first step we will use the endpoint admindiv:

$('#sede').keyup(function() {
    /* omesso */
    let url = `https://api.atoka.io/v2/admindiv`;
    $.get(url, {
        token: token,
        namePrefix: sede, 
       countries: 'it',
       types: 'municipality',
    }).done(mostraSuggerimenti);
});

 

 

Each time the user interacts with the search box, the handler will call the APIs by typing in the namePrefix parameter, countries = it, (Italy) and types = municipality (to get only the municipalities, excluding Regions, provinces, etc.).

This call will return a simple JSON with an array of pair type, value:

"items": [
    {
        "type": "municipality",
        "value": "Trenta"
    },
    {
        "type": "municipality",
        "value": "Trento"
    },
    {
        "type": "municipality",
        "value": "Tione di Trento"
    }
]

 

The array is passed to mostraSuggerimenti:

function mostraSuggerimenti(data) {
    let suggerimenti = data.items
        .map(function(item) {
            let node = $(`<div class='suggerimento'>${item.value}</div>`);
            node.click(() => cercaAziende(item.value));
            return node;
        });
    $('#suggerimenti').html(suggerimenti);
}

 

At this point, a clickable suggestion will be created for each item, located below the search box:

Automatic completion

When the user clicks on a municipality, cercaAziende will be invoked with the municipality name from which we want to get the list of companies with the second call to the APIs:

function cercaAziende(comune) {
    /* omesso */
    let url = `https://api.atoka.io/v2/locations?token=${token}`;
    $.post(url, {
        packages: 'base,contacts',
        municipalities: comune,
        limit: 30,
    }).done(mostraAziende);
}

 

At the endpoint locations then we pass the municipalities parameter to the chosen municipality and get a list of 30 companies in that municipality.

The list is passed to mostraAziende:

function mostraAziende(data) {
    $('#suggerimenti').html('');


    let coords = data.items
        .filter(function(item) {
            return 'lat' in item.base.address;
        })
        .map(function(item) {
            let address = item.base.address;
            return {lat: address.lat, lon: address.lon};
        });
    inizializzaMappa(coords);
}

 

Now the array is filtered, holding only companies for which we have latitude and longitude. Then the company data is reduced to a single lat, lon which we will use to place the markers on the map by inizializzaMappa.

At this point you will see the markers corresponding to the locations of the 30 companies in the municipality selected on a map.

Companies on a map

 

7. Use the Company Match API to correct and enrich approximate data

The Company Match API may find results if incorrect, inaccurate or incomplete starting data (such as a phone number no longer used) and is therefore ideal for verifying the accuracy of your database or updating it with the latest available data in Atoka.

Let's imagine, for example, that we have an incorrectly transcribed VAT match, from which you can not go back to the company.

https://api.atoka.io/v2/companies?packages=base&regNumbers=0241890223&token=TOKEN
    "meta": {
    "limit": 10,
    "ordering": "atoka",
    "offset": 0,
    "count": 0
  },
  "items": []

 

Using endpoint companies, in fact, no results are returned.

Thanks to API Company Match, we can do a “fuzzy” search that, even from inaccurate or incomplete data, offers a list of results that might match the request. Interrogating the endpoint companies/match we can establish the required precision using the fuzziness parameter. You do not need to enable any package.

https://api.atoka.io/v2/companies/match?regNumbers=0241890223&fuzziness=2&token=TOKEN
 "meta": {
    "limit": 10,
     "count": 63
  },
  "items": [
    {
      "id": "f6dde193da86",
       "confidence": 0.8,
      /* omesso */
    },
    {
      "id": "6da785b3adf2",
       "confidence": 0.8,
      /* omesso */
    },
    /* omesso */
  ]

 

The answer is very similar to that of a normal search, with the addition of the confidence value (0-1), which indicates how the result satisfies the search criteria and is used to sort the results. At this point we can add parameters (for example, name) to refine the search and use the minConfidence parameter to reduce the number of results.

https://api.atoka.io/v2/companies/match?packages=base&regNumbers=0241890223&name=spaziodati&minConfidence=0.8&fuzziness=2&token=TOKEN
  "meta": {
    "limit": 10,
    "count": 66
  },
  "items": [
    {
      "id": "f6dde193da86",
      "confidence": 0.8212,
      "name": "SPAZIODATI S.R.L.",
      /* omesso */
      "base": { /* omesso */ }
    }
  ]

 

By adding the base package we get more data on the company, allowing us to verify that the returned business is actually the one that is being sought. All packages available for endpoint companies can also be used with the Company Match API.

 

Relevant Parameters

It is important to note that the purpose of the Company Match API is not to find a set of companies that meet certain requirements, but rather to identify a company from the data at its disposal. For this reason, at least one relevant parameter must be provided to identify a specific company. If no one is used at least one will be returned an error.

https://api.atoka.io/v2/companies/match?municipalities=trento&token=TOKEN
  "error": true,
  "message": "No relevant filters provided",
  "statuscode": 400

 

Some examples of relevant parameters are name, regNumbers, emails; The full list, along with all the information about the Company Match API, is available in the documentation.

 

8. Finding businesses around

We want to provide a representative of a food business with a list of companies in the catering sector (restaurants, canteens, bars, etc ..) located a short distance from its location.

The Location Search API offers both the ability to sort by business locations at a distance and to set the distance from a point within which to search.

 

We suppose our agent is in the center of Trento (latitude and longitude 46.067351, 11.121325). We therefore seek the Ateco sector of our potential customers using the dedicated endpoint:

https://api.atoka.io/v2/ateco?query=ristorazione&token=TOKEN
  "items": [{
    "code": "56",
    "description": "attività dei servizi di ristorazione",
    "rootCode": "I"
  },/* omesso */]

 

Now we can search companies in this area within 500 meters from the given point:

https://api.atoka.io/v2/locations?packages=base&companyAteco=56&lat=46.067351&lon=11.121325&distance=500&ordering=distance&token=TOKEN
 "meta": {
    "limit": 10,
    "count": 245,
    "ordering": "distance"
  },
  "items": [
    {
      "id": "5413314b4546",
      "base": { 
         "address": {
             "distance": 28 
             /* omesso */ 
         },
         "company": { 
             "legalName": "GROMART S.R.L.",
             "id": "893c134733c8"
         }, /* omesso */ 
      }
    },/* omissis */
  ]

 

We searched for business locations:

  • catering sector (companyAteco=56)
  • within 500 meters (distance=500)
  • from the center of Trento (lat=46.067351 lon=11.121325)
  • sorted by distance from the specified point (ordering=distance)

We can also use other filters to refine our search as registered to only get those with legal headquarters nearby, or even filters on other company based information.

However, if our agent requires a more complex query involving company features not contained in site filters, the Company Search API can help.

Suppose we want to limit the previous search to companies born in the last year.
We use endpoint companies with the same lat, lon and distance parameters to define the starting point and radius, ordering = distance to sort results, ateco = 56 for the industry and add ageMax = 12 to filter companies born in the last 12 months. We also include the parameter anyAddress = true to consider all locations and not just the registered office.

https://api.atoka.io/v2/companies?packages=base,locations&lat=46.067351&lon=11.121325&distance=500&ordering=distance&anyAddress=true&ageMax=12&token=TOKEN
 "meta": {
    "limit": 10,
    "count": 10,
    "ordering": "distance"
  },
  "items": [
    {
      "id": "84b3ce2fa0ce",
      "name": "FAES EMANUELE",
      "base": { 
         "registeredAddress": {
             "distance": 92 
             /* omesso */ 
         }
         /* omissis */ 
      },
      "locations": { 
         "items": [{  /* list of all other locations */
             "address": { 
                 "distance": 210312  /* distance for every location */
                 /* omesso */ 
             }
         }]
         /* omissis */ 
      },

    },..
  ]

 

By following the same procedure and by using the APIs with the ’fields=facets’ parameter in a very similar way, you can analyze and segment the surrounding businesses, by Ateco sector, by turnover or other dimensions.

Alternatively, given a company with many branches spread across the Italian territory it is possible to have the one closest to us. For example, look for the closest post office to Piazza Duomo (assuming you know the Atoka ID of Poste Italiane):

https://api.atoka.io/v2/locations?companies=9302c2d7719f&ordering=distance&lat=46.067351&lon=11.121325&packages=base&distance=10000&limit=1&token=TOKEN