How to use entity autocomplete in search inputs#

Call GET /v1/suggest/entities with a prefix to power an autocomplete (typeahead) box: as the user types, the endpoint returns the entities APITube already tracks whose name matches, each with a stable numeric id you can drop straight into the entity.id search filter. This is the reliable way to turn free text like “tesl” into the exact entity a user means before you run a news search.

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

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. Both forms are accepted on every request.

What does /v1/suggest/entities return?#

The endpoint returns a JSON array of matching entities (not a wrapped object). Each item has the same shape:

[
    {
        "id": 5012,
        "name": "SpaceX",
        "type": "organization",
        "links": {
            "self": "https://api.apitube.io/v1/news/entity/...",
            "wikipedia": "https://en.wikipedia.org/wiki/SpaceX",
            "wikidata": "https://www.wikidata.org/wiki/Q193701"
        },
        "metadata": {}
    }
]

• id — the stable numeric entity ID. This is the value you pass to entity.id in a search (not the number inside links.self, which points to that entity’s own news endpoint).
• name — the canonical entity name.
• type — one of person, location, organization, brand, product, natural-disaster, disease, event, sport or unknown.
• links — wikipedia and wikidata URLs when known (empty string when not), plus a self link.
• metadata — extra structured fields about the entity when available.

How does prefix matching work?#

Despite the name, prefix matches any part of the entity name and is case-insensitive — prefix=tesla matches “Tesla” wherever the text appears in the name, not only names that start with it. Results are ordered by internal ID (ascending) and capped at 100 entities per call, which is plenty for a dropdown. There is no separate “minimum length” rule, but a longer prefix returns fewer, sharper matches, so trigger the call after the user has typed 2–3 characters to keep the list tight.

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

How to turn a suggestion into a news search#

The whole point of autocomplete is the hand-off to a real search. Take the id from the suggestion the user picked and pass it to entity.id on /v1/news/everything:

curl "https://api.apitube.io/v1/news/everything?entity.id=5012&api_key=YOUR_API_KEY"

entity.id accepts up to three IDs, comma-separated, with OR logic (an article matches if it mentions any of them), and each value must be an integer of 1 to 30 characters. Because it is a fixed identifier rather than a name, entity.id never fails on an unknown value — a valid-looking ID that matches nothing simply returns no articles. For everything you can do once you have the ID, see How to find news mentioning a person or company.

What errors can the endpoint return?#

There are two request-level errors to handle in your typeahead:

• Missing prefix → HTTP 400 with error ER0346. Skip the call entirely until the input has at least one character.
• Missing API key → HTTP 401 with error ER0201. Send the key on every suggest call, exactly like a search.

Because suggest is hit on nearly every keystroke, debounce the input (wait ~200–300 ms after typing stops) so you fire one request per pause instead of one per character.

APITube exposes the same autocomplete pattern for other facets too — /v1/suggest/sources, /v1/suggest/categories, /v1/suggest/topics and /v1/suggest/industries — each taking a prefix and returning matching options for that filter. For the full list of search parameters these IDs feed into, see the official parameters reference.

Common Questions#

• Does prefix have to be the start of the name?
• How many suggestions are returned?
• Which ID do I pass to entity.id?
• Can I autocomplete only people or only companies?

Does prefix have to be the start of the name?#

No. prefix is matched case-insensitively against the whole entity name, so it behaves like a “contains” search — prefix=york will match “New York”. Use the most distinctive part of the name to keep the list short, and let the user pick the exact entity from the returned name and type.

How many suggestions are returned?#

Up to 100 matching entities per call, ordered by internal ID. That is more than a dropdown needs, so you can safely render just the first handful and let the user refine the prefix to narrow the rest.

Which ID do I pass to entity.id?#

The top-level id field of each suggestion. That value is the stable entity ID, and it is exactly what entity.id expects in a /v1/news/everything request. Do not use the number embedded in links.self — that link is the entity’s own news endpoint and uses a different internal reference.

Can I autocomplete only people or only companies?#

The endpoint returns all matching entity types in one list, but every item carries a type field (person, organization, brand, location and so on). Filter the results client-side by type if your input is meant for one kind of entity, then pass the chosen id to entity.id, which works for any type. To browse a curated list of one type instead of a typeahead, see the people directory.