Entity directory

Enumerate raw entity names found in indexed documents, ordered by event mentions, with observed metadata for each name.

GET/api/v2.0-preview/entities

Authorizations

Bearer

Authorizationstringrequiredheader

Required Bearer API key. Programmatic access to the World API needs a key; browsing nosible.world in a browser does not.

Example: Bearer nos_sk_...

Parameters

query & path

typestringquery

Optional NER type such as ORG, PERSON, or ANY.

Example: ORG

pageintegerquery

1-based page number; each page contains up to 50 entities.

Example: 1

How to use this endpoint

guidance

In V2.0-preview, the directory lists Atlas's normalized entities: each canonical entity once, with its spellings and short names folded in. Use the Entity Directory once per index build, then cache the pages locally. It enumerates raw entity names in mentions-desc order; each item carries the same observed metadata as Entity Profile.

Response body

application/json

These are the fields you can build against. Nested names use dot notation; optional sections are called out in their descriptions.

schemastring

Response schema name.

entity_typestring | null

The type filter, null for every type.

coveragestring

What the directory enumerates: indexed_entity_vocabulary.

orderstring

mentions_desc: the most-mentioned entities first.

pageinteger

1-based page number.

has_moreboolean

Whether another page exists.

entitiesobject[]

Up to 50 Atlas canonical entities, each once, with the counts of all its names folded in.

entities[].kindstring

entity.

entities[].typestring

NER type of the entity, such as ORG or PERSON.

entities[].namestring

The entity's canonical Atlas name.

entities[].normalizedstring

Lower-cased lookup form of the name.

entities[].total_eventsinteger

Indexed events that mention the entity under any of its names.

entities[].first_datedate

Date of the earliest indexed event.

entities[].last_datedate

Date of the latest indexed event.

entities[].events_urlstring

The entity's event timeline on this API version.

entities[].metadataobject

What the indexed events of this entity look like: events_by_year, facets (the top 20 values of each categorical event field, such as language, country, sentiment and every taxonomy level) and numeric (count, missing, sum, min, max and mean of lat, lng, total_coverage, total_netlocs, coverage_concentration_index and materiality_score).

entities[].metadata.events_by_yearobject[]

Events per year: {year, count}.

entities[].metadata.facetsobject

Top values of each categorical field: {field: [{value, count}]}.

entities[].metadata.numericobject

Summary statistics of each numeric field.

entities[].filterobject

Ready-made World Search filter for the entity.

as_ofobject

index_build and archive_cutoff: the index that answered.

took_msinteger

Server time in milliseconds.

Responses and errors

HTTP

200Request succeeded. The response body is shown in the panel on the right.

400invalid_request — The date, filter, cursor, identifier, or request combination is invalid.

401api_key_required — No API key was sent. Send it as Authorization: Bearer <key> or the api-key header.

401invalid_api_key — The API key is invalid or has been revoked.

403access_denied — The requested archive date is outside the caller's World tier.

404not_found — The requested date, entity, ticker, or event does not exist in the accessible index.

410cursor_expired — The cursor was minted against a replaced index build. Restart pagination from the first page.

429rate_limited — The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.

501backend_not_configured — The World backend is not configured for this deployment.

503api_key_auth_unavailable — API key authentication is temporarily unavailable; retry shortly.

502backend_error — The BFF could not obtain a valid response from the World backend.

504backend_timeout — The World backend or an upstream data source timed out.

400invalid_entity_type — The type filter is not one of the indexed NER types or ANY.

503inverted_index_unavailable — The entity directory index is not loaded; retry after the next index publish.