How to filter news by country and location#

To return news from publishers in a specific country, add the source.country.code parameter with a two-letter country code, for example source.country.code=us. You can pass up to three codes separated by commas, and articles from a source in any of those countries are returned (OR logic).

curl "https://api.apitube.io/v1/news/everything?source.country.code=us&api_key=YOUR_API_KEY"

You can also send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. If you omit source.country.code, no country filter is applied and articles from sources in all countries are returned.

What does source.country.code filter on?#

source.country.code filters by the country the news source is registered in — the publisher’s country — not the country a story is about. A US publisher writing about France is matched by source.country.code=us, not fr. If you want articles about a place (where the event happened), use the location filters described below instead.

The code is a two-letter country code such as us, gb, de, jp or fr. The value is case-insensitive, so US and us behave the same way. The full set of accepted codes is in the list of countries in the documentation.

How to request a single country#

Pass one code to keep results to publishers in that country. This request returns articles from Japanese sources:

curl "https://api.apitube.io/v1/news/everything?source.country.code=jp&api_key=YOUR_API_KEY"

How to request multiple countries at once#

Separate codes with commas to match sources in any of the listed countries. This pulls articles from US, German and British publishers in a single call:

curl "https://api.apitube.io/v1/news/everything?source.country.code=us,de,gb&api_key=YOUR_API_KEY"

The maximum is three countries per request. If you list more than three, only the first three are used — the rest are silently dropped, so keep the list to three meaningful codes.

How to exclude a country with ignore.source.country.code#

To keep everything except sources in certain countries, use ignore.source.country.code. It follows the same rules — comma-separated, up to three codes. A common pattern is to drop both a country and its language at the same time:

curl "https://api.apitube.io/v1/news/everything?ignore.source.country.code=fr&ignore.language.code=fr&api_key=YOUR_API_KEY"

For language filtering on its own, see How to filter news by language.

How to filter by the location a story is about#

Country filtering matches the publisher, not the place in the news. To filter by geography — where an event happened — APITube has separate location parameters: location.lat, location.lng and location.radius (a radius in kilometres, up to 20000), location.bbox for a bounding box, and has_location_geo=1 to keep only articles that carry coordinates. These run on the regular search endpoints, the same way country filtering does. See How to find news near a coordinate or bounding box for the full syntax, or How to get local and geo-targeted news for the dedicated /v1/news/local endpoint that ranks results by distance from a point.

Which endpoints support country filtering?#

source.country.code is part of the shared filter chain, so it works on the main search and retrieval endpoints, including /v1/news/everything, /v1/news/top-headlines, /v1/news/story, /v1/news/category, /v1/news/topic, /v1/news/industry and /v1/news/entity. You can combine it with other filters — for example, negative coverage from US, British and German publishers in the health category:

curl "https://api.apitube.io/v1/news/everything?sentiment.overall.polarity=negative&source.country.code=us,gb,de&category.id=medtop:07000000&api_key=YOUR_API_KEY"

Common Questions#

• What country codes does APITube accept?
• How many countries can I request at once?
• What error do I get for an invalid country code?
• Does source.country.code filter by where the news happened?

What country codes does APITube accept?#

APITube accepts two-letter country codes such as us, gb, de, jp or fr. Each code must be exactly two characters. The full set is on the list of countries in the documentation.

How many countries can I request at once?#

Up to three per request, in both source.country.code and ignore.source.country.code. Codes beyond the third are ignored, so a request like source.country.code=us,gb,de,fr only applies us,gb,de.

What error do I get for an invalid country code?#

A code that is not exactly two characters returns HTTP 400 with error ER0246 (or ER0247 for the ignore variant). A well-formed two-letter code that does not exist in APITube returns HTTP 400 with ER0212 (ER0213 for ignore) and a message like source country code 'xx' not found.

Does source.country.code filter by where the news happened?#

No. source.country.code matches the country of the publishing source, not the location a story covers. To filter by the place an event happened, use the location parameters (location.lat/location.lng/location.radius, location.bbox) or the /v1/news/local endpoint.