Normalize entity

Normalize an entity name: the entity it stands for and every name that belongs to it.

GET/api/v2.0-preview/atlas/entities/normalize

Authorizations

Bearer

Authorizationstringrequiredheader

Required Bearer API key: your NOSIBLE API key from the API Dashboard.

Example: Bearer nos_sk_...

Parameters

query & path

namestringrequiredquery

The name to normalize. Punctuation, spacing, case and Latin accents do not matter: "coca cola", "Coca-Cola" and "COCA COLA" are the same name.

Example: coca cola

typeenumquery

Entity type: ORG, PERSON, GPE, LOC or PRODUCT. Without it every type is tried and the most-mentioned answer wins; the others are listed in other_types.

Example: ORG

How to use this endpoint

guidance

Use Normalize entity to turn whatever name a user typed into the normalized entity, with every recorded spelling that belongs to it. Each spelling belongs to exactly one entity, so expanding a query to these names never counts an event twice; match event mentions on match_keys to catch spellings the graph has not recorded. It describes the release as a whole, so it takes no as_of or from.

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.

queryobject

The name and type you sent.

entityobject

The normalized entity: {type, name, normalized}.

namesstring[]

Every recorded spelling that belongs to the entity, its own name first.

match_keysstring[]

The match keys of those names (lowercase letters and digits only, Latin accents folded).

other_typesobject[]

Other entity types that have the name, when type was not sent.

releasestring

Immutable id of the graph release 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 — A parameter is missing, malformed or out of range; the message names it.

400invalid_entity_type — The entity type is not one Atlas holds. TICKER is refused: send the company as an ORG.

400unknown_predicate — A relationship type is not in the graph; list them with Relationship types.

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.

404unknown_entity — No entity of that type has that name in this release. When the name exists under another type, the message says which.

404not_found — No endpoint matches this method and path.

410cursor_expired — The cursor belongs to another release or request; restart from the first page.

422unprocessable_request — Each value is valid but not together, such as from after as_of.

422request_too_broad — The request ran out of its work budget before it could answer; narrow it.

429rate_limited — Too many requests for this key; wait for Retry-After.

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

502backend_error — The Atlas backend could not be reached; retry shortly.

503unavailable — The service is busy or starting; retry after Retry-After.

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

504request_timeout — The request took longer than 25 seconds; narrow it.

504backend_timeout — The Atlas backend did not answer before the deadline; retry.