curl --request GET \
--url https://gdeltcloud.com/api/v2/maritime/ports \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/maritime/ports"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/maritime/ports', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": [
{
"port_id": "NLRTM",
"name": "Rotterdam",
"alt_name": "Rotterdam",
"unlocode": "NLRTM",
"country": "NLD",
"country_name": "Netherlands",
"region": "Western Europe",
"water_body": "North Sea",
"lat": 51.95,
"lon": 4.14,
"harbor_size": "Large",
"harbor_type": "Coastal Natural",
"harbor_use": "Commercial",
"max_vessel_draft_m": 24.4,
"channel_depth_m": 24.4,
"lng_terminal": true,
"oil_terminal": true,
"container": true,
"source": "wpi"
}
],
"pagination": {
"limit": 100,
"cursor": null,
"next_cursor": null
},
"applied_filters": {
"ignored": {}
}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}Ports reference
The open-data ports reference (NGA World Port Index) — ~3,800 ports with coordinates, UN/LOCODE, harbor size/type/use, max vessel draft, channel depth, and container / oil / LNG terminal facilities. Filter by country, harbor size, terminal type, name, or proximity to a point / GEM energy asset. This is reference data (no date window). Requires a plan with Maritime intelligence access (can_use_maritime) — see Pricing for the plans that include it.
When a proximity center is set (near, near_gem_id), each row carries distance_km and results sort nearest-first. Standard envelope: { success, data, pagination, applied_filters }.
curl --request GET \
--url https://gdeltcloud.com/api/v2/maritime/ports \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/maritime/ports"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/maritime/ports', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": [
{
"port_id": "NLRTM",
"name": "Rotterdam",
"alt_name": "Rotterdam",
"unlocode": "NLRTM",
"country": "NLD",
"country_name": "Netherlands",
"region": "Western Europe",
"water_body": "North Sea",
"lat": 51.95,
"lon": 4.14,
"harbor_size": "Large",
"harbor_type": "Coastal Natural",
"harbor_use": "Commercial",
"max_vessel_draft_m": 24.4,
"channel_depth_m": 24.4,
"lng_terminal": true,
"oil_terminal": true,
"container": true,
"source": "wpi"
}
],
"pagination": {
"limit": 100,
"cursor": null,
"next_cursor": null
},
"applied_filters": {
"ignored": {}
}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"details": {}
}Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Case-insensitive match on port name, alternate name, or UN/LOCODE.
Country filter on ports. Accepts a country name, ISO-2, or ISO-3 (e.g. Netherlands, NL, NLD) via the shared resolveCountryInput layer; an unresolvable value returns 400 INVALID_COUNTRY. Full value list: https://docs.gdeltcloud.com/reference/enums#country
Minimum harbor size (inclusive of larger sizes). Full value list: https://docs.gdeltcloud.com/reference/enums#min_harbor_size
very_small, small, medium, large true → only ports with an LNG terminal.
true → only ports with an oil terminal.
Point 'lat,lon' for a radius search; combine with radius_km (default 100). Results carry distance_km, sorted nearest-first. Format: lat,lon — pass the radius separately in radius_km.
"51.5,-0.12"
GEM energy-asset gem_id — returns ports within radius_km of that LNG terminal / platform / port (cross-source join).
Radius in km for near / near_gem_id. Default 100; clamped 1–2000.
Bounding box filter: minLon,minLat,maxLon,maxLat (lon-first, e.g. -6,35,5,44).
Rows per page (1–500).
1 <= x <= 500Pagination cursor (offset) from a prior response's next_cursor.
Response
A page of ports. Each row: port_id, name, alt_name, unlocode, country (ISO-3), country_name, region, water_body, lat, lon, harbor_size, harbor_type, harbor_use, max_vessel_draft_m, channel_depth_m, lng_terminal / oil_terminal / container booleans, and distance_km (only when a proximity center is set).

