How to autocomplete filter values with the Suggest API#

APITube has five autocomplete endpoints — /v1/suggest/sources, /v1/suggest/categories, /v1/suggest/topics, /v1/suggest/industries and /v1/suggest/entities — and they all work the same way: send a prefix string, get back a JSON array of matching options, each carrying the exact id the corresponding search filter expects. They are the practical answer to “how do I find a valid category.id (or topic.id, industry.id, source) without scrolling a thousand-row reference table”.

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

The entity flavour has its own walkthrough — entity autocomplete in search inputs — so this article covers the other four, which complete the reference taxonomies rather than people and companies.

How does the prefix parameter work?#

Every suggest endpoint takes exactly one required query parameter, prefix, plus your API key. Despite the name, the match is a case-insensitive contains, not a starts-with: prefix=oil matches “crude oil” anywhere in the name. Sources are the one exception with a wider net — the prefix is matched against both the source name and its domain, so prefix=bbc finds the source whether the user typed the brand or the hostname.

Each call returns up to 100 matches, ordered by internal ID, and there are no paging or limit parameters — if the list feels too long, type a longer prefix. Suggest calls are made on almost every keystroke, so two behaviours matter: they do not spend your request quota (suggest lookups are free), and you should still debounce the input in your UI so a fast typist fires one request per pause, not one per character.

What does each endpoint return?#

The response is a bare JSON array (there is no results wrapper, unlike the news endpoints). The fields per item differ slightly by endpoint:

• /v1/suggest/sources — id, name, domain, type, bias (left, center or right when known, otherwise null) and a links.self search URL. Pass the domain value to the source.domain filter.
• /v1/suggest/categories — id (an IPTC code like medtop:11000000), name, taxonomy and links.self. The id goes into category.id.
• /v1/suggest/topics — id (a slug such as market_news.commodities.crude_oil), name and links.self. The id goes into topic.id.
• /v1/suggest/industries — id (a plain number), name and links.self. The id goes into industry.id.

Each of category.id, topic.id and industry.id accepts up to 3 comma-separated values in a search, and none of them accepts a name — which is exactly why the suggest endpoints exist. The full parameter syntax lives in the official parameters reference.

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

What errors should a typeahead handle?#

Two request-level failures cover almost everything:

• Empty or missing prefix → HTTP 400 with error code ER0346 (“Prefix in query required”). Do not fire the call until the input has at least one character.
• Missing API key → HTTP 401 with error code ER0201. Suggest requires authentication like every other endpoint, so send the key as the X-API-Key header or the api_key query parameter.

One more edge to know about: if your API key is restricted to specific endpoint scopes, the key needs the suggest scope, otherwise the call returns 403 with ER0603 — see how to limit a key to specific endpoints.

Common Questions#

• Do suggest requests cost anything?
• Can I get more than 100 suggestions?
• Where do I browse the full lists instead of autocompleting?

Do suggest requests cost anything?#

No. Suggest lookups are not billed against your plan — no request is deducted, whatever your plan is. Your key still authenticates the call, but wiring autocomplete into a search form will not eat the quota you want to spend on actual news requests.

Can I get more than 100 suggestions?#

No — 100 per call is a hard cap and there is no page or limit parameter. In practice a dropdown never needs that many options; a longer, more specific prefix is the intended way to narrow the list. If you need the complete taxonomy rather than matches, use the reference lists in the documentation instead.

Where do I browse the full lists instead of autocompleting?#

The documentation publishes every valid value: all categories, all topics and all industries. Suggest is for interactive inputs; the static lists are better when you are hard-coding a known set of IDs into your integration.