In questo tutorial ti mostriamo un esempio di utilizzo delle API, ispirato allo use case di un nostro cliente.

Vogliamo fornire ad un rappresentante di una ditta di prodotti alimentari la lista delle aziende nel settore della ristorazione (ristoranti, mense, bar, ecc..) che si trovano a poca distanza dalla sua posizione.

Risorse

Iniziamo

La Location Search API offre sia la possibilità di ordinare per distanza le sedi aziendali, sia di definire la distanza da un punto entro la quale cercare.

Supponiamo che il nostro agente si trovi in centro a Trento (latitudine e longitudine 46.067351, 11.121325). Cerchiamo quindi il settore Ateco dei nostri potenziali clienti utilizzando l’endpoint dedicato:

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

Ora possiamo cercare le sedi di aziende in questo settore nel raggio di 500 metri dal punto dato:

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,
                    /* ... */ 
                },
                "company": { 
                    "legalName": "GROMART S.R.L.",
                    "id": "893c134733c8"
                }, 
                /* ... */ 
            }
        },
        /* ... */
    ]
}

Abbiamo cercato le sedi di aziende:

  • nel settore della ristorazione (companyAteco=56);
  • nel raggio di 500 metri (distance=500);
  • dal centro di Trento (lat=46.067351 lon=11.121325);
  • ordinate per distanza a partire dal punto specificato (ordering=distance).

Possiamo utilizzare anche altri filtri per raffinare la nostra ricerca, come registered per ottenere solo quelle con sede legale all’interno del perimetro specificato, o anche filtri su altre informazioni base dell’azienda.

Se invece il nostro agente necessita di una query più complessa, che coinvolge caratteristiche dell’azienda non contenute nei filtri delle sedi, la Company Search API può esserci d’aiuto.

Supponiamo di voler limitare la ricerca precedente alle aziende nate nell’ultimo anno.
Utilizziamo l’endpoint companies con gli stessi parametri lat, lon e distance per definire il punto di partenza ed il raggio, ordering=distance per ordinare i risultati, ateco=56 per il settore ed aggiungiamo ageMax=12 per filtrare le aziende nate negli ultimi 12 mesi. Includiamo anche il parametro anyAddress=true per considerare tutte le sedi e non solo la sede legale.

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,
                    /* ... */ 
                },
                /* ... */ 
            },
            "locations": { 
                "items": [{  /* lista di indirizzi di eventuali altre sedi */
                    "address": { 
                        "distance": 210312,  /* distanza per ogni indirizzo */
                        /* ... */
                    }
                }],
                /* ... */ 
            }
        },
        ...
    ]
}

Seguendo la stessa procedura e utilizzando le API con il parametro ‘fields=facets’ in modo molto simile, è possibile analizzare e segmentare le aziende nei dintorni, per settore Ateco, per fatturato o altre dimensioni.

In alternativa, data un’azienda con molte sedi sparse sul territorio italiano è possibile avere quella che si trova più vicino a noi. Per esempio, cerchiamo l’ufficio postale più vicino a piazza Duomo (supponendo di conoscere l’Atoka ID di 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

Quanto mi costa

In questo tutorial abbiamo utilizzato l’endpoint Locations, che ci fornisce dati relativi alle sedi delle aziende, e di conseguenza consuma crediti di tipo locations:*: come per le aziende, ogni sede ottenuta nei risultati (con almeno un pacchetto) consumerà un credito.

Atoka Trick

Se non ci interessa mostrare subito tutte le aziende sulla mappa possiamo risparmiare qualche credito con questo trucchetto. Quando cerchiamo le aziende nelle vicinanze, evitiamo di passare il parametro packages: avremo comunque i risultati ordinati per distanza dal più vicino al più lontano, ma non vedremo tutti i dettagli relativi alla posizione. Quando il nostro agente avrà scelto quale azienda vuole andare a visitare per prima e visualizzarla sulla mappa possiamo chiedere il dettaglio di quella sede passando l’id:

// consuma 0 crediti
https://api.atoka.io/v2/locations?companyAteco=56&lat=46.067351&lon=11.121325&distance=500&ordering=distance&token=TOKEN

// consuma 1 credito
https://api.atoka.io/v2/locations?ids=<id>&packages=base&token=TOKEN