APITube Documentation

Appearance

Sign inGet started

Interactive Query Builder ​

The query builder turns any combination of News API filters into a ready request URL and a cURL command. Pick an endpoint, set the parameters you need, and copy the result — or paste your API key and run the request straight from this page.

Presets

Text & language

Any title or query search is capped to a 31-day published_at window (ER0110).

Title

Boolean query

Language

How to use the query builder ​

  1. Pick an endpoint. Endpoints that carry a value in the path — Story, Category, Topic, Industry, Entity — show an extra field for it next to the selector. Until it is filled, the URL keeps the {placeholder} visible and Run stays disabled.
  2. Set parameters. The list on the left groups every filter by subject; the filter box above searches all of them at once, by label or by API name, so typing sentiment or source.rank jumps straight to the right fields.
  3. Check the active row. Each parameter you set becomes a chip under the header, showing the real API name and value. Click a chip to remove that one parameter, or Clear all to start over.
  4. Copy or run. Copy URL and Copy cURL put the request on your clipboard. Run opens it in a new tab using the key you pasted; that key is kept in your browser's local storage and is never sent anywhere except api.apitube.io.

Four presets — breaking news, big-tech coverage, finance from ranked sources, trending entities — fill a working query in one click if you would rather start from something that already returns results.

What the generated URL contains ​

Every field maps to one query parameter in dotted notation, and the builder prints that name next to the label: Min score under Sentiment is sentiment.overall.score.min, Min rank (OPR) under Sources is source.rank.opr.min. Booleans are sent as 1. Fields you leave empty are omitted, so the URL only ever carries what you actually set.

Parameters that the chosen endpoint does not read are left out of the request rather than sent and ignored. The Trends group appears only for /v1/news/trends and Article lookup only for /v1/news/article, since field and id are read only there. In the other direction, /v1/news/trends has its own pagination and sorting and returns aggregates rather than articles, so on that endpoint the builder hides sort.by, sort.order, page, fl, export and the faceting and highlighting groups.

Parameter syntax worth knowing ​

Multi-value filters keep only the first three values, silently. source.domain, language.code, category.id, topic.id, industry.id, entity.id, source.id, source.country.code, the *.name filters and their ignore.* counterparts all cap at 3 — source.domain=a.com,b.com,c.com,d.com searches the first three and drops the fourth without an error. id on the article endpoint takes up to 100.

Title searches are limited to a 31-day window. title, title_pattern, title_starts_with, title_ends_with and query may not span more than 31 days of published_at on any plan. A wider explicit range returns 400 ER0110; no range at all searches the last 31 days and reports ER0366 in meta.warnings.

title supports phrases with proximity. "climate change"~2 matches the two words within two positions of each other. title_pattern is a plain substring match, not a regular expression — ^, ., * and | are treated as literal characters.

The query field is a boolean language. It accepts AND / OR / NOT, parentheses, field:value predicates, quoted phrases, ranges [a TO b] and entity blocks, and combines with the flat filters through AND. Parse errors come back as ER0701–ER0712. See advanced query syntax for the full grammar.

Dates take YYYY-MM-DD or ISO 8601. 2024-01-15 and 2024-01-15T10:30:00Z are both accepted for published_at, published_at.start and published_at.end.

per_page is capped by plan. The parameter accepts 1–250, but Free is limited to 10, Starter to 50 and Basic to 200; asking for more returns 400 ER0171. The Free plan also cannot go past page 5 (ER0173). On /v1/news/trends the ceiling is 100.

Source rank is a whole number from 0 to 10. source.rank.opr.min and source.rank.opr.max are parsed as integers, so source.rank.opr.min=0.7 becomes 0 and quietly stops filtering anything. The Premium only flag is exactly source.rank.opr.min=6; Verified only is source.rank.opr.min=5 plus is_duplicate=0.

Faceting and highlighting need their flag. Setting facet.field or hl.fl alone returns 200 with no facets or highlighting block and no error — facet=1, facet.range=1 and hl=1 switch the features on. The builder's checkboxes set them.

Running the generated query in code ​

Copy the URL from the builder and drop it into your client of choice.

javascript
const url =
  'https://api.apitube.io/v1/news/everything?title=AI&sentiment.overall.polarity=positive&api_key=YOUR_API_KEY';

const response = await fetch(url);
const data = await response.json();

console.log(data.results.length);
python
import requests

response = requests.get(
    "https://api.apitube.io/v1/news/everything",
    params={
        "title": "AI",
        "sentiment.overall.polarity": "positive",
        "api_key": "YOUR_API_KEY",
    },
)

data = response.json()
bash
curl "https://api.apitube.io/v1/news/everything?title=AI&sentiment.overall.polarity=positive&api_key=YOUR_API_KEY"

Keep the key out of client-side code in production — call the API from your backend and pass it in the X-API-Key header instead of the query string. See Authentication.