Ricerca Aziende

In questo tutorial vedremo come utilizzare l’API di Company Search per trovare aziende a partire da un insieme di criteri di ricerca, come il settore Ateco.

Risorse utili

• Documentazione delle API di Company Search che utilizzeremo.
• JS Fiddle con il codice per il tutorial, il riquadro in basso a destra è funzionante, inserite il vostro token, cliccate vai…
• Qui puoi controllare i crediti disponibili e consumati sul tuo token, e qui trovi informazioni più dettagliate sui crediti.

Iniziamo!

L’API di ricerca ci offre numerosi parametri per filtrare i risultati: in questo tutorial vogliamo trovare nuovi potenziali clienti tra le aziende che hanno meno di un anno di vita nel settore dell’agricoltura. Ci piacerebbe contattarli questi potenziali clienti via email (quindi vorremmo ottenere solo risultati di cui è presente l’indirizzo email).

I parametri che andremo ad utilizzare sono:

• ateco = 01 per avere solo le aziende nel settore dell’agricoltura;
• ageMax = 12 per filtrare le aziende che hanno meno di 12 mesi;
• emails = * per filtrare le aziende di cui conosciamo un qualsiasi indirizzo email.

GET https://api.atoka.io/v2/companies?packages=base,contacts&ateco=01&ageMax=12&emails=*&token=TOKEN

La risposta, modificata per brevità, contiene:

• items: è la lista dei risultati, aziende in questo caso;
• meta: contiene il numero dei risultati, l’ordinamento, limit e offset.. Informazioni 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;
• contacts: contiene tutte le informazioni fornite dal package contacts, gli indirizzi email conosciuti, i numeri di telefono con il dettaglio relativo alla sede.

{
    "items": [{
            "id": "6da785b3adf2",
            "name": "SPAZIODATI S.R.L.",
            "country": "it",
            "fullAddress": "Via Adriano Olivetti, 13, 38122, Trento (TN)",
            "base": {
                "legalName": "SPAZIODATI S.R.L.",
                "vat": "02241890223",
                "founded": "2019-02-13",
                "ateco": [{
                    "code": "01.24.00",
                    "description": "Coltivazione di pomacee e frutta a nocciolo",
                    "rootCode": "A"
                }],
                "legalForms": [ ... ],
                "registeredAddress": { ... }
            },
            "contacts": {
                "emails": [{
                    "address": "info@spaziodati.eu",
                    "type": "info",
                    "verified": true
                }],
                "phones": [{
                    "fullAddress": "Via Adriano Olivetti, 13, 38122, Trento (TN)",
                    "locationId": "0ef76064b441",
                    "number": "+39 1234 567890",
                    "source": "phone books",
                    "verified": true
                }]
            }
        }, ...],
    "meta": {
        "count": 129,
        "limit": 10,
        "offset": 0,
        "ordering": "atoka"
    }
}

Con questa richiesta otteniamo solo 10 risultati, ma dal contenuto del meta possiamo vedere che ci sono in totale 129 aziende che potrebbero essere nostri futuri clienti. Per poter vedere tutte le altre aziende è sufficiente utilizzare i parametri limit e offset per paginare:

// per avere i successivi 10 risultati
GET https://api.atoka.io/v2/companies?packages=base,contacts&ateco=01&ageMax=12&emails=*&token=TOKEN&limit=10&offset=10

Ma quanto mi costa?

Ogni azienda con almeno un pacchetto di dati costa 1 credito. La richiesta nell’esempio consumerà 10 crediti companies:* perché le API ci hanno restituito le prime 10 aziende, e per ognuna abbiamo richiesto il pacchetto base.

Atoka Trick

Possiamo spendere meno crediti evitando di richiedere il pacchetto base per tutte le aziende nella risposta (1), e selezionare poi una per una tramite il loro id le aziende che pensiamo siano veramente dei potenziali clienti e di cui vogliamo scaricare tutti i dati che ci interessano (2):

(1) GET https://api.atoka.io/v2/companies?ateco=01&emails=*&ageMax=12&token=TOKEN&limit=10  // costa 0 crediti

(2) GET https://api.atoka.io/v2/companies/6da785b3adf2?packages=base,contacts&token=TOKEN  // costa 1 credito

Per informazioni più dettagliate sul funzionamento dei crediti consulta la nostra documentazione.