How to filter news by category#

To return only articles that belong to a subject category, add the category.id parameter with an IPTC category code, for example category.id=medtop:15000000 for Sport. You can pass up to three codes separated by commas, and an article is returned if it matches any of them (OR logic). Every code must be a category APITube already tracks.

curl "https://api.apitube.io/v1/news/everything?category.id=medtop:15000000&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 category.id, no category filter is applied and articles from all categories are returned.

What is the category.id parameter?#

category.id takes one or more category codes from the IPTC taxonomy. IPTC codes look like medtop:15000000 (Sport) — a medtop: prefix followed by the numeric topic ID. The category filter is part of the shared filter chain, so it works on /v1/news/everything and on the other search endpoints described below.

Each code you pass is checked against the categories APITube tracks. If a code does not exist, the request fails with HTTP 400 and error ER0206 and a message like category with ID 'medtop:99999999' not found — the whole request stops, so one unknown code blocks the entire call. Confirm a code exists first with the suggest endpoint (see below).

How to filter by one or more categories#

Pass a single code to read one category, or a comma-separated list to combine several. This request pulls articles from two categories in one call, returning anything that matches either:

curl "https://api.apitube.io/v1/news/everything?category.id=medtop:15000000,medtop:04000000&api_key=YOUR_API_KEY"

The maximum is three codes per request; extra codes beyond the third are dropped. Because category.id runs in the shared filter chain, it also combines with other filters and with sorting:

curl "https://api.apitube.io/v1/news/everything?category.id=medtop:15000000&language.code=en&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

That request returns the newest English articles in the Sport category. To restrict the time window too, add published_at.start and published_at.end.

How to find the right category ID#

Use the /v1/suggest/categories endpoint to look up a category by name before you filter. Pass a prefix and it returns matching categories, each with an id, name, taxonomy and a ready-made links.self URL:

curl "https://api.apitube.io/v1/suggest/categories?prefix=sport&api_key=YOUR_API_KEY"

The id it returns is the exact value to drop into category.id — no conversion needed. The prefix parameter is required; omitting it returns HTTP 400 with error ER0346, and a missing API key returns ER0200. For the complete reference of IPTC categories, see the list of supported categories in the official docs.

How to exclude a category#

To return everything except a category, use ignore.category.id. It follows the same rules — comma-separated, up to three codes. This keeps every category but drops Sport:

curl "https://api.apitube.io/v1/news/everything?ignore.category.id=medtop:15000000&api_key=YOUR_API_KEY"

As with the positive filter, an unknown code in ignore.category.id stops the request with HTTP 400 and error ER0207, so the excluded codes must also be tracked categories. You can combine category.id and ignore.category.id in the same request to include one set of categories while removing another.

Which endpoints support category filtering?#

The category.id and ignore.category.id parameters work on /v1/news/everything, /v1/news/top-headlines, /v1/news/story, /v1/news/category, /v1/news/topic, /v1/news/industry and /v1/news/entity. There is also a dedicated category endpoint, /v1/news/category/{taxonomy}/{id}, that returns a single category’s articles. The simplest way to get a correct URL for it is the links.self field returned by /v1/suggest/categories. An unknown category on that endpoint returns HTTP 404 with error ER0241.

What does the category data look like in the response?#

Every article in the response carries a categories array so you can see how it was classified:

{
    "categories": [
        {
            "id": 314,
            "name": "Sport",
            "taxonomy": "iptc_mediatopics",
            "links": {
                "self": "https://api.apitube.io/v1/news/category/iptc_mediatopics/medtop:15000000"
            }
        }
    ]
}

Each entry also includes a score field reflecting how strongly the article maps to that category. The links.self URL fetches all articles in the same category. To discover the code you pass to category.id, use /v1/suggest/categories rather than the id in this object. If you only need a tally per category instead of the articles themselves, see How to count news articles without downloading them.

Common Questions#

• How many categories can I filter by at once?
• What category codes does category.id accept?
• What error do I get for an unknown category?
• Can I include and exclude categories in the same request?

How many categories can I filter by at once?#

Up to three per parameter. category.id and ignore.category.id each accept a comma-separated list, and only the first three codes are applied — extra codes beyond the third are ignored. Multiple codes use OR logic, so an article is returned if it matches any one of them.

What category codes does category.id accept?#

category.id accepts IPTC category codes such as medtop:15000000. Each code is matched against the categories APITube tracks. The reliable way to get a valid code is /v1/suggest/categories?prefix=NAME, whose id field is exactly what category.id expects.

What error do I get for an unknown category?#

A code APITube does not track returns HTTP 400 with error ER0206 (category with ID '…' not found) for category.id, or ER0207 for ignore.category.id. The request stops on the first unknown code, so validate each code with /v1/suggest/categories before filtering.

Can I include and exclude categories in the same request?#

Yes. category.id and ignore.category.id can be combined with each other and with other filters such as language.code, published_at.start or source.domain. The positive filter limits results to the listed categories, and the ignore filter removes any you do not want from whatever remains.