Local News

The /v1/news/local endpoint returns news around a single geographic point — given either lat/lng coordinates or a place name — and ranks the results by distance. Unlike the plain geo filter on /v1/news/everything, it sorts by proximity, adds distance_km and nearest_location to every article, and can attach an optional local intelligence dashboard.

Endpoint

GET  /v1/news/local
POST /v1/news/local

Both methods are equivalent: parameters can be passed as query parameters (GET) or as a JSON body (POST).

Local endpoint vs. the geo filter

/v1/news/local uses bare lat, lng and radius parameters, while the geo filter on /v1/news/everything uses the dotted location.lat, location.lng and location.radius form. Both find articles near a point, but /v1/news/local adds features the filter does not: proximity sorting, per-article distance_km and nearest_location, place-name geocoding, relevance ranking presets, and aggregate local_insights. If you only need a geographic constraint on a normal search, use the geo filter instead.

Query Parameters

The endpoint accepts every filter available on /v1/news/everything (for example language.code, category.id, published_at.start), plus the local-specific parameters below.

Parameter	Type	Required	Description
lat	float	Yes*	Latitude of the center point (-90 to 90). Must be sent together with lng.
lng	float	Yes*	Longitude of the center point (-180 to 180). Must be sent together with lat.
place	string	Yes*	A place name to geocode instead of lat/lng (for example Berlin).
country	string	No	Two-letter country code that narrows a place lookup (for example de).
radius	integer	No	Search radius in kilometers. Default 50, maximum 20000.
sort	string	No	distance (default), published_at, or relevance.
ranking	string	No	Weighting preset used when sort=relevance: balanced (default), proximity, authority, fresh.
w.distance / w.opr / w.recency / w.important	float	No	Override individual relevance weights (used with sort=relevance).
insights	string	No	Comma-separated list of local insight blocks to compute (see below).
per_page	integer	No	Number of articles per page. Default 100, maximum 250.
page	integer	No	Page of results, starting at 1.

* You must supply a center: either both lat and lng, or a place.

Response Format

{
  "status": "ok",
  "query": { "lat": 52.52, "lng": 13.4, "radius_km": 50, "sort": "distance" },
  "total": 128,
  "results": [
    {
      "id": 0,
      "title": "string",
      "href": "string",
      "distance_km": 3.2,
      "nearest_location": {
        "entity_id": 0,
        "name": "string",
        "lat": 52.51,
        "lng": 13.41,
        "country": "de"
      }
    }
  ]
}

Response Fields

Field	Type	Description
status	string	Always ok on success.
query	object	The center and settings that were used: lat, lng, radius_km, sort. When place is used it also carries place and resolved_entity_id.
total	integer	Exact number of matching articles inside the radius.
results	array	Article objects (same shape as /v1/news/everything) with the extra fields below.
results[].distance_km	float	Distance from the center to the article's nearest matched location.
results[].nearest_location	object	Closest matched place: entity_id, name, lat, lng, country.
results[].relevance_score	float	Present only when sort=relevance.
ranking_weights	object	The effective relevance weights (present when sort=relevance).
local_insights	object	Present only when insights is requested (see below).

Local insights

Pass the insights parameter — a comma-separated list — to compute aggregate intelligence over the radius. The results appear under a local_insights object alongside the article list. Allowed blocks are:

mood, hotspots, events, entities, bias, sources, timeline, top_categories, top_topics, breaking, velocity, movers.

An unknown value returns 400 ER0420. In the response, four blocks are keyed by their aggregated form: events → top_events, entities → top_entities, bias → bias_split, sources → top_sources; the rest keep their names. The movers block surfaces entities and topics accelerating against their 14-day baseline, scoped to the radius.

Billing

A /v1/news/local call costs 1 point for the article listing, plus 1 additional point for each requested insight block. A request with no insights costs 1 point; insights=mood,hotspots,breaking costs 4 points (1 + 3). Points are charged only when the response contains at least one article.

Request Examples

cURL

curl "https://api.apitube.io/v1/news/local?lat=52.52&lng=13.40&radius=50&api_key=YOUR_API_KEY"

Python

import requests

resp = requests.get(
    "https://api.apitube.io/v1/news/local",
    params={"lat": "52.52", "lng": "13.40", "radius": "50", "api_key": "YOUR_API_KEY"},
)
print(resp.json())

Node.js

const params = new URLSearchParams({ lat: "52.52", lng: "13.40", radius: "50", api_key: "YOUR_API_KEY" });
const resp = await fetch(`https://api.apitube.io/v1/news/local?${params}`);
console.log(await resp.json());

PHP

$query = http_build_query(["lat" => "52.52", "lng" => "13.40", "radius" => "50", "api_key" => "YOUR_API_KEY"]);
$data = json_decode(file_get_contents("https://api.apitube.io/v1/news/local?$query"), true);
print_r($data);

Geocode a place name and rank by relevance

curl "https://api.apitube.io/v1/news/local?place=Berlin&country=de&radius=30&sort=relevance&ranking=authority&api_key=YOUR_API_KEY"

Attach a local insights dashboard

curl "https://api.apitube.io/v1/news/local?lat=52.52&lng=13.40&radius=50&insights=mood,hotspots,breaking&api_key=YOUR_API_KEY"

Error Responses

Code	Status	Meaning
ER0406	400	No center provided — send lat and lng together, or a place.
ER0407	400	lat must be a valid latitude between -90 and 90.
ER0408	400	lng must be a valid longitude between -180 and 180.
ER0409	400	radius must be a positive number up to 20000 km.
ER0420	400	Unknown value in insights.
ER0421	400	The place could not be geocoded — try a more specific name, add country, or pass lat/lng.