How to browse the people directory and view profiles#

Call GET /v1/people to search a directory of known persons — public figures, politicians and executives — and GET /v1/people/: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.

curl "https://api.apitube.io/v1/people?name=Elon&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 people directory?#

The people directory is the set of persons APITube already tracks as named entities (entity type person). GET /v1/people returns those records so you can look someone up by name, confirm their entity id, and read the Wikidata profile APITube stores for them. It is the people-only view of the same entities you match in a search with person.name or entity.id, so the id you read here is the exact value you pass back into a news query.

The list never mixes in companies or locations: it only returns records of type person. To pivot from a person to their news coverage, follow the links.articles URL on any record, which points to /v1/news/entity/:id.

How to search people by name or Wikidata ID#

GET /v1/people accepts four query parameters:

• name — filter by a person’s name as a substring match.
• wikidata_id — filter by a Wikidata ID, given as either Q317521 or 317521.
• page — page number, starting at 1 (default 1).
• per_page — results per page, default 100, maximum 250.

curl "https://api.apitube.io/v1/people?name=Angela%20Merkel&per_page=20&api_key=YOUR_API_KEY"

Spaces in a name should be URL-encoded (Angela%20Merkel). A per_page above 250 returns HTTP 400 with error ER0171. 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 person record contain?#

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

{
    "id": 317521,
    "name": "Elon Musk",
    "type": "person",
    "links": {
        "self": "https://api.apitube.io/v1/people/317521",
        "articles": "https://api.apitube.io/v1/news/entity/317521",
        "wikipedia": "https://en.wikipedia.org/wiki/Elon_Musk",
        "wikidata": "https://www.wikidata.org/wiki/Q317521"
    },
    "profile": {}
}

id is the numeric entity ID, type is always person for this endpoint, 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 person). profile holds the Wikidata-enriched metadata, which varies by person and may be null.

How to open a single person profile#

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

curl "https://api.apitube.io/v1/people/317521?api_key=YOUR_API_KEY"

If the ID does not exist, or it belongs to an entity that is not a person, the endpoint returns HTTP 404 with error ER0151 (“Person not found.”). recent_articles is a list of up to 5 of the person’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 person 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/people/317521?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 people directory requests billed?#

Each successful directory call costs one request. The single-profile endpoint (/v1/people/:id) always charges one request when it returns a profile. The list endpoint (/v1/people) 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 entity ID to filter news?
• Can I look someone up by their Wikidata page?
• Why did a profile request return ER0151?
• How do I skip the coverage statistics?

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

Search GET /v1/people?name= for the person, 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. Alternatively, read the id straight from the entities array of any article, or use entity autocomplete for type-ahead lookups.

Can I look someone up by their Wikidata page?#

Yes. Pass wikidata_id to GET /v1/people, using either the Q-prefixed form (Q317521) or the bare number (317521). This is the most precise way to find one specific person, because names can be ambiguous while a Wikidata ID maps to exactly one entity.

Why did a profile request return ER0151?#

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

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 person fields and recent_articles. Use it when you only need the person’s name, links and latest stories and do not want the aggregated counts and timeline.