How to find news near a coordinate or bounding box#

To find news near a point, send location.lat, location.lng and location.radius (in kilometers) to the APITube News API. The request below returns articles within 50 km of central Berlin:

curl "https://api.apitube.io/v1/news/everything?location.lat=52.52&location.lng=13.40&location.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. These geographic filters are part of the shared filter chain, so they work on the standard /v1/news/everything search — you are not limited to the dedicated /v1/news/local endpoint.

How does radius search work?#

Radius search needs three parameters together: location.lat (latitude, −90 to 90), location.lng (longitude, −180 to 180) and location.radius (the distance in kilometers). The radius is measured from the lat/lng center point, and location.radius accepts any positive number up to 20000 km. APITube matches every article whose attached coordinates fall inside that circle.

If you send a radius without both coordinates, the request fails with HTTP 400 and error ER0406 (location.lat and location.lng are required when using radius filters). An out-of-range latitude returns ER0407, an out-of-range longitude returns ER0408, and a radius that is zero, negative or above 20000 km returns ER0409.

How to run a ring search with a minimum radius#

To exclude the area immediately around your center point — a “ring” or “doughnut” search — add location.radius.min. With both bounds set, APITube returns articles whose distance is greater than location.radius.min and less than or equal to location.radius. This finds news between 20 km and 100 km of Berlin, skipping the inner city:

curl "https://api.apitube.io/v1/news/everything?location.lat=52.52&location.lng=13.40&location.radius.min=20&location.radius=100&api_key=YOUR_API_KEY"

location.radius.min also works on its own: sent without location.radius, it returns everything farther than that minimum distance. The minimum must be smaller than the maximum, otherwise the request returns ER0411. If you send neither location.radius nor location.radius.min while using coordinates, you get ER0412.

How to search inside a bounding box#

When you want a rectangle instead of a circle, use location.bbox with four comma-separated values in the order minLat,maxLat,minLng,maxLng. This example covers the New York City area:

curl "https://api.apitube.io/v1/news/everything?location.bbox=40.0,45.0,-74.0,-73.0&api_key=YOUR_API_KEY"

The bounding box must contain exactly four numbers, or the request returns ER0400. Latitudes outside −90 to 90 return ER0401 and longitudes outside −180 to 180 return ER0402. The minimum latitude must not exceed the maximum (ER0403), and the same rule applies to longitude (ER0404). A bounding box is the simplest way to constrain results to a city, metro region or country shape.

How to keep only articles that have coordinates#

Not every article carries geographic coordinates. To filter purely on coordinate presence — without a circle or rectangle — use has_location_geo. Send has_location_geo=1 to keep only geotagged articles, or has_location_geo=0 to keep only articles without coordinates:

curl "https://api.apitube.io/v1/news/everything?has_location_geo=1&api_key=YOUR_API_KEY"

Any value other than 0 or 1 returns ER0405. This is useful as a pre-filter before mapping results, since articles with no coordinates cannot be plotted.

What do geo coordinates look like in the response?#

Each article includes a locations_mentioned array describing the places detected in it. Every entry carries a name, a country code, the lat and lng coordinates, and a type:

{
    "locations_mentioned": [
        { "name": "Berlin", "country": "de", "lat": 52.52, "lng": 13.40, "type": "..." }
    ]
}

These are the same coordinates the radius and bounding-box filters match against, so you can map results directly without a separate geocoding step.

Which endpoints support geo filtering?#

The geographic filters belong to the shared filter chain, so location.lat/location.lng/location.radius, location.bbox and has_location_geo all work on /v1/news/everything and the other search and retrieval endpoints that run the chain. APITube also ships a purpose-built /v1/news/local endpoint for geo-targeted queries. You can combine geo filters with any other parameter — for example, recent English coverage near Berlin:

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

See How to filter news by language and How to filter news by date range to layer those filters on top, and the parameters reference for the full list.

Common Questions#

• What units is location.radius in?
• What is the maximum radius I can search?
• Why do I get error ER0406?
• Can I combine geo search with other filters?

What units is location.radius in?#

location.radius and location.radius.min are both in kilometers. A value of 50 means a 50 km radius from the location.lat/location.lng center. You do not pass meters or miles — APITube converts kilometers internally when measuring distance to each article’s coordinates.

What is the maximum radius I can search?#

location.radius accepts any positive number up to 20000 km. A radius of zero, a negative number or anything above 20000 km returns HTTP 400 with error ER0409. The same 20000 km ceiling applies to location.radius.min, which additionally must be smaller than location.radius.

Why do I get error ER0406?#

Error ER0406 means you sent a radius parameter without both coordinates. location.lat and location.lng are required whenever you use location.radius or location.radius.min. Add both coordinates, and make sure latitude is between −90 and 90 (ER0407) and longitude is between −180 and 180 (ER0408).

Can I combine geo search with other filters?#

Yes. Geographic filters run inside the standard filter chain, so you can mix location.lat/location.lng/location.radius or location.bbox with language, date range, source, sentiment and sorting in the same request. Filters combine with AND logic, so each one narrows the result set further. For source-level narrowing, see How to filter news by source.