Usare la Company Match API per correggere ed arricchire dati approssimativi

In questo tutorial ti mostreremo l’utilizzo della Company Match API, che ti permette di 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.

Risorse

• Documentazione Company Match API.
• Codice completo di un esempio di utilizzo.

Iniziamo!

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,
            /* ... */
        },
        {
            "id": "6da785b3adf2",
            "confidence": 0.8,
            /* ... */
        },
        /* ... */
    ]
}

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.",
            /* ... */
            "base": { /* ... */ }
        }
    ]
}

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.

Quanto mi costa

Come per la ricerca aziende, la Company Match API consuma 1 credito (companies:*) per ogni azienda ottenuta con almeno un pacchetto dati. Si può evitare di spendere crediti togliendo il parametro packages dalla richiesta, e chiedere poi i dati solo dell’azienda che ci interessa in una richiesta a parte:

// consuma 0 crediti
https://api.atoka.io/v2/companies/match?regNumbers=0241890223&fuzziness=2&token=TOKEN

// consuma 1 credito companies:*
https://api.atoka.io/v2/companies/f6dde193da86?token=TOKEN&packages=base