Input municipality names to see the corresponding companies on a map

In this tutorial, we will show you how to use two of our APIs: Locations and AdminDiv. We will use them both to display Atoka information on a map.

Useful resources

API Locations documentation
API AdminDiv documentation
Example code (JS Fiddle), in which you will find a box in the bottom right that lets you enter a token (write something, click on a suggestion and… voilà!).

The Locations API gives you information about company sites and also about the companies they belong to (e.g., NACE code). This API lets you perform complex queries combining geographical and company data.

The AdminDiv API is a helper API that contains the list of all administrative divisions (municipalities, provinces, regions) searchable by type and name prefix.

Let’s start

We want to create a simple search field that lets you select a municipality and, using this input, display on a map the locations of the top 30 companies that have local units in that municipality. Moreover, we want the search field to suggest municipalities as you type. For example, entering “tren” will suggest “Trento”, “Trentinara”, “Trenta”, but also “Tione di Trento” and so on.

The complete code is here: https://jsfiddle.net/simone\_/4esemece/ (The bottom right box is working, enter your token, write something in and click on a suggestion… voilà!)

The problem can be divided into two steps:

get the list of municipalities to suggest; and
get the list of companies for a given municipality.

For the first step we will use the endpoint admindiv:

$('#site').keyup(function() {
    /* omitted */
    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 putting the contents of the search box in the namePrefix parameter and setting 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 {type: , value: } objects:

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

The array will be used to populate the list of suggestions by passing it 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 in the array. Once the whole array is processed, the list of clickable suggestions will be displayed below the search box:

Automatic completion

For the second step, which starts when the user clicks on a municipality, cercaAziende will be invoked with the municipality name for which we want to get the list of companies:

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

Using the locations endpoint, we will perform a search passing the municipalities parameter with the chosen municipality and limiting our result set to an array with the first 30 companies that have sites located in that municipality.

This array of companies will be 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);
}

Here the array will be filtered, keeping only companies for which we have latitude and longitude. Afterwards, each entry in the list will be reduced to a {lat: , lon: } object that will be used to place the markers on the map in inizializzaMappa.

At this point you will see on the map the markers that correspond to the sites of the 30 companies in the municipality that you selected.

Companies on a map