Text to Geo (Single)

Find geographic locations mentioned or supported by the entities in one text.

POST/api/v2.0-preview/models/geocode

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_...

Body

application/json

textstringrequiredbody

Text to geocode. Maximum 8,000 characters (UTF-16 code units). JSON body limit: 64 KiB. Upload deadline: 5 seconds; upstream deadline: 10 seconds.

Example: A concert took place at Newlands Stadium in Cape Town, South Africa.

How to use this endpoint

guidance

Available only in V2.0-preview. Send one text and receive the same schema, model, text, and predictions envelope as ticker tagging and the other Model APIs. Each prediction contains a resolved location, from direct place names or supported Atlas graph associations. No matches produces an empty predictions array. Coordinates describe a representative point for each resolved place; they are not precise event coordinates. Location predictions contain no scores or evidence chains.

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

Stable response schema shared with the other text model endpoints.

Example: nosible_model_classification_v1

modelstring

Pinned geography tagger engine revision.

Example: NOSIBLE/geo-tagger-v2.0-preview@revision:c9fe46347e5422548c0e0780ddbc6252284619a1

textstring

The exact input text, preserved without trimming.

Example: A concert took place at Newlands Stadium in Cape Town, South Africa.

predictionsobject[]

Resolved geographic locations. An empty array is a successful no-match result.

Example: [{ continent, region, country, lat, lng, source, matched_on, entity_type }]

predictions[].continentstring | null

Continent containing the resolved place, when known.

Example: Africa

predictions[].regionstring | null

State or province associated with the resolved place, when known.

Example: null

predictions[].countrystring | null

Country containing the resolved place, when known.

Example: South Africa

predictions[].latnumber

Representative latitude in decimal degrees, from −90 to 90.

Example: -29

predictions[].lngnumber

Representative longitude in decimal degrees, from −180 to 180.

Example: 24

predictions[].sourcestring

Location source. Text matching and supported graph associations use ner; the World location schema also supports llm.

Example: ner

predictions[].matched_onstring

The text or supporting entity matched to this location.

Example: South Africa

predictions[].entity_typestring (optional)

Type of the supporting named entity, when available.

Example: GPE

Responses and errors

HTTP

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

400invalid_json — Request body is not valid UTF-8 JSON.

401api_key_required / invalid_api_key — A valid NOSIBLE bearer API key is required.

408request_timeout — Request body did not finish within 5 seconds.

413request_too_large — JSON request body exceeds the endpoint's byte limit.

422validation_error — Text is missing, blank, too long, or contains unsupported request fields; a batch must also satisfy the item and total-text limits.

429rate_limited / model_rate_limited — Caller or upstream rate limit exceeded. Respect Retry-After when present.

502model_invalid_response — The geocoder returned an invalid location or an incomplete batch. This is distinct from a successful empty predictions array.

502model_upstream_error / model_upstream_unreachable — The geocoder rejected the request or could not be reached.

503model_not_configured — The geocoder is not configured for this deployment.

503api_key_auth_not_configured / api_key_auth_unavailable / api_key_metering_unavailable — Authentication or quota metering is temporarily unavailable.

504model_upstream_timeout — The geocoder did not respond within 10 seconds. No automatic retries are made.

404not_found — Ticker and Geo tagging are unavailable in V1.2. Use the /api/v2.0-preview/models/ routes.