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]

 


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.

 

 

Il tuo browser non è aggiornato!

Aggiornalo per vedere questo sito correttamente. Aggiorna ora

×