locations

23 endpoints at a glance

Method	Path	Summary
GET	/admin/locations/cities/datasets	List Datasets
GET	/admin/locations/cities/imports	List Imports
GET	/admin/locations/cities/imports/{import_id}	Get Import
POST	/admin/locations/cities/imports/run	Submit Import
GET	/admin/locations/cities/stats	Cities Stats
GET	/admin/locations/cities/status	Cities Status
GET	/admin/locations/languages/imports	List Language Imports
GET	/admin/locations/languages/imports/{import_id}	Get Language Import
POST	/admin/locations/languages/imports/run	Run Language Import
GET	/admin/locations/languages/stats	Languages Stats
GET	/admin/locations/languages/status	Languages Status
GET	/locations/cities	List Cities
GET	/locations/cities/{geoname_id}	Get City
GET	/locations/cities/{geoname_id}/history	Get City History
GET	/locations/cities/countries	List Country Counts
GET	/locations/countries	List Countries
GET	/locations/countries/{cca2}	Get Country
POST	/locations/countries/refresh	Refresh Countries
GET	/locations/languages	List Languages
GET	/locations/languages/{lang_id}	Get Language
GET	/locations/regions	List Regions
GET	/locations/regions/{region_id}	Get Region
POST	/locations/regions/refresh	Refresh Regions

locations

---

List Countries

GET

/locations/countries

All countries.

details=false (default) → slim {code, name, region, flag}
picker payload. details=true → the full {code, data, meta}
envelope per row. Both ordered alphabetically by common name.

Parameters

Header Parameters

authorization

Query Parameters

details

Type

boolean

Default

false

Responses

Successful Response

Content-Type

application/json

[

  

{

  

  

"additionalProperties": "string"

  

}

]

GET

/locations/countries

Playground

Headers

authorization

Variables

Key

Value

details

Samples

---

Get Country

GET

/locations/countries/{cca2}

Parameters

Header Parameters

authorization

Path Parameters

cca2*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/locations/countries/{cca2}

Playground

Headers

authorization

Variables

Key

Value

cca2*

Samples

---

Refresh Countries

POST

/locations/countries/refresh

Pull the latest country dataset from REST Countries (admin only).

Runs the (blocking) HTTP + bulk-upsert off the event loop and records
a task_history row so the admin panel sees it.

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/locations/countries/refresh

Playground

Headers

authorization

Samples

---

List Regions

GET

/locations/regions

List subdivisions. country (cca2) narrows to one country.

Parameters

Header Parameters

authorization

Query Parameters

country

Responses

Successful Response

Content-Type

application/json

[

  

{

  

  

"additionalProperties": "string"

  

}

]

GET

/locations/regions

Playground

Headers

authorization

Variables

Key

Value

country

Samples

---

Get Region

GET

/locations/regions/{region_id}

Parameters

Header Parameters

authorization

Path Parameters

region_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/locations/regions/{region_id}

Playground

Headers

authorization

Variables

Key

Value

region_id*

Samples

---

Refresh Regions

POST

/locations/regions/refresh

Re-import the GeoNames admin1 subdivisions (admin only, audited).

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/locations/regions/refresh

Playground

Headers

authorization

Samples

---

List Cities

GET

/locations/cities

Paginated city search. Returns {rows, total, limit, offset}.

Parameters

Header Parameters

authorization

Query Parameters

q

country

admin1

min_population

limit

Type

integer

Maximum

200

Minimum

1

Default

25

offset

Type

integer

Minimum

0

Default

0

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/locations/cities

Playground

Headers

authorization

Variables

Key

Value

q

country

admin1

min_population

limit

offset

Samples

---

List Country Counts

GET

/locations/cities/countries

[{country_code, count}] for the country dropdown.

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

[

  

{

  

  

"additionalProperties": "string"

  

}

]

GET

/locations/cities/countries

Playground

Headers

authorization

Samples

---

Get City

GET

/locations/cities/{geoname_id}

One city plus its nearest neighbours (self excluded).

Parameters

Header Parameters

authorization

Path Parameters

geoname_id*

Type

integer

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/locations/cities/{geoname_id}

Playground

Headers

authorization

Variables

Key

Value

geoname_id*

Samples

---

Get City History

GET

/locations/cities/{geoname_id}/history

Per-city change history (most recent first).

Parameters

Header Parameters

authorization

Path Parameters

geoname_id*

Type

integer

Required

Query Parameters

skip

Type

integer

Minimum

0

Default

0

limit

Type

integer

Maximum

500

Minimum

1

Default

100

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/locations/cities/{geoname_id}/history

Playground

Headers

authorization

Variables

Key

Value

geoname_id*

skip

limit

Samples

---

List Languages

GET

/locations/languages

Search + filter + paginate. Slim {id, ref_name, part1, scope, type, retired} rows.

Parameters

Header Parameters

authorization

Query Parameters

q

scope

I | M | S

type

Living | Extinct | …

has_639_1

include_retired

Type

boolean

Default

false

page

Type

integer

Minimum

1

Default

1

limit

Type

integer

Maximum

200

Minimum

1

Default

50

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/locations/languages

Playground

Headers

authorization

Variables

Key

Value

q

scope

type

has_639_1

include_retired

page

limit

Samples

---

Get Language

GET

/locations/languages/{lang_id}

One language, full envelope. For a macrolanguage, resolves its members.

Parameters

Header Parameters

authorization

Path Parameters

lang_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/locations/languages/{lang_id}

Playground

Headers

authorization

Variables

Key

Value

lang_id*

Samples

---

List Datasets

GET

/admin/locations/cities/datasets

Importable GeoNames datasets with label + estimated row count.

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/locations/cities/datasets

Playground

Headers

authorization

Samples

---

Cities Status

GET

/admin/locations/cities/status

Current dataset, total cities, last import + live worker state.

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/locations/cities/status

Playground

Headers

authorization

Samples

---

Cities Stats

GET

/admin/locations/cities/stats

Live distributions + totals over the loaded dataset.

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/locations/cities/stats

Playground

Headers

authorization

Samples

---

List Imports

GET

/admin/locations/cities/imports

Newest-first import-run rows. Optional YYYY-MM-DD bounds.

Parameters

Header Parameters

authorization

Query Parameters

since

until

limit

Type

integer

Maximum

1000

Minimum

1

Default

100

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/locations/cities/imports

Playground

Headers

authorization

Variables

Key

Value

since

until

limit

Samples

---

Get Import

GET

/admin/locations/cities/imports/{import_id}

Parameters

Header Parameters

authorization

Path Parameters

import_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/locations/cities/imports/{import_id}

Playground

Headers

authorization

Variables

Key

Value

import_id*

Samples

---

Submit Import

POST

/admin/locations/cities/imports/run

Queue a cities import. Returns immediately with worker state.

Parameters

Header Parameters

authorization

Request Body

application/json

{

  

"dataset": "string",

  

"skip_if_unchanged": false

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/admin/locations/cities/imports/run

Playground

Headers

authorization

Body

Samples

---

Languages Status

GET

/admin/locations/languages/status

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/locations/languages/status

Playground

Headers

authorization

Samples

---

Languages Stats

GET

/admin/locations/languages/stats

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/locations/languages/stats

Playground

Headers

authorization

Samples

---

List Language Imports

GET

/admin/locations/languages/imports

Parameters

Header Parameters

authorization

Query Parameters

since

until

limit

Type

integer

Maximum

1000

Minimum

1

Default

100

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/locations/languages/imports

Playground

Headers

authorization

Variables

Key

Value

since

until

limit

Samples

---

Get Language Import

GET

/admin/locations/languages/imports/{import_id}

Parameters

Header Parameters

authorization

Path Parameters

import_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

GET

/admin/locations/languages/imports/{import_id}

Playground

Headers

authorization

Variables

Key

Value

import_id*

Samples

---

Run Language Import

POST

/admin/locations/languages/imports/run

Download the SIL tables + upsert (admin only). Runs the blocking work
off the event loop and returns the resulting import-audit row.

Parameters

Header Parameters

authorization

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/admin/locations/languages/imports/run

Playground

Headers

authorization

Samples

---