Farsi suggerire i nomi dei comuni e vederne le aziende su una mappa

In questo tutorial ti mostremo come utilizzare due API molto utili per integrare le informazioni delle aziende di Atoka in una mappa.

Risorse

Le Locations API ti forniscono le informazioni relative alle sedi (sia legali che secondari) delle aziende; inoltre contengono anche alcune informazioni relative alle aziende (e.g. codice Ateco) che ci permettono di effettuare query di ricerca incrociando sia dati geografici che aziendali.

L’AdminDiv API è uno strumento di supporto che contiene la lista di tutte le divisioni amministrative (comuni, province, regioni) ricercabili per tipologia e prefisso del nome.

Iniziamo!

Vogliamo realizzare un semplice campo di ricerca che permetta di selezionare un comune, per poi vederne le sedi delle prime 30 aziende su una mappa. Vogliamo che il campo di ricerca suggerisca i comuni mentre l’utente digita. Ad esempio inserendo “tren” suggerirà “Trento”, “Trentinara”, “Trenta” ma anche “Tione di Trento” eccetera.

Il problema si può dividere in due passi:

  • ottenere la lista dei comuni da suggerire;
  • ottenere la lista di aziende per un dato comune.

Per il primo passo utilizzeremo l’endpoint admindiv:

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

Ogni volta che l’utente interagisce con la casella di ricerca, l’handler eseguirà una chiamata alle API, passando quanto digitato tramite il parametro namePrefix, countries=it, (Italia) e types=municipality (per ottenere solo i comuni, escludendo quindi regioni, province, ecc).

Questa chiamata restituirà un semplice JSON con un array di coppie {type: , value: }:

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

L’array viene passato a 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);
}

A questo punto per ogni elemento verrà creato un suggerimento cliccabile, posizionato sotto alla casella di ricerca:

Automatic completion

Quando l’utente clicca su un comune verrà invocata la cercaAziende con il nome del comune, dal quale vogliamo ricavare la lista di aziende con la seconda chiamata alle API:

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

All’endpoint locations quindi passiamo il parametro municipalities con il comune scelto ed otteniamo una lista di 30 aziende di quel comune.

La lista viene passata a 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);
}

Ora l’array viene filtrato, tenendo solo le aziende per le quali disponiamo di latitudine e longitudine. Poi i dati dell’azienda vengono ridotti ad una sola coppia {lat: , lon: } che useremo per posizionare i marker sulla mappa tramite la inizializzaMappa.

A questo punto si vedranno i marker corrispondenti alle posizioni delle sedi delle 30 aziende del comune selezionato su una mappa.

Companies on a map