Per un giornalista, le potenti capacità delle interfacce di programmazione delle applicazioni (API) possono essere una risorsa preziosa. In questa guida, imparerai i principi basilari su come usare le API per aiutarti nella tua ricerca e reporting di dati, così come suggerimenti e trucchetti per ottenere il massimo dalla loro implementazione.
Sommario
I giornalisti alla ricerca della loro prossima storia basata sui dati potrebbero trovare un’API altrettanto utile, se non di più, di un foglio di calcolo tradizionale. Cosa sono le API e come possono aiutare nella creazione di report? spiega Paul Bradshaw. Per guardare un’esercitazione video di Bradshaw sull’utilizzo delle API, vai alla fine di questo articolo.
Se stai cercando dati come giornalista, è probabile che tu possa trovarli in un’API. Il significato di queste tre lettere (Application Programming Interface) non è così importante: ciò che è importante per i giornalisti è che un’API è un modo per porre domande e ottenere risposte.
Cos’è un’API?
Un’API (Application Programming Interface) è un modo per consentire la comunicazione tra diverse applicazioni o siti web. In parole povere, consente alle app di parlare tra loro attraverso lo scambio di dati. Le API sono più utilizzate per semplificare le operazioni complesse e aumentano l’efficienza del processo in cui vengono comunicate informazioni tra sistemi informatici differenti.
Quindi un’API è solo un tipo di database? Beh, sì e no. Alcune API funzionano come un database, in cui puoi specificare una parola chiave o una categoria, selezionare i parametri per la tua ricerca e ottenere risultati in un formato di dati come CSV, JSON o XML.
OpenCorporates è un esempio di un sito Web che offre un’API come questa: fornisci un nome a una parte dell’API e ti fornirà i dati sui direttori dell’azienda che corrispondono (questa API è stata utilizzata per l’ indagine di Global Witness sul commercio di giada). OpenCorporates offre account gratuiti ai giornalisti e troverai video come questo in cui spiegano come utilizzare la piattaforma per le indagini.
L’API della polizia del Regno Unito, ad esempio, fornirà dati sui crimini in prossimità di un determinato luogo. Per ottenere quei dati è necessario formare un URL: un esempio fornito nella “documentazione” dell’API è https://data.police.uk/api/crimes-at-location?date=2017-02&lat=52.629729&lng= -1.131592
Quell’URL codifica fondamentalmente una particolare query. Si scompone in più parti:
- L’URL di base, che punta all’API stessa. In questo caso: https://data.police.uk/api/
- Il tipo di domanda che viene posta (un’API può supportare diversi tipi di domande). In questo caso: crimini sul posto
- Un punto interrogativo seguito da qualsiasi ingrediente utilizzato nella tua domanda. In questo caso l’esempio indica che l’API prevede una data, una latitudine e una longitudine: date=2017-02&lat=52.629729&lng=-1.131592
Se li divido in ogni e commerciale puoi vedere meglio cosa viene chiesto:
data=2017-02 & lat=52.629729 & lng=-1.131592
Gli elementi dopo ogni segno di uguale (e prima di ogni e commerciale che segue) sono i valori specifici della tua query, quindi in questo caso potresti cambiare il valore dopo ‘lat=’ e ‘lng=’ per ottenere i dati in una posizione diversa e il valore della data nel formato AAAA-MM per ottenere i dati per un periodo diverso (l’API non restituisce più i dati dal 2017, quindi in questo particolare esempio sarà necessario modificarlo a prescindere).
Quando carichi quell’URL – usa Firefox o Chrome per i migliori risultati – ti verranno forniti dati in risposta a quella query. Non sembrerà una normale pagina Web perché molto probabilmente i dati saranno in formato JSON (alcune API ti permetteranno di specificare quale formato preferisci e alcune forniscono dati in XML), che utilizza parentesi quadre e parentesi graffe per strutturare i dati.
Affrontare quel JSON (o XML) è una sfida completamente separata e oltre lo scopo di questo articolo. Normalmente richiede l’uso del codice (Python, R e JavaScript funzionano tutti bene con JSON e XML) e in definitiva è per questo che è progettata un’API: per semplificare la scrittura di script in grado di recuperare e lavorare con i dati.
Tuttavia, se desideri solo dati da una query, è possibile salvare JSON o XML (utilizzando l’opzione File> Salva del browser) e cercare “Convertitore da JSON a CSV” o “Convertitore da XML a CSV” per trovare uno dei i numerosi strumenti gratuiti che convertiranno i dati in un foglio di calcolo (come quelli su ConvertCSV).
Utilizzo delle API per la ricerca di immagini o altri media
Ma altre API ti consentono di porre una domanda sotto forma di immagine: l’ API Cloud Vision di Google, quando viene fornita un’immagine, restituirà il testo che identifica nell’immagine, elenca oggetti e valutazioni rispetto a concetti come “audace” o ” violenza’. L’API Microsoft Emotion è stata utilizzata da Periscopic, ad esempio, per produrre un’analisi delle espressioni facciali di Donald Trump durante i discorsi più importanti .
L’altra grande differenza tra un database e un’API è che alcune API non restituiscono dati in risposta a una query ma altri media come immagini e suoni: QuickChart è solo una delle numerose API che genereranno un grafico quando dati i dati. Altre API restituiranno l’audio (musica o parlato) e l’API di Google Maps ti fornirà una mappa quando viene interrogata su una coordinata lat-long.
Un’ultima differenza, cruciale per i giornalisti, è che le API vengono spesso aggiornate molto più regolarmente rispetto ai set di dati pubblicati. Alcune API forniscono l’accesso a dati in tempo reale: l’API di Twitter, ad esempio, ti dice cosa c’è sul sito in questo momento. Ciò significa che le API possono essere utilizzate per alimentare visualizzazioni interattive che vengono aggiornate ogni volta che i dati vengono — non è necessario scaricare l’ultimo foglio di calcolo, ripetere l’analisi e creare un nuovo grafico: puoi invece scrivere uno script che modifica i grafici ogni volta che i dati vengono aggiornati.
Costruire storie con le API
Le API aprono nuove possibilità per la narrazione che non sono sempre disponibili con i set di dati tradizionali. L’API di Spotify fornisce dati sulla musica e sul comportamento di ascolto che non sono accessibili in nessun altro modo. Alla BBC Data Unit l’ho utilizzato come parte di un reportage sull’equilibrio di genere nei festival musicali , mentre per una storia sui biglietti ferroviari più costosi è stato utilizzato la Distance Matrix API di Google Maps, che mi ha permesso di scoprire la distanza di un treno percorso stesso, qualcosa che non ottieni su Google Maps stesso.
Le API possono essere particolarmente utili per aumentare i dati esistenti: un certo numero di API, quando viene fornito un elenco di nomi, restituirà un genere probabile per ciascuno, insieme a un livello di confidenza. L’ API Parserator suddividerà un indirizzo nei suoi componenti separati; e ci sono più API che ti forniranno un elenco di organi amministrativi per un determinato codice postale o codice postale, aiutandoti a classificare i dati granulari per area.
Dove trovare le API
Molte fonti di dati forniranno un’API insieme ai fogli di calcolo tradizionali: vale sempre la pena prestare attenzione e verificare se offre funzionalità o informazioni aggiuntive. Ma vale anche la pena includere la parola “API” durante la ricerca di dati più in generale.
Una volta trovata un’API, cerca la “documentazione”: questa è una pagina o una raccolta di pagine che normalmente spiega come funziona l’API. Normalmente è rivolto a persone che hanno familiarità con la programmazione, quindi ci sarà un po’ di gergo con cui fare i conti, tra cui:
- Funzioni e metodi : queste sono le domande che puoi porre in un’API. L’API OpenCorporates, ad esempio, ha una “chiamata di metodo” per la ricerca dei funzionari dell’azienda e un’altra per la ricerca per numero di azienda, tra gli altri.
- Argomenti : questi sono i parametri che potresti includere quando esegui una query su un’API. Ad esempio, potrebbe essere necessario includere un argomento che specifichi il formato di file in cui si desidera ottenere i risultati o il codice postale di cui si desidera ottenere i dati.
- Chiavi API : una “chiave” è una password che alcune API potrebbero richiedere di includere nella query. Per ottenere una chiave dovrai normalmente registrarti al sito, e per usarla normalmente la includi come uno degli “argomenti” (vedi sopra).
- Limiti e quote : alcune API limiteranno il numero di query (o “richieste”) che puoi effettuare ogni ora, giorno o mese.
- Endpoint : un endpoint è un URL che generi per porre la tua domanda. Una volta caricato, l’URL dovrebbe fornire la risposta alla tua domanda, sotto forma di dati (spesso in formato JSON).
Non tutte le API sono uguali: alcune sono scarsamente documentate. Alcune potrebbero persino essere interrotte, quindi non aver paura di abbandonare un’API e provarne altre finché non sei soddisfatto.
C’è una certa curva di apprendimento coinvolta nell’uso delle API: devi conoscere un po’ di programmazione oppure chiedi aiuto da uno sviluppatore. Quindi, se hai appena iniziato, cerca tutorial che ti guidino attraverso il processo di lavoro con una particolare API e prova a scegliere API che forniscano esempi di URL che puoi adattare (l’API della polizia del Regno Unito, ad esempio, offre un ‘richiesta di esempio’ per ciascun metodo) o strumenti interattivi che consentono di generare un URL.