Newspapers API
What it is
Newspapers API lets registered news outlets and recognised news portals automatically publish their news on Nearby Community.
It works like a webhook: every time a news story is published (or updated) on the news outlet's website, the publishing system sends a request to Nearby Community, which indexes the content and shows it to users based on the location given and on their preferences.
- Real-time sync: news stories appear on Nearby moments after they're published, with no manual imports or RSS feeds read at intervals.
- Geolocated distribution: every news story is linked to a place, so it's shown first to people who are nearby or follow that area.
It's the news outlet that sends the data to Nearby Community: Nearby doesn't scrape or periodically query the source website.
To publish one news story at a time, by hand, use the Workspace: see the Workspace guide. The rules on which news is accepted are in News and Current Affairs.
Endpoint
https://webhooks.nearbycommunity.it/newspapers_webhook/submit
| Method | POST |
| Protocol | HTTPS |
| Content-Type | application/json |
| Charset | UTF-8 |
Each request must contain only one news story: to publish more than one, make one call for each article.
Authentication
Every request is authenticated with the x-newspapers-authorization header:
{
"Content-Type": "application/json; charset=UTF-8",
"x-newspapers-authorization": "YOUR_API_KEY"
}
The API KEY is issued by Nearby Community when the news outlet is activated, and it is unique to each publisher: it's with this key that the system recognises the author of the news story and links it to the right account.
The API KEY must never be put in client-side code (website JavaScript, apps, public repositories): use it only server to server. If it has been compromised, ask straight away for it to be revoked and replaced at [email protected].
If the header is missing, misspelt, or contains an invalid or revoked key, the request is automatically rejected.
The parameters
The body is JSON:
{
"newspaper_url": string,
"newspaper_image": string,
"newspaper_title": string,
"newspaper_text": string,
"newspaper_location": string
}
All fields are required and can't be empty.
newspaper_url
The address of the article's public page. It's the unique key of the news story: if you send a news story with an address that already exists, the existing story is updated instead of a new one being created. This is the right way to pass on corrections and updates.
"newspaper_url": "https://www.esempio.it/cronaca/nuova-ciclabile-corso-italia"
newspaper_image
The address of the article's image: it must be public (no login or restrictions) and on HTTPS. Allowed formats: jpg, jpeg, png and webp.
"newspaper_image": "https://www.esempio.it/media/ciclabile.jpg"
An image that can't be downloaded doesn't block publication, but it penalises the news story, which drops down the feed.
newspaper_title
The article's title, as plain text: no HTML tags or encoded entities.
"newspaper_title": "New Corso Italia cycle lane opened"
newspaper_text
An excerpt of the article, as plain text: no HTML tags or encoded entities. You don't need to send the whole article: the preview is enough (and recommended), because the full article is read on the news outlet's website, through newspaper_url.
"newspaper_text": "The ribbon was cut this morning in the presence of the mayor. The route links the station to the old town and is 3.2 kilometres long in total."
newspaper_location
The location of the news story, in one of two formats.
City or address: the Nearby Community server finds the coordinates and places the news story on the map.
"newspaper_location": "Piazza del Duomo 43, Milano, MI"
Coordinates: a longitude,latitude string, separated by a comma. You can use + and -; spaces, letters and other symbols are not allowed.
"newspaper_location": "9.1900,45.4642"
The coordinates format is preferable: it avoids confusion between places with the same name and guarantees the exact position on the map.
Example with cURL
curl -X POST https://webhooks.nearbycommunity.it/newspapers_webhook/submit \
-H "Content-Type: application/json" \
-H "x-newspapers-authorization: YOUR_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": "New Corso Italia cycle lane opened",
"newspaper_text": "The ribbon was cut this morning in the presence of the mayor. The route links the station to the old town and is 3.2 kilometres long in total.",
"newspaper_location": "9.1900,45.4642"
}'
The response
{
response: 'success' | 'no-data' | 'error',
data: string | null,
message?: string | null
}
response
| Value | Meaning |
|---|---|
success | the request was successful |
no-data | not enough data was sent |
error | there was an error on the server or in the request |
data
| Value | Meaning |
|---|---|
| string | the unique id of the news story just created |
null | with response no-data or error |
message
Optional: it describes the outcome. It's usually filled in with no-data and error, to give the reason; use it for your logs and when asking for support.
| Value | Meaning |
|---|---|
missing or null | everything went well |
error-missing-authentication | there's a problem with authentication: the header or the API KEY |
error-missing-url | newspaper_url is missing |
error-missing-image | newspaper_image is missing |
error-missing-title | newspaper_title is missing |
error-missing-text | newspaper_text is missing |
error-missing-location | newspaper_location is missing |
error-generic | a generic server error |
Retrying requests
With no-data, error, or if the server doesn't respond, repeat the call with an increasing delay (for example 5 seconds, 30 seconds, 5 minutes), without retrying straight away: the server tends to block identical calls sent at the same time or immediately one after the other.
Keeping the response, data and message of every call makes it easier to find out why a news story doesn't appear in the feed.