Make suggestions for names of municipalities and see companies on a map

In this tutorial we'll show you how to use two very useful API to integrate the awesome company information of Atoka on a map.

Useful resources

The Locations API provide you information about the companies local units, and they also contain data about the companies (e.g. NACE code) that allow us to perform complex queries combining geographical data and company data. 

The AdminDiv API is an utility tool 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 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