Un tutorial
per le Atoka API

Come usare al meglio le Atoka API

1. Premessa
2. Ricavare nome e sede legale di un’azienda avendo la Partita IVA
3. Come sono organizzate le informazioni in Packages e quali sono gli endpoint per arrivarci
4. Uso di social network al variare del numero di dipendenti: faceting
5. Completamento automatico di una form anagrafica azienda [Javascript]
6. Farsi suggerire i nomi dei comuni e vederne le aziende su una mappa [Javascript]
7. Usare la Company Match API per correggere ed arricchire dati approssimativi
8. Trovare aziende nei dintorni

 


1. Premessa

Atoka, la banca dati con più di 21 milioni di imprese italiane (di cui circa 6 milioni attive oggi) e inglesi e 13 milioni di contatti verificati, permette l’accesso ai propri dati tramite queste API. Questo tutorial introduce i concetti base per poterle usare, mostrando degli esempi pratici che potrai provare.

SuperQuick reference

La documentazione completa ed ufficiale delle API: https://developers.atoka.io/v2/
L’indirizzo di base, condiviso da tutti gli endpoint, e’: https://api.atoka.io/v2/.
Ogni API segue l’architettura REST e risponde in formato JSON.

Token di accesso

Le API hanno bisogno di autenticazione, tramite un token passato ad ogni chiamata, simile a xuao1d61b5234c1e912b11856c3f4de3. Se non ne hai uno, scrivici a sales@atoka.io, saremo felici di crearne uno di prova.

 


 

 

2. Ricavare nome e sede legale di un’azienda avendo la Partita IVA

 

Per farlo basta interrogare l’endpoint companies, con il parametro vat del package base, con il tuo TOKEN, in questo modo:

 

https://api.atoka.io/v2/companies?packages=base&vat=02241890223&token=TOKEN

 

"items": [
   {
            "id": "6da785b3adf2", 
            "name": "SPAZIODATI S.R.L.",
            "country": "it",
            "fullAddress": "Viale Adriano Olivetti, 13, 38122, Trento (TN)"
            "base": {
                "legalName": "SPAZIODATI S.R.L.",
                "startup": true,
                "vat": "02241890223",
                "active": true,
                "founded": "2012-02-13",
                "ateco": [ /*omesso */ ],
                "legalForms": [ /* omesso */ ] ,
                "registeredAddress": { /* omesso */ }             
            },
        }
    ],
    "meta": {
        "ordering": "atoka",
        "count": 1,
        "offset": 0,
        "limit": 10
    }

 

La risposta, modificata per brevità, contiene:

  • items: è la lista dei risultati, aziende, che in questo caso, cercando per Partita IVA, ha un solo elemento
  • meta: contiene numero di risultati, ordine, limit ed offset.. Utili per paginare e ordinare
  • id: è l’id che Atoka usa per identificare l’azienda, usato da molte altre API
  • name, fullAddress: le informazioni che cercavamo!
  • base: contiene tutte le informazioni fornite dal package base, dettaglio dell’indirizzo, codice ATECO, natura giuridica, data di fondazione ed altro ancora

 

3. Come sono organizzate le informazioni in Packages e quali sono gli endpoint per arrivarci

Le API di Atoka sono divise in vari endpoint, tra cui:

Ed inoltre contracts, jobs, people.

All’interno di ogni endpoint, i dati sono organizzati in più package, che non sono altro che unità logiche di raggruppamento.
Nell’esempio, utilizzando il package base abbiamo recuperato l’anagrafica ed alcune informazioni di base dell’azienda. Altri package dell’endpoint companies sono:

  • contacts: telefoni ed email
  • economics: numero dipendenti, dati finanziari sui ricavi, stagionalità
  • web: dati estratti dal web quali descrizione, logo, siti web controllati, feed rss, parole chiave ed altro
  • govContracts: contratti e bandi di gara con le pubbliche amministrazioni, a cui le aziende hanno solo partecipato o che hanno vinto
  • people: informazioni sugli esponenti (manager e amministratori) e rispettivi ruoli ricoperti nell’azienda
  • shares: chi possiede chi e cosa, con ammontare e percentuali

Ed inoltre economicsLite, groups, jobs, locations, socials, technologies, entities, cervedIndicators.

Il parametro packages permette di selezionare cosa vuoi ottenere nella risposta, e dichiarare quali parametri stai usando per costruire la tua richiesta.

Ad esempio, per sapere come crescono i follower di una certa azienda userai il package socials, per ottenere email e numeri di telefono contacts e così via. Per una lista di email e telefoni di aziende che usano Twitter e Facebook, si possono usare assieme per filtrare ed arricchire la risposta.

4. Uso di social network al variare del numero di dipendenti: faceting

Vogliamo delle informazioni quantitative, divise in 4 segmenti per dimensione. Quali e quanti social sono usati da aziende fino a 5 dipendenti? Quanti da 6 a 10? 11-100? Ed oltre i 100?

Vogliamo cioè scoprire che circa il 4% delle aziende fino a 5 impiegati usa i social network, il 13% di quelle con numero impiegati compreso tra 6 e 10, il 19% nella fascia 11-100 ed infine il 31% di quelle oltre i 100 dipendenti.

Inoltre vogliamo scoprire che al salire della grandezza delle aziende Facebook diventa relativamente meno dominante, andando quasi in pari con il secondo ed il terzo social più usato, quando si parla di aziende molto grandi.

Per ottenere questo tipo di conteggi è possibile usare le facet!

Usando il parametro fields=facet le risposte non conterranno più dati aziendali, ma aggregazioni che ci dicono quante aziende corrispondono ai criteri della richiesta. Specifichiamo su che campo fare faceting, cioè dove ottenere gli aggregati, usando facetFields, nel nostro caso con valore socials.*.

Per interagire con socials e numero di dipendenti delle aziende avremo bisogno dei package socials e economics. Il numero dipendenti è filtrabile tramite employeesMin ed employeesMax.

 

Fino a 5 dipendenti:

 

https://api.atoka.io/v2/companies?packages=socials,economics&fields=facets&facetFields=socials.*&employeesMax=5&token=TOKEN

 

 "meta": { "count": 3800034 },
    "facets": {
        "socials": {
            "facebook": { "count": 145637 },
            "twitter": { "count": 35509 },
            "googleplus": { "count": 22678 },
            "youtube": { "count": 17581 },
            "instagram": { "count": 13936 },
            "linkedin": { "count": 9777 },
            "vimeo": { "count": 1648 },
            "flickr": { "count": 1290 },
        }
    }
  • meta.count ci dice quante aziende corrispondono ai filtri, aziende fino a 5 dipendenti
  • facets.socials contiene la lista di facet: per ogni valore viene riportato il numero aggregato. Circa 145 mila usano Facebook, 35 mila Twitter ecc

 

 

Da 6 a 10 dipendenti:

https://api.atoka.io/v2/companies?packages=socials,economics&fields=facets&facetFields=socials.*&employeesMin=5&employeesMax=10&token=TOKEN

 

 "meta": { "count": 376793 },
    "facets": {
        "socials": {
            "facebook": { "count": 49002 },
            "twitter": { "count": 11234 },
            "googleplus": { "count": 7499 },
            /* omesso */
        }
    }

 

 

Da 11 a 100 dipendenti:

https://api.atoka.io/v2/companies?packages=socials,economics&fields=facets&facetFields=socials.*&employeesMin=10&employeesMax=100&token=TOKEN

 

 "meta": { "count": 234119 },
    "facets": {
        "socials": {
            "facebook": { "count": 44633 },
            "twitter": { "count": 14005 },
            "youtube": { "count": 10894 },
            /* omesso */
        }
    }

 

 

Oltre 100 dipendenti:

https://api.atoka.io/v2/companies?packages=socials,economics&fields=facets&facetFields=socials.*&employeesMin=100&token=TOKEN

 

  "meta": { "count": 13503 },
    "facets": {
        "socials": {
            "facebook": { "count": 4199 },
            "twitter": { "count": 2335 },
            "youtube": { "count": 2267 },
        }
    }

 

 

In altre parole i dati dicono che Facebook è il social più usato da tutte le aziende italiane, seguito da Twitter, stabile in seconda posizione. Google Plus si aggiudica il terzo posto, ma solo tra aziende fino a 10 dipendenti, dopo questa soglia le aziende tendono a preferire YouTube. Grazie ai dati di queste 4 chiamate sono stati disegnati i grafici di cui sopra.

Seguendo la stessa procedura ed utilizzando le API in modo molto simile, è possibile analizzare e segmentare aziende lombarde, quelle con fatturato oltre i 10 milioni di euro, quelle che esistono da più di 10 anni o le startup. O qualsiasi combinazione di questi e tanti altri criteri!

5. Completamento automatico di una form anagrafica azienda [Javascript]

Partendo da una partita IVA vogliamo ottenere l’anagrafica azienda: ragione sociale, settore ATECO di appartenenza, natura giuridica, sede legale, ricavi, dipendenti, sito web, contatti email e telefonici.

Il codice completo è qui: https://jsfiddle.net/simone_/w2dsLamb/ (Il riquadro in basso a destra è funzionante, inserite il vostro token, cliccate vai... et-voilà!) L’HTML ed il CSS non sono granchè interessanti, qualche input, un po’ di margini, due colori.
Il codice Javascript invece esegue la chiamata alla API e popola i risultati.

 

Quando si clicca sul pulsante, viene eseguito questo handler:

$('#vai').click(function() {
    let token = $('#token').val(),
        piva = $('#piva').val(),
        url = `https://api.atoka.io/v2/companies?token=${token}`;


    $.post(url, {
        vat: piva,
        packages: 'base,economics,contacts,web'
    }).done(displayData);


    return false;
});

 

 

Vengono letti token e partita IVA e generato l’URL delle API. Da notare che il token è inserito nella query string e non nel body della chiamata.

Viene eseguita una chiamata AJAX in modalità POST, passando i parametri vat e packages. Per ottenere i dati desiderati avremo bisogno di base, economics contacts e web. E’ necessario usare il metodo POST per aggirare i controlli di sicurezza CORS.

Il risultato della chiamata viene gestito dalla funzione displayData, di cui riportiamo un estratto:

function displayData(data) {
    let azienda = data.items[0];
    console.log('Atoka data:', azienda);

    $('#ragioneSociale').html(azienda.name);
    $('#sedeLegale').html(azienda.fullAddress);
    $('#ateco').html(
        azienda.base.ateco[0].code + ': ' + 
        azienda.base.ateco[0].description
    );

    // ecc

    if (azienda.contacts.phones) {
        $('#telefono').html(
            azienda.contacts.phones[0].number +
            ' (' + azienda.contacts.phones.length + ' in totale)'
        );
    }
}

 

 

... che non fa altro che usare il JSON per mettere i vari pezzi al loro posto.

Il risultato di questo endpoint è comunque un array di items (aziende), ma visto che filtriamo per partita IVA possiamo essere sicuri che il risultato sia uno solo (o nessuno, se la partita IVA non esiste), il primo elemento dell’array data.items[0].

Da notare l’ultimo blocco con l’if: prima di stampare il numero di telefono verifichiamo che azienda.contacts.phones sia truthy, cioè presente nell’oggetto. Inoltre, essendo phones un array, possiamo decidere se mostrarli tutti o solo il più significativo (il primo) e dare semplicemente visibilità del loro numero complessivo.

Inserendo la partita IVA 07516911000, vedrete qualcosa di simile a:

6. Farsi suggerire i nomi dei comuni e vederne le aziende su una mappa [Javascript]

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 codice completo è qui: https://jsfiddle.net/simone_/4esemece/ (Il riquadro in basso a destra è funzionante, inserite il vostro token, scrivete qualcosa e cliccate un suggerimento...et-voilà!)

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() {
    /* omesso */
    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:

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) {
    /* omesso */
    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.

 

7. Usare la Company Match API per correggere ed arricchire dati approssimativi

La Company Match API può trovare risultati in caso di dati di partenza imprecisi, errati o incompleti (ad esempio un numero di telefono non più utilizzato) ed è quindi l’ideale per verificare la correttezza del proprio database o aggiornarlo con gli ultimi dati disponibili su Atoka.

Immaginiamo, ad esempio, di avere una partita IVA trascritta in modo inesatto, da cui non è possibile risalire all’azienda.

https://api.atoka.io/v2/companies?packages=base&regNumbers=0241890223&token=TOKEN
    "meta": {
    "limit": 10,
    "ordering": "atoka",
    "offset": 0,
    "count": 0
  },
  "items": []

 

Usando l’endpoint companies infatti non viene restituito nessun risultato.

Grazie all’API Company Match, possiamo effettuare una ricerca “fuzzy” che, anche a partire da dati imprecisi o incompleti, propone una lista di risultati che potrebbero corrispondere alla richiesta. Interrogando l’endpoint companies/match possiamo stabilire la precisione richiesta usando il parametro fuzziness. Non è necessario abilitare alcun package.

https://api.atoka.io/v2/companies/match?regNumbers=0241890223&fuzziness=2&token=TOKEN
 "meta": {
    "limit": 10,
     "count": 63
  },
  "items": [
    {
      "id": "f6dde193da86",
       "confidence": 0.8,
      /* omesso */
    },
    {
      "id": "6da785b3adf2",
       "confidence": 0.8,
      /* omesso */
    },
    /* omesso */
  ]

 

La risposta è molto simile a quella di una normale ricerca, con l’aggiunta del valore confidence (0-1), che indica quanto il risultato soddisfa i criteri di ricerca ed è usato per ordinare i risultati. A questo punto possiamo aggiungere parametri (ad esempio name) per raffinare la ricerca ed usare il parametro minConfidence per ridurre il numero di risultati.

https://api.atoka.io/v2/companies/match?packages=base&regNumbers=0241890223&name=spaziodati&minConfidence=0.8&fuzziness=2&token=TOKEN
  "meta": {
    "limit": 10,
    "count": 66
  },
  "items": [
    {
      "id": "f6dde193da86",
      "confidence": 0.8212,
      "name": "SPAZIODATI S.R.L.",
      /* omesso */
      "base": { /* omesso */ }
    }
  ]

 

Aggiungendo il package base otteniamo più dati sull’azienda, permettendoci di verificare che l’azienda restituita è effettivamente quella cercata. Tutti i package disponibili per gli endpoint companies sono utilizzabili anche con la Company Match API.

 

Parametri rilevanti

È importante notare che lo scopo della Company Match API non è trovare un insieme di imprese rispondenti a determinati requisiti, ma piuttosto identificare un’azienda a partire dai dati a propria disposizione. Per questo motivo, è necessario fornire almeno un parametro rilevante che possa cioè identificare un’azienda specifica. Nel caso non ne venga usato almeno uno verrà restituito un errore.

https://api.atoka.io/v2/companies/match?municipalities=trento&token=TOKEN
  "error": true,
  "message": "No relevant filters provided",
  "statuscode": 400

 

Alcuni esempi di parametri rilevanti sono name, regNumbers, emails; l’elenco completo, assieme a tutte le informazioni sulla Company Match API, si trova nella documentazione.

 

8. Trovare aziende nei dintorni

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.

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"
  },/* omesso */]

 

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

 

Abbiamo cercato le sedi di aziende:

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

    },..
  ]

 

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 nel 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