World API/GET EVENTS

By polygon

Retrieve full World V2.0 event records with a stored location inside a GeoJSON polygon or multipolygon.

POST/api/v2.0/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 date window. Published newer slices through today are included automatically; the front door clamps the lower bound to the API key's tier window. to cannot be later than today (UTC).

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 across the unified archive and published newer slices. 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"]

include_livebooleanbody

Defaults to true. Include published slices after the archive index, including today and yesterday (UTC). Set false for archive-only retrieval. GET uses the query string; POST uses a JSON boolean.

Example: true

Related in NOSIBLE World

World · Map ↗Open this result set on the event map, filtered to the same windowWorld · Trend ↗Plot the same query as a historical event signalWorld · Chaos ↗Watch the unfiltered crawl the ontology is built from

How to use this endpoint

guidance

Available only in V2.0 at /api/v2.0/polygon/events. An event matches when any stored location is inside the GeoJSON Polygon or MultiPolygon; coordinates are [longitude, latitude], outer and hole boundaries count as inside, and a point inside a hole does not. GET uses query parameters with polygon URL-encoded as GeoJSON; POST accepts the same options in JSON, with request bodies capped at 128 KiB. Each page returns full hydrated event records in one events[] array, merging archive results with every published newer slice after the archived index through today (UTC). The V2.0 service publishes yesterday and today as recent slices and checks them automatically when they fall inside the requested dates. The normal World API key/session gate and tier-clamped date floor apply. include_live defaults to true, just as on the entity, ticker and ontology timelines; set it to false for archive-only results. Polygon pages use one events[] list. to defaults to today and cannot be later. The opaque cursor is bound to polygon, effective dates, order, language and archive index build; send it unchanged to avoid gaps or overlaps. Live rows are read from the same pinned source snapshot as their live polygon index, and live membership is refreshed on each page with a date/event_id keyset. A source publish between page requests can change later live membership, so restart from page one when a consistent traversal is needed. An archive republish expires the cursor with 410 cursor_expired. Use order and language to control the unified result set, view=lite (default) or view=full to choose event projection, and include_vector=true when the embedding is needed.

About records

lite and full

By polygon returns the same fully hydrated V2.0 event records as the other World event timelines. view=lite is the default; view=full adds provenance, availability, triples, each ticker's why and v2_preview_success. A page contains complete records, not event IDs that need a separate hydration call.

include_vector=true adds each matching event's embedding to either view. Send view and include_vector in the POST body or as GET query parameters.

The fields of a lite record:

event_idstring

Stable event identifier.

versionstring

Event record version: "2.0-preview".

eventobject

The event in its original language: date, language, title, description and points.

event.datedate

World archive date of the event.

event.languagestring

ISO 639-1 code of the event's original language.

event.titlestring

Headline, in the original language.

event.descriptionstring

Short narrative, in the original language.

event.pointsstring[]

Key facts of the event, one sentence each.

englishobject

The event in English: title, description and points, translated when the original language is not English.

coverageobject

total_coverage, total_netlocs, coverage_concentration_index, first_seen, last_seen and most_seen, as in Event details.

locationsobject[]

Places of the event, its own place first, then places named in it, as in Event details.

signalsobject

Sentiment, materiality, time horizon and forward-looking signals with their class probabilities, as in Event details.

tickersobject[]

Listed companies the event concerns, in the Event details format without why. Empty when has_tickers is false.

has_tickersboolean

Whether tickers is non-empty.

entitiesobject

Named entities by NER type, {TYPE: [{name, mention_count, confidence}]}, as in Event details.

sentimentsobject

Entity-level sentiment grouped by entity type. Each item has name, sentiment_label (positive, neutral or negative), and sentiment_score, the final Percentage Margin Z-score.

ontologiesobject[]

Classifications of the event, most probable first, as in Event details.

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

Effective date range through today (UTC), the archive boundary, and the effective include_live option.

date_window.fromdate

First date in the effective tier-clamped window.

date_window.todate

Last date in the effective window; defaults to today (UTC) and never exceeds today.

date_window.index_last_datedate

Last date included in the current archived index.

date_window.archive_cutoffdate

Archive cutoff reported by the active World index.

date_window.include_liveboolean

Effective include_live choice. Defaults to true; false restricts the timeline to the archive.

eventsobject[]

Unified, fully hydrated V2.0 event records from the archive and any published newer slices in the effective date range, ordered and paged together. Lite by default; view=full returns the complete records.

events[].event_idstring

Stable event identifier.

events[].versionstring

Event record version: "2.0-preview".

events[].eventobject

The event in its original language: date, language, title, description and points.

events[].event.datedate

World archive date of the event.

events[].event.languagestring

ISO 639-1 code of the event's original language.

events[].event.titlestring

Headline, in the original language.

events[].event.descriptionstring

Short narrative, in the original language.

events[].event.pointsstring[]

Key facts of the event, one sentence each.

events[].englishobject

The event in English: title, description and points, translated when the original language is not English.

events[].coverageobject

total_coverage, total_netlocs, coverage_concentration_index, first_seen, last_seen and most_seen, as in Event details.

events[].locationsobject[]

Places of the event, its own place first, then places named in it, as in Event details.

events[].signalsobject

Sentiment, materiality, time horizon and forward-looking signals with their class probabilities, as in Event details.

events[].tickersobject[]

Listed companies the event concerns, in the Event details format without why. Empty when has_tickers is false.

events[].has_tickersboolean

Whether tickers is non-empty.

events[].entitiesobject

Named entities by NER type, {TYPE: [{name, mention_count, confidence}]}, as in Event details.

events[].sentimentsobject

Entity-level sentiment grouped by entity type. Each item has name, sentiment_label (positive, neutral or negative), and sentiment_score, the final Percentage Margin Z-score.

events[].ontologiesobject[]

Classifications of the event, most probable first, as in Event details.

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.

as_of.index_buildstring

Archive index generation used for the page. A later generation expires existing cursors with 410 cursor_expired.

as_of.archive_cutoffdate

Archive cutoff reported by the active World index.

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.