UN/LOCODE

11 endpoints at a glance

Method	Path	Summary
POST	/atlas/unlocode/refresh/	Refresh Unlocode
GET	/unlocode/	Search
GET	/unlocode/{code}/	Get Code
GET	/unlocode/{code}/changes/	List Changes
GET	/unlocode/{code}/neighbors/	Get Neighbors
GET	/unlocode/anchor-fqdn/	Anchor Fqdn
GET	/unlocode/function-classifiers/	Function Classifiers
GET	/unlocode/imports/	List Imports
GET	/unlocode/imports/{import_id}/	Get Import
POST	/unlocode/imports/run	Run Import
GET	/unlocode/status/	Get Status

unlocode

---

Get Status

GET

/unlocode/status/

Admin-header tiles + worker snapshot.

Parameters

Header Parameters

authorization

x-api-key

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/unlocode/status/

Playground

Headers

authorization

x-api-key

Samples

---

List Imports

GET

/unlocode/imports/

Newest-first import-run rows. since / until inclusive
YYYY-MM-DD bounds on started_at.

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

since

until

trigger

limit

Type

integer

Default

100

Responses

Successful Response

Content-Type

application/json

[

  

{

  

  

"additionalProperties": "string"

  

}

]

GET

/unlocode/imports/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

since

until

trigger

limit

Samples

---

Get Import

GET

/unlocode/imports/{import_id}/

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

import_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/unlocode/imports/{import_id}/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

import_id*

Samples

---

Run Import

POST

/unlocode/imports/run

Queue the import. Returns immediately; the serial worker picks
it up and writes the running audit row. 403 when the dataset
is disabled.

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

force

Re-run even if the source commit is unchanged (otherwise the import skips a no-op download).

Type

boolean

Default

false

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/unlocode/imports/run

Playground

Headers

authorization

x-api-key

Variables

Key

Value

force

Samples

---

Function Classifiers

GET

/unlocode/function-classifiers/

The 10-row Function-flag legend (bundled, static) so the UI can
decode the 8-position data.function string.

Parameters

Header Parameters

authorization

x-api-key

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/unlocode/function-classifiers/

Playground

Headers

authorization

x-api-key

Samples

---

Anchor Fqdn

GET

/unlocode/anchor-fqdn/

Derive candidate anchor FQDN(s) from the nearest UN/LOCODE(s)
to (lat, lon).

Public — no auth gate (pure derivation over open UN/LOCODE
reference data + a public-FQDN existence flag; same posture as the
public /series/ reads). Unlike the other /unlocode reads
this one is intentionally unauthenticated.

For each of the n nearest UN/LOCODE records (by great-circle
distance over the coords-bearing subset) we assemble
<cc>-<loc>-as<asn>.anchors.atlas.ripe.net and flag whether an
anchor with that exact FQDN already exists (one batched
db.anchors lookup). Pure read — no writes, no RIPE calls; the
caller decides what to do with a collision (we don't guess RIPE's
multi-anchor numbering). Declared before /{code}/ so the
literal segment wins. 400 on out-of-range lat/lon/asn/n.

Parameters

Query Parameters

lat*

Type

number

Required

Maximum

90

Minimum

-90

lon*

Type

number

Required

Maximum

180

Minimum

-180

asn*

AS number for the as segment

Type

integer

Required

Minimum

1

n

how many nearest candidates

Type

integer

Maximum

25

Minimum

1

Default

1

asn_holder

True/omitted = anchor host holds the ASN (plain hostname). False = host is a client → append '-client' to the hostname label.

Type

boolean

Default

true

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/unlocode/anchor-fqdn/

Playground

Variables

Key

Value

lat*

lon*

asn*

n

asn_holder

Samples

---

Search

GET

/unlocode/

Lookup by country / name-or-code / alias / nearest.

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

country

ISO cca2 filter

q

code / name / alias prefix

near

"lat,lon" nearest

limit

Type

integer

Default

50

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/unlocode/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

country

q

near

limit

Samples

---

List Changes

GET

/unlocode/{code}/changes/

Per-record change history (newest-first).

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

code*

Type

string

Required

Query Parameters

since_ts

until_ts

skip

Type

integer

Default

0

limit

Type

integer

Default

100

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/unlocode/{code}/changes/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

code*

since_ts

until_ts

skip

limit

Samples

---

Get Neighbors

GET

/unlocode/{code}/neighbors/

The code plus its limit nearest other UN/LOCODEs (for the
detail-view map: the selected location + its closest neighbours).
404 when unknown or coordinate-less (nothing to plot). Declared
before /{code}/ so the literal segment wins.

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

code*

Type

string

Required

Query Parameters

limit

how many nearest others

Type

integer

Maximum

25

Minimum

1

Default

10

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/unlocode/{code}/neighbors/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

code*

limit

Samples

---

Get Code

GET

/unlocode/{code}/

Single code + joined aliases. 404 when unknown.

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

code*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/unlocode/{code}/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

code*

Samples

---

Refresh Unlocode

POST

/atlas/unlocode/refresh/

Queue an improved-UN/LOCODE import (ops companion to the admin
panel's Run button). Returns immediately — the serial worker does
the ~13 MB code-list + ~17 MB aliases parse off-thread and writes
the audit row. ?force=true re-runs even if the upstream commit
is unchanged (default skips a no-op download).

Authorizations

APIKeyQuery

Type

API Key (query: api-key)

or

APIKeyHeader

Type

API Key (header: x-api-key)

Parameters

Query Parameters

force

Type

boolean

Default

false

Responses

Successful Response

Content-Type

application/json

[

]

POST

/atlas/unlocode/refresh/

Playground

Authorization

APIKeyQuery

Variables

Key

Value

force

Samples

---