Find entities

Find the canonical entity or security identifier before retrieving its event timeline.

GET/api/v2.0/resolve

Authorizations

Bearer

Authorizationstringheader

Required Bearer API key for programmatic World access.

Example: Bearer nos_sk_...

Parameters

query & path

viewenumquery

The records returned: lite (the default), each entity's or ticker's identity, event count, date range and events per year, enough to choose one and fetch its events; or full, which adds the facets and numeric statistics of its events and a ticker's complete reference data. Any other value is a 422 validation_error.

Example: lite

qstringrequiredquery

Entity, company, ticker, or identifier to resolve.

Example: nvidia

typesstringquery

Comma-separated entity types or TICKER.

Example: ORG,TICKER

limitintegerquery

Maximum number of candidates. Defaults to 10, maximum 50.

Example: 3

min_eventsintegerquery

Only candidates with at least this many events.

Example: 10

How to use this endpoint

guidance

In V2.0, Find entities searches Atlas's normalized entities: a spelling or short name such as "NVIDIA" or "Trump" resolves to the canonical entity, and the names it returns are the ones the Atlas API accepts. Results are lite by default: each candidate's identity, event count, date range, how it matched, a ready filter and its events_url, and for a ticker its issuer's reference data and Atlas entity. That is what an autocomplete or a lookup needs; send view=full for each candidate's profile, events per year, facets and numeric statistics, as Entity profile and Ticker profile return them. An exact match is marked match: "exact" and is never followed by fuzzy candidates; with no match at all, results is empty (count 0).

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.

viewstring

The view of the records: lite (the default) or full.

qstring

The query.

countinteger

Candidates found.

resultsobject[]

Entity and ticker candidates, best first. Entities are Atlas's canonical entities, so a spelling or short name resolves to the canonical name ("Trump" to "Donald Trump"); tickers carry their exchange suffix (NVDA.US).

results[].kindstring

entity or ticker.

results[].typestring

NER type of an entity, or TICKER.

results[].namestring

The entity's canonical Atlas name, or the issuer's name for a ticker.

results[].tickerstring

Symbol with its exchange suffix (tickers only), such as NVDA.US.

results[].identifiersobject

isin, figi, lei and wiki_qid of the security (tickers only).

results[].matchstring

How the query matched: exact (the query is the candidate's name or one of its names, or a ticker's symbol, ISIN, FIGI, LEI or Wikidata QID), prefix (one of its names starts with the query) or fuzzy (a similar spelling). Exact candidates come first, then prefix, then fuzzy. Fuzzy candidates are returned only when nothing matches exactly, and only when they share at least a quarter of their letter triples with the query (trigram similarity 0.25), so an identifier or an exact name is not padded with unrelated candidates.

results[].scorenumber

Ranking score; higher is better.

results[].total_eventsinteger

Indexed events of the candidate.

results[].first_datedate

Date of its earliest indexed event.

results[].last_datedate

Date of its latest indexed event.

results[].events_urlstring

The candidate's event timeline on this API version.

results[].filterobject

Ready-made World Search filter for the candidate.

results[].profileobject

view=full only. The same identity fields as the candidate's profile endpoint.

results[].metadataobject

view=full only. What the indexed events of this entity look like: events_by_year, and with view=full 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).

results[].metadata.events_by_yearobject[]

view=full only. Events per year: {year, count}, every year of the archive.

results[].metadata.facetsobject

view=full only. Top values of each categorical field: {field: [{value, count}]}.

results[].metadata.numericobject

view=full only. Summary statistics of each numeric field.

results[].referenceobject

Tickers only. Reference data for the issuer: its Atlas entity, name, identifiers, listing and country; with view=full also its website, every identifier and its classification. Each part is present only when it is known.

results[].reference.entityobject

The issuer's Atlas entity, {type, name}: the entity the Atlas API and the entity endpoints use. Absent when the ticker is not mapped to an Atlas entity.

results[].reference.entity.typestring

NER type of the issuer's entity: ORG.

results[].reference.entity.namestring

Canonical Atlas name of the issuer, such as Nvidia.

results[].reference.company_namestring

Issuer name.

results[].reference.websitesobject

view=full only. Issuer websites: website.

results[].reference.websites.websitestring

view=full only. Main website of the issuer.

results[].reference.identifiersobject

Identifiers of the issuer and security: isin, figi, lei and wiki_qid; view=full adds the others known.

results[].reference.identifiers.isinstring

ISIN of the security.

results[].reference.identifiers.leistring

LEI of the issuer.

results[].reference.identifiers.figistring

FIGI of the security.

results[].reference.identifiers.wiki_qidstring

Wikidata identifier of the issuer.

results[].reference.identifiers.companyv5_idstring

view=full only. NOSIBLE company identifier of the issuer.

results[].reference.marketobject

Listing: exchange and mic.

results[].reference.market.exchangestring

Exchange of the listing.

results[].reference.market.micstring

ISO 10383 market identifier code of the exchange.

results[].reference.geographyobject

Issuer country: country_iso.

results[].reference.geography.country_isostring

ISO 3166-1 alpha-2 country of the issuer.

results[].reference.classificationobject

view=full only. GICS classification of the issuer: sector and industry.

results[].reference.classification.sectorstring

view=full only. GICS sector.

results[].reference.classification.industrystring

view=full only. GICS industry.

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_json — The request body is not JSON. Every error body, 401 included, is {error, message, status}.

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.

422validation_error — The request is well formed but the API cannot decode or validate it: an unknown body field or query parameter, a missing required parameter, a value of the wrong type, an empty and, or or not, a date that is not a calendar date (in the path, the query or the body), an unknown enum value or a reversed range. The message names the parameter and what is wrong.

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.

503api_key_metering_unavailable — API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.

502backend_error — The World backend could not be reached or did not return a valid response; retry shortly.

504backend_timeout — The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.