By polygon

Retrieve cursor-paged World events with a stored location inside a GeoJSON polygon or multipolygon.

POST/api/v2.0-preview/polygon/events

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

Authorizationstringheader

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

viewenumbody

The record each event is returned as: lite (the default), the event without its evidence, or full, the complete record. Any other value is a 422 validation_error. About records on Event details lists both.

Example: lite

include_vectorbooleanbody

true adds each event's embedding, oai_vector (3,072 values, comma-separated), to either view. Defaults to false.

Example: false

polygonobjectrequiredbody

GeoJSON Polygon or MultiPolygon geometry. Coordinates are [longitude, latitude]; do not wrap it in a Feature. POST bodies are limited to 128 KiB.

Example: {"type":"Polygon","coordinates":[[[-122.5,37.6],[-122.3,37.6],[-122.3,37.8],[-122.5,37.6]]]}

from / todatebody

Inclusive YYYY-MM-DD archive window. Anonymous/public requests are clamped to the accessible window floor.

Example: 2026-10-08

as_ofdatebody

Alias for to. Send as_of or to; if both are sent, their values must match.

Example: 2026-10-14

limitintegerbody

Page size. Defaults to 50 and is capped at 500.

Example: 50

cursorstringbody

Opaque next_cursor from the previous page. Send it unchanged with the same polygon and filters.

Example: eyJ2Ijox...

orderenumbody

Event order: desc (newest first, default) or asc (oldest first).

Example: desc

includeenumbody

Record projection: event_lite, lite, event_full, or full.

Example: event_lite

languagestring | string[]body

Optional language code or list of language codes.

Example: ["en"]

How to use this endpoint

guidance

Use By polygon to retrieve archive events by geography. An event matches when any of its stored locations is inside the geometry. Coordinates are [longitude, latitude]; outer and hole boundaries are included, while a point inside a hole is excluded. Polygon and MultiPolygon are accepted; Feature wrappers, include_live, body/query mixing, and repeated singleton query parameters are refused. GET accepts the same options as query parameters with polygon set to URL-encoded GeoJSON; use POST for larger geometries. Send next_cursor unchanged with the same polygon and filters. The cursor is bound to the effective polygon, tier-clamped date window, order, language, and index build. The route uses the normal World API-key/session gate, rate limit, and date-window clamp. Both verbs support from, to (or its as_of alias), limit, cursor, order, view, include, include_vector, and language.

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 the events are returned in: lite (the default) or full.

polygonobject

GeoJSON Polygon or MultiPolygon geometry used for the query.

totalinteger

Matching events in the effective date window before paging.

countinteger

Events in this page.

limitinteger

Page size applied.

orderstring

Event order: desc (newest first) or asc (oldest first).

date_windowobject

The effective inclusive archive window and archive cutoff; live events are not included.

eventsobject[]

Matching event records in the selected view.

events[].event_idstring

Stable event identifier.

events[].versionstring

Event record version: 2.0-preview.

events[].locationsobject[]

Stored locations attached to the event.

events[].locations[].latnumber

Latitude of a stored event location.

events[].locations[].lngnumber

Longitude of a stored event location.

next_cursorstring | null

Opaque cursor for the next page; send it unchanged with the same query.

hydration_missesinteger

Matching records that could not be read during hydration; normally 0.

as_ofobject

Index build and archive cutoff used for the query.

took_msinteger

Server time in milliseconds.

languagestring[]

Effective language filter; empty when none was sent.

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.

408request_timeout — The JSON body did not finish uploading within 10 seconds.

413payload_too_large — The POST body is larger than 128 KiB.

415unsupported_media_type — POST requires Content-Type: application/json.