Atoka API Tutorial
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
7. Use the Company Match API to correct and enrich approximate data
8. Finding businesses around
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.
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.
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 firstname.lastname@example.org, we would be happy to create a trial one for you.
The answer modified for brevity, contains:
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:
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.
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?
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.
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.*.
Up to 5 employees:
From 6 to 10 employees:
From 11 to 100 employees:
More than 100 employees:
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!
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.
When you click the button, this handler runs:
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:
...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 .
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.
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:
For the first step we will use the endpoint admindiv:
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:
The array is passed to mostraSuggerimenti:
At this point, a clickable suggestion will be created for each item, located below the search box:
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:
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:
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.
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.
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.
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.
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.
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.
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:
Now we can search companies in this area within 500 meters from the given point:
We searched for business locations:
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.
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):