IDs & kinds
Stable ids you can store, and one vocabulary for places across countries.
Boundary ids
A boundary's id is its OpenStreetMap id: r plus the relation id, or w plus the way id. It's stable, and you can open any boundary on openstreetmap.org to check it. Inputs accept these forms; responses always use the canonical one:
| Input | Meaning |
|---|---|
| r62422 | Canonical: an OSM relation (Berlin) |
| w123456 | Canonical: a boundary drawn as one closed OSM way |
| R62422, relation/62422, rel 62422 | Common spellings |
| -62422 | osm2pgsql's negative relation ids |
| https://www.openstreetmap.org/relation/62422 | An osm.org URL |
| wikidata:Q64 | A Wikidata item |
| iso:US-CA, iso:DE | ISO 3166-2 or 3166-1 code |
Wikidata and ISO ids are looked up once, then answered from our table.
Kinds
OSM's admin_level means different things per country: level 4 is a US state, a French region and a Japanese prefecture; level 8 is a German Gemeinde and a US city. Each boundary also has a kind from one vocabulary, so you can filter the same way everywhere:
country, state, region, province, county, district, municipality, city, borough, ward, neighbourhood, postal_code.
Level 2 is always country, and postcode areas are postal_code. Below that, a sample:
| Country | Level 4 | Level 5 | Level 6 | Level 7 | Level 8 | Level 9 | Level 10 |
|---|---|---|---|---|---|---|---|
| US | state | region | county | municipality | city | ward | neighbourhood |
| GB | region | region | county | district | district | ward | ward |
| DE | state | region | district | municipality | municipality | borough | neighbourhood |
| FR | region | region | county | district | municipality | borough | neighbourhood |
| ES | region | region | province | district | municipality | district | neighbourhood |
| JP | province | region | county | municipality | borough | neighbourhood | neighbourhood |
| IN | state | district | district | district | city | ward | neighbourhood |
| BR | state | region | county | region | municipality | district | neighbourhood |
| AU | state | region | municipality | district | municipality | neighbourhood | neighbourhood |
| Other | state | region | county | district | municipality | borough | neighbourhood |
A municipality OSM tags as a city becomes city. Filter search with kind, or with admin_level when you need OSM's own level.