locodata.ai · UN/LOCODE API Reference — Port Data, PLSCI & Trade Routes

Authentication

All API requests require an API key. Create a free account to get your key — it's issued automatically on sign-up.

Passing your key

HTTP header

GET /api/location/CNSHA HTTP/1.1
X-Api-Key: loco_sk_your_key_here

curl

curl https://locodata.ai/api/location/CNSHA \
     -H "X-Api-Key: loco_sk_your_key_here"

Plans & rate limits

Plan	Daily limit	Endpoints
Free	50 requests / day	/api/search · /api/locations · /api/location/{locode} (basic fields)
Standard	10,000 requests / day	All Free endpoints (full fields) + /api/regions/bbox
Pro	Unlimited (fair-use)	All endpoints + /api/region/{locode}/trade-routes + /api/alerts/{locode} + /api/maps/active-badges

When you exceed your daily limit the API returns HTTP 429. Limits reset at midnight UTC.

Response format

All endpoints return JSON. Errors return a standard shape:

JSON

{
  "detail": "LOCODE CNXYZ not found or has no coordinates"
}

GET /api/search Free

Multi-layer LOCODE search. Handles exact codes, fuzzy names, IATA codes, abbreviations, and non-Latin scripts (Chinese, Korean, Japanese, Arabic, Cyrillic). Returns results ranked by match quality.

Parameters

Name	Type		Description
q	string	required	Search query — LOCODE, name, IATA code, or non-Latin text. Min 2 chars.
limit	integer	optional	Max results to return. Default `20`, max `50`.
country	string	optional	ISO alpha-2 country code to restrict results. E.g. `JP`, `CN`.

Example

Request

GET /api/search?q=Shanghai&limit=5
GET /api/search?q=上海&country=CN   // Chinese script
GET /api/search?q=JFK               // IATA code

Response fields

Array of location objects

locodestring5-character UN/LOCODE (e.g. CNSHA)

namestringLocation name

country_codestringISO alpha-2 country

match_scorefloatSimilarity score 0–1. Higher = better match

matched_termstringThe exact term that matched (useful for alternate names)

time_zonestringIANA timezone identifier

populationintegerCity population

lat, lonfloatWGS-84 coordinates

GET /api/locations Free

Fast ASCII name prefix search. Best for the map search box where results need to appear as the user types. Searches name_ascii and geo_asciiname fields only — use /api/search for non-Latin scripts.

Parameters

Name	Type		Description
q	string	required	ASCII name prefix or LOCODE. Min 2 chars.
limit	integer	optional	Max results. Default `50`, max `500`.

Request

GET /api/locations?q=Rotterdam&limit=10

GET /api/location/{locode} Free

Full enrichment for a single LOCODE. If the LOCODE is a member of a port region, it automatically resolves to the region anchor and returns the full region profile. Includes PLSCI connectivity, WPI depth data, nearby airports, nearby regions, major cities, and upcoming public holidays.

Member resolution: GET /api/location/CNZOS (Zhoushan) returns Ningbo's full region profile because Zhoushan is a PLSCI member of CNNGB.

Parameters

Name	Type		Description
locode	string	path	5-character UN/LOCODE. Case-insensitive.
radius_km	float	optional	Search radius for nearby cities. Default `50` km.
limit	integer	optional	Max items per section. Default `5`.

Example

Request

GET /api/location/CNNGB   // Ningbo, China
GET /api/location/JPTYO   // Tokyo, Japan
GET /api/location/NLRTM   // Rotterdam, Netherlands

Response shape

Top-level keys

referenceobjectLocation + port region data merged. See fields below.

region_membersarrayMember LOCODEs of the port region with role, depth, facility data.

nearby_regionsarrayUp to 5 nearby port regions with cluster_relationship and alternative_gateway.

nearby_airportsarrayIATA airports within radius, sorted by weighted distance + rank.

major_citiesarrayMajor city LOCODEs within radius_km.

reference object — key fields

locodestringResolved LOCODE (may differ from input if member was resolved to anchor)

namestringLocation / region name

plsci_scorefloatUNCTAD PLSCI connectivity score. null for non-PLSCI ports.

plsci_rankintegerGlobal rank (1 = highest). null for non-PLSCI ports.

voyage_activitystring"active" or "inactive" based on AIS voyage history.

channel_depth_mfloatChannel depth in metres. null = unknown.

fac_containerstringContainer facility: "Yes", "No", or "Unknown".

time_zonestringIANA timezone (e.g. "Asia/Shanghai")

upcoming_holidaysarrayNext 3 public holidays with date and name.

lat, lonfloatWGS-84 coordinates

GET /api/regions/bbox Standard

Returns port regions visible within a map bounding box. Used to populate the map as the user pans and zooms. Returns PLSCI score and coordinates for each region anchor.

Parameters

Name	Type		Description
west	float	required	Western longitude bound
south	float	required	Southern latitude bound
east	float	required	Eastern longitude bound
north	float	required	Northern latitude bound
limit	integer	optional	Max regions. Default `500`.

Request

GET /api/regions/bbox?west=-10&south=35&east=30&north=60
// Returns all port regions visible over Europe

GET /api/region/{locode}/trade-routes Pro

Active AIS trade routes for a port region, aggregated across the two most recent quarters. Groups routes by vessel type and classifies each route as local, coastal, regional, or ocean. Activity level is benchmarked against the average for that vessel type globally.

Pass any member LOCODE — it resolves to the region anchor automatically. /api/region/CNZOS/trade-routes returns Ningbo's routes.

Parameters

Name	Type		Description
locode	string	path	Region anchor or any member LOCODE.

Example

Request

GET /api/region/CNNGB/trade-routes   // Ningbo
GET /api/region/NLRTM/trade-routes   // Rotterdam
GET /api/region/USLGB/trade-routes   // Long Beach

Response shape

Top-level

region_locodestringResolved anchor LOCODE

region_namestringRegion name

periodsstring[]Quarters included, e.g. ["2026-Q2","2026-Q1"]

member_countintegerNumber of member LOCODEs in the region

routes_by_typeobjectKeyed by vessel type: container, bulk_carrier, tanker, ro_ro, general_cargo

Each route object

from_actual_locodestringActual origin port LOCODE (sub-terminal level)

from_region_locodestringOrigin port region anchor LOCODE

from_region_namestringHuman-readable origin region name

to_actual_locodestringActual destination LOCODE

to_region_locodestringDestination region anchor LOCODE

to_region_namestringHuman-readable destination region name

directionstring"outbound" or "inbound" relative to the queried region

route_classstring"local" <150km · "coastal" same-country <800km · "regional" same-continent · "ocean" cross-continental

activity_levelstring"high" · "above_avg" · "average" · "below_avg" · "low" — benchmarked against all routes of same vessel type

median_transit_daysfloatMedian AIS transit time in days

dist_kmfloatMedian straight-line distance in km

Sample response (truncated)

JSON · Ningbo → Long Beach

{
  "region_locode":  "CNNGB",
  "region_name":    "Ningbo",
  "periods":        ["2026-Q2", "2026-Q1"],
  "member_count":   14,
  "routes_by_type": {
    "container": [
      {
        "from_actual_locode":  "CNZOS",
        "from_region_locode":  "CNNGB",
        "from_region_name":    "Ningbo",
        "to_actual_locode":    "USLGB",
        "to_region_locode":    "USLGB",
        "to_region_name":      "Long Beach",
        "direction":           "outbound",
        "route_class":         "ocean",
        "activity_level":      "high",
        "median_transit_days":  13.4,
        "dist_km":             10535.0
      }
    ]
  }
}

GET /api/alerts/{locode} Pro

Active port disruption alerts for a specific LOCODE — strikes, weather, accidents, geopolitical events, and trade policy changes (sanctions, tariffs, embargoes). Returns up to 5 alerts from the last 7 days, ranked by severity then recency. Ideal for integrating real-time port risk into TMS, ERP, or trading dashboards.

A single alert may cover multiple ports (e.g. a Hormuz crisis alert links to both OMMSQ and AEJEA). Querying either LOCODE returns the same alert.

Parameters

Name	Type		Description
locode	string	path	Any UN/LOCODE. Also resolves member LOCODEs to their region anchor.

Example

Request

GET /api/alerts/OMMSQ   // Muscat — Strait of Hormuz
GET /api/alerts/BEANR   // Antwerp
GET /api/alerts/SAJED   // Jeddah — Red Sea
X-Api-Key: loco_sk_...

Response shape

Top-level

locodestringQueried LOCODE

alertsarrayUp to 5 active alerts, sorted by severity then recency

Each alert object

severitystring"high" · "medium" · "low"

alert_typestring"strike" · "weather" · "accident" · "congestion" · "geopolitical" · "trade_policy" · "other"

locodesstring[]All LOCODEs affected by this alert

headlinestringOriginal news headline

ai_summarystringOne-sentence AI-generated summary in English

source_namestringNews source (e.g. gCaptain, Reuters)

time_agostringHuman-readable age e.g. "3h ago" · "2d ago"

Sample response

JSON · OMMSQ (Hormuz)

{
  "locode":  "OMMSQ",
  "alerts": [
    {
      "severity":    "high",
      "alert_type":  "geopolitical",
      "locodes":     ["OMMSQ", "AEJEA"],
      "headline":    "Strait of Hormuz Crisis Is Cracking the Petrodollar System",
      "ai_summary":  "Escalating tensions in the Strait of Hormuz are disrupting tanker routing and energy markets.",
      "source_name": "gCaptain",
      "time_ago":    "6h ago"
    }
  ]
}

GET /api/maps/active-badges Pro

Returns a compact {"locode": "severity"} dictionary for all ports with active alerts. Designed for dashboard map rendering — one request gives you the full global alert state, which you join client-side with your port coordinates to render risk indicators.

Example

Request

GET /api/maps/active-badges
X-Api-Key: loco_sk_...

Sample response

JSON

{
  "OMMSQ": "high",
  "AEJEA": "high",
  "BEANR": "medium",
  "BRSSZ": "medium"
}

Every port, terminal & depot.One clean API.

Authentication

Passing your key

Plans & rate limits

Response format

Parameters

Example

Response fields

Parameters

Parameters

Example

Response shape

Parameters

Parameters

Example

Response shape

Sample response (truncated)

Parameters

Example

Response shape

Sample response

Example

Sample response

Every port, terminal & depot.
One clean API.