How to browse the companies directory and view profiles#

Call GET /v1/companies to search a directory of organizations and brands, and GET /v1/companies/:id to open a single profile with Wikidata-enriched metadata, coverage statistics and recent articles. Filter the list by name or wikidata_id, page through it with page and per_page, then take the id from any result and request its profile or pass it back into a news search.

curl "https://api.apitube.io/v1/companies?name=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.

What is the companies directory?#

The companies directory is the set of organizations and brands APITube tracks as named entities. Unlike the people directory, which returns only persons, GET /v1/companies returns two entity types at once: organization and brand. So a single result’s type field is either organization (a company, agency or institution) or brand (a product brand or label) — both live in this directory.

It is the company-only view of the same entities you match in a search, so the id you read here is the exact value you pass back into a news query as entity.id. The list never mixes in people or locations. To pivot from a company straight to its news coverage, follow the links.articles URL on any record, which points to /v1/news/entity/:id.

How to search companies by name or Wikidata ID#

GET /v1/companies accepts four query parameters:

• name — filter by company name as a substring match (matches any record whose name contains the text).
• wikidata_id — filter by a Wikidata ID, given as either Q478214 or 478214.
• page — page number, starting at 1 (default 1).
• per_page — results per page, default 100, maximum 250.

curl "https://api.apitube.io/v1/companies?name=Coca-Cola&per_page=20&api_key=YOUR_API_KEY"

Spaces in a name should be URL-encoded. A per_page above 250 returns HTTP 400 with error ER0171 (“Limit is out of range.”), and a non-numeric page returns ER0172. The response wraps the records in a small envelope:

{
    "status": "ok",
    "limit": 20,
    "page": 1,
    "has_next_pages": true,
    "results": []
}

has_next_pages is true when the page came back completely full (its length equals per_page), which signals there may be more records on the next page. To walk the whole directory, keep incrementing page until has_next_pages is false.

What does a company record contain?#

Each entry in results (and the body of a single profile) shares the same shape:

{
    "id": 478214,
    "name": "Tesla, Inc.",
    "type": "organization",
    "links": {
        "self": "https://api.apitube.io/v1/companies/478214",
        "articles": "https://api.apitube.io/v1/news/entity/478214",
        "wikipedia": "https://en.wikipedia.org/wiki/Tesla,_Inc.",
        "wikidata": "https://www.wikidata.org/wiki/Q478214"
    },
    "profile": {}
}

id is the numeric entity ID, type is organization or brand, and links gives you ready-made URLs: self for the profile, articles for coverage, plus wikipedia and wikidata (each an empty string when APITube has no link for that company). profile holds the Wikidata-enriched metadata — fields such as headquarters and key_people — and varies by company; it may be null when no metadata is stored.

How to open a single company profile#

Take the id and request GET /v1/companies/:id. The profile returns the same company fields plus two extra blocks: a coverage summary and recent_articles.

curl "https://api.apitube.io/v1/companies/478214?api_key=YOUR_API_KEY"

If the ID does not exist, or it belongs to an entity that is not a company (not an organization or brand), the endpoint returns HTTP 404 with error ER0151 (“Company not found.”). recent_articles is a list of up to 5 of the company’s most recent articles as full article objects; on a free plan or a test key the article body is truncated to a preview.

What is in the coverage block?#

The coverage block aggregates how the company has appeared in the news. It includes:

• article_count — total matching articles.
• first_seen and last_seen — the earliest and latest article dates (YYYY-MM-DD, or null).
• sentiment — counts of positive, neutral and negative coverage.
• momentum — last_30_days vs previous_30_days plus a change_pct.
• timeline — monthly counts (up to 24 months).
• top_sources, top_topics, top_countries, top_languages and related_entities — each up to 10 entries with a count.

curl "https://api.apitube.io/v1/companies/478214?coverage=false&api_key=YOUR_API_KEY"

Add coverage=false to skip the whole block when you only need the profile and recent articles — the request is lighter and returns no coverage key. For the full list of accepted parameters and values, see the official parameters reference.

How are companies directory requests billed?#

Each successful directory call costs one request. The single-profile endpoint (/v1/companies/:id) always charges one request when it returns a profile. The list endpoint (/v1/companies) only charges when it returns at least one match, so a search that finds nobody does not cost a request. Both endpoints require a valid API key and reject missing or invalid keys with an authentication error.

Common Questions#

• How do I get the company ID to filter news?
• What’s the difference between an organization and a brand?
• Why did a profile request return ER0151?
• How do I skip the coverage statistics?

How do I get the company ID to filter news?#

Search GET /v1/companies?name= for the company, read the id from the matching record, and pass it back into a news search as entity.id. The directory and the search filter use the same entity IDs, so the value is interchangeable and exact. You can also filter by name with organization.name or brand.name, but those expect an exact name match, so the numeric entity.id is the safer bridge. See how to find news mentioning a person or company for the full filter syntax.

What’s the difference between an organization and a brand?#

The companies directory returns both entity types together. An organization is a company, agency or institution; a brand is a product brand or label. The type field on each record tells you which one you are looking at. Both are searchable through GET /v1/companies and both expose the same record shape, so you rarely need to care about the distinction — but if you later filter news by name instead of ID, organizations use organization.name and brands use brand.name.

Why did a profile request return ER0151?#

GET /v1/companies/:id returns HTTP 404 with ER0151 (“Company not found.”) when no entity has that ID, or when the ID belongs to an entity that is not a company — for example a person or a location. Confirm the ID by searching GET /v1/companies first, since that endpoint only ever lists organizations and brands.

How do I skip the coverage statistics?#

Append coverage=false to the profile request. The response then omits the coverage block entirely and still returns the company fields and recent_articles. Use it when you only need the company’s name, links and latest stories and do not want the aggregated counts and timeline. To turn the same ID into an ongoing feed, see how to monitor news about a company or brand.