Newspapers API
Definizione e Scopo
Newspapers API è un prodotto di Nearby Community che permette a testate giornalistiche registrate e portali di informazione riconosciuti di pubblicare automaticamente le proprie notizie all'interno di Nearby Community.
Il servizio funziona come un webhook: ogni volta che una notizia viene pubblicata (o aggiornata) sul portale della testata, il sistema editoriale invia una richiesta all'endpoint di Nearby Community, che si occupa di indicizzare il contenuto e di renderlo visibile agli utenti in base alla posizione geografica indicata ed alle preferenze in ambito di notizie.
Lo scopo del servizio è quindi duplice:
- Sincronizzazione in tempo reale — le notizie compaiono nel feed di Nearby Community pochi istanti dopo la pubblicazione, senza necessità di importazioni manuali o di feed RSS interrogati periodicamente.
- Distribuzione geolocalizzata — ogni notizia viene associata a un luogo, così da essere mostrata prioritariamente agli utenti che si trovano nelle vicinanze o che seguono quell'area.
L'integrazione è push: è la testata a inviare i dati a Nearby Community, che non effettua alcuna operazione di scraping o polling sul sito di origine.
Endpoint
L'unico endpoint per la pubblicazione delle notizie su Nearby Community è definito come:
https://webhooks.nearbycommunity.it/newspapers_webhook/submit
| Valore | Significato |
|---|---|
| Metodo | POST |
| Protocollo | HTTPS |
| Content-Type | application/json |
| Charset | UTF-8 |
Ogni richiesta deve contenere una sola notizia. Per pubblicare più notizie è necessario effettuare più chiamate, una per ciascun articolo.
Autenticazione
Per la riuscita della connessione al servizio è necessario autenticarsi mediante Headers con la key x-newspapers-authorization come di seguito:
{
"Content-Type": "application/json; charset=UTF-8",
"x-newspapers-authorization": "LA_TUA_API_KEY"
}
La API KEY viene rilasciata da Nearby Community in fase di attivazione della testata ed è univoca per ogni editore: è tramite questa chiave che il sistema riconosce l'autore della notizia e la associa all'account corretto.
La API KEY è un dato riservato. Non deve essere inserita in codice lato client (JavaScript di frontend, app mobile, repository pubbliche) e va utilizzata esclusivamente da server a server. In caso di compromissione è necessario richiederne immediatamente la revoca e la sostituzione tramite una mail a support@nearbycommunity.it.
Se l'header è assente, malformato o contiene una chiave non valida o revocata, la richiesta viene rifiutata automaticamente.
Parametri
I parametri da inviare vengono inviati tramite un body json come di seguito:
{
"newspaper_url": string,
"newspaper_image": string,
"newspaper_title": string,
"newspaper_text": string,
"newspaper_location": string
}
Tutti i campi sono obbligatori e non possono essere vuoti o falsy.
Campo newspaper_url
Deve puntare alla pagina pubblica dell'articolo. Poiché il valore funge da chiave univoca, l'invio di una notizia con un URL già presente aggiorna il contenuto esistente anziché crearne uno nuovo: è quindi la modalità corretta per propagare correzioni e aggiornamenti.
Esempio
"newspaper_url": "https://www.esempio.it/cronaca/nuova-ciclabile-corso-italia"
Campo newspaper_image
L'url dell'immagine dell'articolo, deve essere raggiungibile pubblicamente (nessuna autenticazione, nessun blocco) e servita in HTTPS. Sono ammessi i formati jpg, jpeg, png e webp.
Esempio
"newspaper_image": "https://www.esempio.it/media/ciclabile.jpg"
Un URL immagine non raggiungibile non blocca la pubblicazione, ma penalizza la resa della notizia nel feed e la sposta più in basso.
Campo newspaper_title
Il titolo dell'articolo, testo semplice senza tag HTML e senza entità codificate
Esempio
"newspaper_title": "Inaugurata la nuova pista ciclabile di Corso Italia"
Campo newspaper_text
Un estratto dell'articolo, testo semplice senza tag HTML e senza entità codificate. Non è necessario trasmettere l'intero articolo: è sufficiente e consigliato inviare l'anteprima, poiché la lettura completa avviene sul sito della testata, reindirizzato tramite newspaper_url.
Esempio
"newspaper_text": "Il taglio del nastro si è tenuto questa mattina alla presenza del sindaco. Il tratto collega la stazione al centro storico per un totale di 3,2 chilometri."
Campo newspaper_location
Formato con Indirizzo o Città
È possibile inserire direttamente il nome della città o l'indirizzo del luogo, in questo modo il server di Nearby Community effettua un reverse geocoding ed assegna direttamente le coordinate alla notizia in modo da visualizzarla correttamente nella mappa
Esempio
"newspaper_location": "Milano, MI"
"newspaper_location": "Piazza del Duomo, Milano, MI"
"newspaper_location": "Piazza del Duomo 43, Milano, MI"
Formato con Coordinate
È possibile inserire direttamente una stringa contente le coordinate in formato "longitudine,latitudine" avente come separatore la virgola ",". È permesso usare i simboli "+" e "-" per identificare coordinate positive o negative, non sono ammessi spazi, lettere o altri simboli.
Esempio
"newspaper_location": "9.1900,45.4642"
Il formato con le coordinate è preferibile, in quanto evita le ambiguità tra i toponimi e garantisce il posizionamento preciso sulla mappa
Invio della richiesta con cURL
curl -X POST https://webhooks.nearbycommunity.it/newspapers_webhook/submit \
-H "Content-Type: application/json" \
-H "x-newspapers-authorization: LA_TUA_API_KEY" \
-d '{
"newspaper_url": "https://www.esempio.it/cronaca/nuova-ciclabile-corso-italia",
"newspaper_image": "https://www.esempio.it/media/ciclabile.jpg",
"newspaper_title": "Inaugurata la nuova pista ciclabile di Corso Italia",
"newspaper_text": "Il taglio del nastro si è tenuto questa mattina alla presenza del sindaco. Il tratto collega la stazione al centro storico per un totale di 3,2 chilometri.",
"newspaper_location": "9.1900,45.4642"
}'
Risposta
La risposta che si riceve dal server è di tipo:
{
response: 'success' | 'no-data' | 'error',
data: string | null,
message?: string | null
}
Proprietà response
| Valore | Significato |
|---|---|
success | La richiesta è stata eseguita correttamente e la risposta è valida |
no-data | Non sono stati forniti sufficienti dati per l'esecuzione della richiesta |
error | Si è verificato un errore nel server o nella richiesta |
Proprietà data
| Valore | Significato |
|---|---|
| string | ID univoco della notizia appena creata sul server |
| null | In caso di response: no-data oppure response error |
Proprietà message
Campo opzionale che descrive l'esito in forma leggibile. È tipicamente valorizzato nei casi no-data ed error, dove indica il motivo del mancato inserimento, e va utilizzato per il logging lato editore, o per, eventualmente richiedere assistenza.
| Valore | Significato |
|---|---|
| undefined | Valore ottimale, tutto è stato eseguito correttamente |
| null | Valore ottimale, tutto è stato eseguito correttamente |
error-missing-authentication | Esiste un problema con l'autenticazione, potrebbe essere un problema di header oppure di api key errata |
error-missing-url | Valore per newspaper_url mancante, impossibile procedere con la richiesta |
error-missing-image | Valore per newspaper_image mancante, impossibile procedere con la richiesta |
error-missing-title | Valore per newspaper_title mancante, impossibile procedere con la richiesta |
error-missing-text | Valore per newspaper_text mancante, impossibile procedere con la richiesta |
error-missing-location | Valore per newspaper_location mancante, impossibile procedere con la richiesta |
error-generic | Valore che indica un errore generico lato server |
Gestione Retry
In caso di risposta no-data, error, o di mancata risposta del server, ripetere la chiamata con un ritardo progressivo (ad esempio 5s, 30s, 5 minuti) anziché insistere immediatamente. Il server tende a blacklistare chiamate identiche simultaee o immediatamente sucessive.
Conservare response, data e message di ogni chiamata semplifica la diagnosi di eventuali notizie non comparse nel feed.