Local News

Find news near a location with /v1/news/local. Send lat/lng coordinates or a place name. Results are sorted by distance and include distance_km and nearest_location. You can also request summaries of local coverage.

Endpoint

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

GET and POST return the same results. Send parameters in the URL with GET or as JSON in the request body with POST.

Local endpoint vs. the geo filter

For /v1/news/local, use lat, lng and radius. The geo filter on /v1/news/everything uses location.lat, location.lng and location.radius. Both select news near a point. The local endpoint also supports sorting by distance, distance_km, nearest_location, place names, relevance ranking and local_insights.

Query Parameters

The endpoint accepts the shared Filters, plus the local parameters listed below.

Choose a center with both lat and lng, or with place. If you send both, the API uses the coordinates. On Basic and above, you can also use prompt, but you must still send the center separately.

Local parameters

Parameter	Type	Required	Description
lat	number	No	Latitude of the search center (required unless place is given). Range: -90–90.
lng	number	No	Longitude of the search center (required unless place is given). Range: -180–180.
place	string	No	Use a place name, such as Berlin, as the search center. For ambiguous names, add country or send lat/lng. Coordinates take priority when both are sent. Example: Berlin.
country	string	No	Two-letter ISO 3166-1 alpha-2 country code. Add it when a place name exists in several countries (e.g. de). Example: de.
radius	number	No	Search radius in kilometers (default 50, max 20000). Range: max 20000, > 0. Default: 50.
sort	string	No	Sort order: nearest first (distance), newest first (published_at), or relevance (blends proximity + source authority + recency + breaking; adds relevance_score to each article). One of: distance, published_at, relevance. Default: distance.
ranking	string	No	Choose how relevance is ranked when sort=relevance: balanced, proximity (distance), authority (source rank) or fresh (recency). Use w.* parameters to adjust individual weights. One of: balanced, proximity, authority, fresh. Default: balanced.
w.distance	number	No	How much distance affects the relevance score. Overrides the selected preset. Range: min 0.
w.opr	number	No	How much source rank affects the relevance score. Overrides the selected preset. Range: min 0.
w.recency	number	No	How much article age affects the relevance score. Overrides the selected preset. Range: min 0.
w.important	number	No	How much breaking-news importance affects the relevance score. Overrides the selected preset. Range: min 0.
insights	string	No	List the local summaries you want, separated by commas: mood, hotspots, events, entities, bias, sources, timeline, top_categories, top_topics, breaking, velocity, movers. For the most accurate velocity and movers results, omit the published_at filter. Each block costs 1 extra point. Example: top_categories,breaking,movers.

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 fields 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

To get summaries for the search area, list the blocks you want in insights, separated by commas. The response includes them in local_insights. Available blocks are:

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

An unknown value returns 400 ER0420. Four blocks have different names in the response: events becomes top_events, entities becomes top_entities, bias becomes bias_split, and sources becomes top_sources. Other blocks keep their names.

The movers block finds entities and topics gaining attention within your search radius. It compares recent coverage with the previous 14 days.

Insights can increase response time

Requesting more insight blocks can slow down the response. Broad searches with hotspots may time out with 502.

Request only the blocks you need, two or three at a time. Add article filters to narrow the search before requesting insights.

Billing

Each /v1/news/local request costs 1 point plus 1 point per requested insight block. Without insights, it costs 1 point. With insights=mood,hotspots,breaking, it costs 4 points. You are charged only if the response contains articles.

Request Examples

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

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())

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());

$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 API could not find coordinates for place. Use a more specific name, add country or send lat/lng.
ER0422	400	Unknown sort value — allowed: distance, published_at, relevance.
ER0423	400	Unknown ranking preset — allowed: balanced, proximity, authority, fresh.
ER0424	400	A w.* weight is not a non-negative number.