Newspapers API
Cos'è
Newspapers API permette alle testate giornalistiche registrate e ai portali di informazione riconosciuti di pubblicare automaticamente le proprie notizie su Nearby Community.
Funziona come un webhook: ogni volta che una notizia viene pubblicata (o aggiornata) sul sito della testata, il sistema editoriale invia una richiesta a Nearby Community, che indicizza il contenuto e lo mostra agli utenti in base al luogo indicato e alle loro preferenze.
- Sincronizzazione in tempo reale: le notizie compaiono su Nearby pochi istanti dopo la pubblicazione, senza importazioni a mano o feed RSS letti periodicamente.
- Distribuzione geolocalizzata: ogni notizia è legata a un luogo, così viene mostrata prima a chi si trova vicino o segue quella zona.
È la testata a inviare i dati a Nearby Community: Nearby non fa scraping né interroga periodicamente il sito di origine.
Per pubblicare una notizia alla volta, a mano, usa il Workspace: vedi la guida del Workspace. Le regole sulle notizie accettate sono in Notizie ed Attualità.
Endpoint
https://webhooks.nearbycommunity.it/newspapers_webhook/submit
| Metodo | POST |
| Protocollo | HTTPS |
| Content-Type | application/json |
| Charset | UTF-8 |
Ogni richiesta deve contenere una sola notizia: per pubblicarne più di una fai una chiamata per ogni articolo.
Autenticazione
Ogni richiesta si autentica con l'header x-newspapers-authorization:
{
"Content-Type": "application/json; charset=UTF-8",
"x-newspapers-authorization": "LA_TUA_API_KEY"
}
La API KEY viene rilasciata da Nearby Community quando la testata viene attivata ed è unica per ogni editore: è con questa chiave che il sistema riconosce l'autore della notizia e la associa all'account giusto.
La API KEY non va mai inserita in codice lato client (JavaScript del sito, app, repository pubblici): si usa solo da server a server. Se è stata compromessa, chiedine subito la revoca e la sostituzione a [email protected].
Se l'header manca, è scritto male o contiene una chiave non valida o revocata, la richiesta viene rifiutata automaticamente.
I parametri
Il body è un JSON:
{
"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.
newspaper_url
L'indirizzo della pagina pubblica dell'articolo. È la chiave univoca della notizia: se invii una notizia con un indirizzo già presente, la notizia esistente viene aggiornata invece di crearne una nuova. È il modo corretto per propagare correzioni e aggiornamenti.
"newspaper_url": "https://www.esempio.it/cronaca/nuova-ciclabile-corso-italia"
newspaper_image
L'indirizzo dell'immagine dell'articolo: deve essere pubblica (senza login né blocchi) e in HTTPS. Formati ammessi: jpg, jpeg, png e webp.
"newspaper_image": "https://www.esempio.it/media/ciclabile.jpg"
Un'immagine che non si riesce a scaricare non blocca la pubblicazione, ma penalizza la notizia, che scende nel feed.
newspaper_title
Il titolo dell'articolo, come testo semplice: niente tag HTML né entità codificate.
"newspaper_title": "Inaugurata la nuova pista ciclabile di Corso Italia"
newspaper_text
Un estratto dell'articolo, come testo semplice: niente tag HTML né entità codificate. Non serve inviare tutto l'articolo: basta (ed è consigliato) l'anteprima, perché la lettura completa avviene sul sito della testata, tramite newspaper_url.
"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
Il luogo della notizia, in uno di due formati.
Città o indirizzo: il server di Nearby Community trova le coordinate e posiziona la notizia sulla mappa.
"newspaper_location": "Piazza del Duomo 43, Milano, MI"
Coordinate: una stringa longitudine,latitudine, separate dalla virgola. Si possono usare + e -; non sono ammessi spazi, lettere o altri simboli.
"newspaper_location": "9.1900,45.4642"
Il formato con le coordinate è preferibile: evita le ambiguità tra luoghi con lo stesso nome e garantisce la posizione esatta sulla mappa.
Esempio 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"
}'
La risposta
{
response: 'success' | 'no-data' | 'error',
data: string | null,
message?: string | null
}
response
| Valore | Significato |
|---|---|
success | la richiesta è andata a buon fine |
no-data | non sono stati inviati abbastanza dati |
error | c'è stato un errore nel server o nella richiesta |
data
| Valore | Significato |
|---|---|
| string | l'id univoco della notizia appena creata |
null | con response no-data oppure error |
message
Facoltativo: descrive l'esito. È valorizzato di solito con no-data ed error, per indicare il motivo; usalo per i log e per chiedere assistenza.
| Valore | Significato |
|---|---|
assente o null | tutto è andato bene |
error-missing-authentication | c'è un problema con l'autenticazione: l'header o la API KEY |
error-missing-url | manca newspaper_url |
error-missing-image | manca newspaper_image |
error-missing-title | manca newspaper_title |
error-missing-text | manca newspaper_text |
error-missing-location | manca newspaper_location |
error-generic | un errore generico del server |
Ripetere le richieste
Con no-data, error o se il server non risponde, ripeti la chiamata con un ritardo crescente (per esempio 5 secondi, 30 secondi, 5 minuti), senza insistere subito: il server tende a bloccare le chiamate identiche contemporanee o immediatamente successive.
Conservare response, data e message di ogni chiamata semplifica la ricerca delle notizie che non compaiono nel feed.