Skip to main content
GET
Raw position points in an area

Authorizations

Authorization
string
header
required

GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....

Query Parameters

chokepoint
enum<string>

One chokepoint as the area. One of chokepoint / bbox / near / near_gem_id is required.

Available options:
hormuz,
bab_el_mandeb,
malacca,
suez,
panama,
bosphorus,
gibraltar,
dover,
kerch,
taiwan,
danish_straits
bbox
string

Bounding box filter: minLon,minLat,maxLon,maxLat (lon-first axis order). One of chokepoint / bbox / near / near_gem_id is required.

near
string

Point 'lat,lon' for a radius area; combine with radius_km (default 50 km). Rows include distance_km. One of chokepoint / bbox / near / near_gem_id is required.

near_gem_id
string

GEM energy-asset gem_id center — points within radius_km of that asset (default 25 km). Rows include distance_km. One of chokepoint / bbox / near / near_gem_id is required.

radius_km
number

Radius in km for near / near_gem_id. Default 50 (near) or 25 (near_gem_id); clamped 1–2000.

date_start
string

Window start YYYY-MM-DD (≤7-day window).

date_end
string

Window end YYYY-MM-DD.

days
integer

Trailing N-day window (1–7). Defaults to 1.

Required range: 1 <= x <= 7
limit
integer
default:1000

Position points per page (1–5000).

Required range: 1 <= x <= 5000
cursor
string

Opaque keyset cursor on (time, mmsi). Pass back a prior response's next_cursor to fetch the next page; do not request one giant response.

Response

A page of raw position points, time-ordered ascending. Envelope: { success, data, pagination, applied_filters }. Each data row: time, mmsi, imo, lat, lon, sog, cog, nav_status, chokepoint, and distance_km (km from the near / near_gem_id center, only when one is set). pagination.next_cursor is an opaque token — follow it to page through a long window.

success
boolean
data
object[]
pagination
object
applied_filters
object