How to get local and geo-targeted news#

To get news around a place, call the /v1/news/local endpoint with a center point — either lat and lng coordinates or a place name — and a radius in kilometers. Unlike a plain geo filter, this endpoint sorts results by distance and adds distance_km and nearest_location to every article. This request returns news within 50 km of central Berlin, nearest first:

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

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. The radius defaults to 50 km when omitted and accepts any positive number up to 20000 km; a zero, negative or out-of-range value returns HTTP 400 with error ER0409.

How is /v1/news/local different from the geo filter on the main search?#

The /v1/news/local endpoint 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. They overlap on “find articles near a point”, but /v1/news/local adds things the filter does not: it sorts by proximity, returns a per-article distance_km and nearest_location, accepts a place name, and can attach a local intelligence dashboard. If you only need a geographic constraint on a normal search, use the filter instead — see How to find news near a coordinate or bounding box.

/v1/news/local supports the same filters as /v1/news/everything, so you can layer language, date, sentiment, source and other parameters on top of the geo search in the same request.

How to search local news by place name#

Instead of coordinates, pass a place name and APITube geocodes it to a center point for you:

curl "https://api.apitube.io/v1/news/local?place=Berlin&radius=30&api_key=YOUR_API_KEY"

Place names are resolved against APITube’s entity graph and matched on a word boundary, so Paris will not accidentally match Parish. Ambiguous names resolve to the best candidate — add a country parameter (an ISO 3166-1 alpha-2 code such as de or fr) to disambiguate, or pass explicit lat/lng, which always take precedence over place. When a place is used, the response echoes the resolved name and entity id in its query block. If the name cannot be geocoded, the request returns ER0421.

How to sort local news by distance, date or relevance#

The sort parameter accepts three values and defaults to distance (nearest first):

• distance — closest articles first.
• published_at — newest first.
• relevance — a composite of proximity, source authority, recency and importance; this adds a relevance_score to every article.

When you sort by relevance, the ranking parameter picks a weighting preset: balanced (default), proximity (closer wins), authority (bigger sources win) or fresh (recency wins). This returns the most relevant Berlin coverage, favoring authoritative sources:

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

The effective weights are returned in ranking_weights, and you can override any of them with the w.distance, w.opr, w.recency and w.important parameters.

What does each local result include?#

Every article in results is the standard article object enriched with geo fields:

• distance_km — distance from your center to the nearest matched location in the article.
• nearest_location — an object with entity_id, name, lat, lng and country for that closest place.
• relevance_score — present only when sort=relevance.

The response also carries a query block (the lat, lng, radius_km and sort it used) and total, the exact number of matching articles inside the radius. Pagination uses page and per_page, which defaults to 100 and is capped at 250; a higher per_page returns ER0171.

How to add a local insights dashboard#

Pass the insights parameter — a comma-separated list — to compute aggregate intelligence over the radius. Allowed blocks are: mood, hotspots, events, entities, bias, sources, timeline, top_categories, top_topics, breaking, velocity and movers. This returns Berlin articles plus local mood, density hotspots and a breaking-news count:

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"

The results appear under a local_insights object alongside the article list. An unknown insight value returns ER0420. The movers block surfaces entities and topics accelerating against their 14-day baseline — useful the same way the trends endpoint is, but scoped to your radius.

Common Questions#

• How much does a /v1/news/local request cost?
• What is the maximum search radius?
• Why do I get error ER0421?
• Can I combine local news with other filters?

How much does a /v1/news/local request cost?#

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; a request with insights=mood,hotspots,breaking costs 4 points (1 + 3). Skip the insights parameter when you only need the ranked articles.

What is the maximum search radius?#

The radius is measured in kilometers, defaults to 50 when omitted, and accepts any positive number up to 20000 km. A radius of zero, a negative value or anything above 20000 km returns HTTP 400 with error ER0409. You must also supply a center: send lat and lng together (or a place), otherwise the request returns ER0406. An out-of-range latitude returns ER0407 and an out-of-range longitude returns ER0408.

Why do I get error ER0421?#

Error ER0421 means APITube could not geocode the place name you sent. Try a more specific name, add a country code to disambiguate it, or pass explicit lat/lng coordinates instead of a place name. Coordinates skip geocoding entirely and always take precedence over place.

Can I combine local news with other filters?#

Yes. /v1/news/local runs the same filter chain as the main search, so you can mix the geo center with language, date range, sentiment, source and sorting in one request. This returns recent English-language news near Berlin:

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

For the full list of filters you can layer on top, see the parameters reference.