How to filter news by source or domain#

To return articles only from specific publishers, add the source.domain parameter with one or more website domains, for example source.domain=theguardian.com. You can pass up to three domains separated by commas, and articles from any of those sources are returned (OR logic). Each domain must match a publisher APITube already tracks.

curl "https://api.apitube.io/v1/news/everything?source.domain=theguardian.com&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.domain, no source filter is applied and articles from all publishers are returned.

What is the source.domain parameter?#

source.domain takes one or more publisher domains, like nytimes.com or bbc.co.uk. The value is case-insensitive, so NYTimes.com and nytimes.com behave the same. Each domain may be 1 to 255 characters long; anything outside that range returns HTTP 400 with error ER0057.

Every domain you pass is matched against the publishers APITube tracks. If a domain is not in the directory, the request fails with HTTP 400 and error ER0214 and a message like source domain name 'example.com' not found — the whole request stops, so one unknown domain blocks the entire call. That is why it pays to confirm a domain exists first (see below).

How to filter by one or more domains#

Pass a single domain to read just that publisher, or a comma-separated list to combine several. This request pulls articles from three newspapers in one call:

curl "https://api.apitube.io/v1/news/everything?source.domain=theguardian.com,foxnews.com,nytimes.com&api_key=YOUR_API_KEY"

The maximum is three domains per request. If you list more than three, only the first three are used and the rest are silently dropped, so keep the list to three meaningful domains. Source filtering is part of the shared filter chain, so it also combines with other filters and with sorting:

curl "https://api.apitube.io/v1/news/everything?source.domain=theguardian.com,nytimes.com&language.code=en&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

How to filter by source ID instead of domain#

Every publisher also has a numeric source.id. Filtering by ID avoids domain typos and survives a publisher changing its domain. Pass up to three IDs, comma-separated:

curl "https://api.apitube.io/v1/news/everything?source.id=12345,67890&api_key=YOUR_API_KEY"

Each ID must be a non-negative integer of 1 to 20 characters. A non-numeric value returns ER0050, a negative value returns ER0051, and an out-of-range length returns ER0052 — all HTTP 400.

How to exclude specific sources#

To return everything except certain publishers, use ignore.source.domain or ignore.source.id. Both follow the same rules — comma-separated, up to three values. This excludes two tabloids while keeping all other sources:

curl "https://api.apitube.io/v1/news/everything?ignore.source.domain=foxnews.com,nypost.com&api_key=YOUR_API_KEY"

As with the positive filters, an unknown domain in ignore.source.domain returns ER0215, so the excluded domains must also be tracked publishers.

How to find a source’s domain or ID#

Use the /v1/suggest/sources endpoint to look up a publisher before you filter. Pass a prefix and it returns matching sources, each with its id, name, domain, type and bias, plus a ready-made links.self URL that filters on that source:

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

The prefix parameter is required; omitting it returns HTTP 400 with error ER0346. Take the domain or id from a result and drop it straight into source.domain or source.id. You can also filter by a publisher’s country with source.country.code (a two-letter code, up to three) — see How to filter news by country and location.

What does the source object in the response contain?#

Every article in the response carries a source object so you can confirm where it came from:

{
    "source": {
        "id": 12345,
        "domain": "theguardian.com",
        "home_page_url": "https://www.theguardian.com",
        "type": "news",
        "rankings": { "opr": 7 },
        "location": { "country_name": "United Kingdom", "country_code": "gb" }
    }
}

The id and domain here are exactly the values you pass back into source.id and source.domain for follow-up requests. To narrow results to a single language at the same time, combine source filtering with How to filter news by language.

Common Questions#

• How many sources can I filter by at once?
• Should I use source.domain or source.id?
• What error do I get for an unknown domain?
• Can I include and exclude sources in the same request?

How many sources can I filter by at once?#

Up to three per parameter. source.domain, source.id, ignore.source.domain and ignore.source.id each accept a comma-separated list, and only the first three values are applied — extra values beyond the third are silently ignored.

Should I use source.domain or source.id?#

Both target the same publishers. source.domain is easier to read and write because you use the website address directly. source.id is more stable: it is a fixed numeric identifier that does not change even if a publisher moves to a new domain. Use /v1/suggest/sources to translate between the two.

What error do I get for an unknown domain?#

A domain that APITube does not track returns HTTP 400 with error ER0214 (source domain name '…' not found) for source.domain, or ER0215 for ignore.source.domain. A domain shorter than 1 or longer than 255 characters returns ER0057 (ER0059 for the ignore variant). Because the request stops on the first bad domain, validate each domain with /v1/suggest/sources before filtering.

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

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