Appearance
GeoNames
7 endpoints at a glance
| Method | Path | Summary |
|---|---|---|
GET | /geonames/{geonameid}/changes/ | List Changes |
GET | /geonames/datasets/ | List Datasets |
GET | /geonames/imports/ | List Imports |
GET | /geonames/imports/{import_id}/ | Get Import |
POST | /geonames/imports/run | Submit Import |
GET | /geonames/stats/ | Get Stats |
GET | /geonames/status/ | Get Status |
geonames
List Datasets
GET
/geonames/datasets/
Catalogue of importable datasets — drives the admin dropdown.
Static today (the four GeoNames cities files); kept on the wire
surface so a future addition (e.g. allCountries, per-country) is
a backend-only change.
Parameters
Header Parameters
authorization
x-api-key
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Get Status
GET
/geonames/status/
High-level admin-header state — current dataset, total cities,
last import timestamp, plus the worker's in-flight dataset and
queue depth so the UI can render a "Importing cities5000…" chip
without polling the import history.
Parameters
Header Parameters
authorization
x-api-key
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Get Stats
List Imports
GET
/geonames/imports/
Newest-first list of import-run rows. since / until are
inclusive YYYY-MM-DD bounds on started_at. Limit clamped
to 1000 by the storage layer.
Parameters
Header Parameters
authorization
x-api-key
Query Parameters
since
until
limit
Type
integer
Default
100Responses
Successful Response
application/json
JSON { "additionalProperties": "string" }
[
]
Get Import
GET
/geonames/imports/{import_id}/
Single import-run row including the full stats block when
present. import_id is the <dataset>_<started_ts> we
generated at submission time.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
import_id*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Submit Import
POST
/geonames/imports/run
Queue an import job. Returns immediately with a placeholder
audit row; the worker picks it up serially.
Validates the dataset name up front so a typo gets a 400 instead
of disappearing into the worker. The actual running audit
row is written by Geonames.import_dataset once the worker
reaches it — until then GET /imports/ won't show this
submission.
Parameters
Header Parameters
authorization
x-api-key
Request Body
application/json
JSON "dataset": "string", "skip_if_unchanged": false
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
List Changes
GET
/geonames/{geonameid}/changes/
Per-record change history for one city (newest-first).
Populated by the import's diff (anchors/unlocode style): one row
per import where the city's place fields materially changed.
Declared after the literal routes so int {geonameid}
can't shadow /imports/ etc. Admin-gated like the rest of this
panel.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
geonameid*
Type
Requiredinteger
Query Parameters
since_ts
until_ts
skip
Type
integer
Default
0limit
Type
integer
Default
100Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}