From 0e2c88fdb02564f7877447b008d7dbc378eab92f Mon Sep 17 00:00:00 2001 From: Itz-Agasta Date: Sat, 23 May 2026 23:37:51 +0530 Subject: [PATCH] Clarifies postcode reference format in API docs Explains that spaces and hyphens in postcode IDs are replaced with underscores in stable postcode references and adds new examples for clarity. Improves guidance for constructing and using postcode refs in API endpoints. --- docs/api/Details.md | 7 ++++--- docs/api/Search.md | 4 ++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/api/Details.md b/docs/api/Details.md index 97be28cb..52c1d267 100644 --- a/docs/api/Details.md +++ b/docs/api/Details.md @@ -40,13 +40,14 @@ changes when data gets reimported. Therefore it cannot be used as a permanent id and shouldn't be used in bug reports. ``` xml -https://nominatim.openstreetmap.org/details?place_ref=P: +https://nominatim.openstreetmap.org/details?postcode=: ``` Artificial postcodes do not always have an OSM object reference. For these, Nominatim provides a stable postcode reference that combines the country code - and postcode. For example, `Pus:94110` refers to postcode `94110` in the - United States. +and postcode. Spaces and hyphens in the postcode id are replaced with +underscores. For example, `us:94110` refers to postcode `94110` in the +United States and `gb:EH4_7EA` refers to postcode `EH4 7EA` in Great Britain. !!! danger "Deprecation warning" The API can also be used with the URL diff --git a/docs/api/Search.md b/docs/api/Search.md index fca3e361..e31dbf66 100644 --- a/docs/api/Search.md +++ b/docs/api/Search.md @@ -240,9 +240,9 @@ Each entry may be one of: * a Nominatim internal `place_id` (for example `125279639`) * an OSM object reference in the form `` where `` is one of `N` (node), `W` (way) or `R` (relation), for example `N107775` -* a stable postcode reference in the form `P:`, for example `Pus:94110` +* a stable postcode reference in the form `P:`, for example `Pus:94110` or `Pgb:EH4_7EA` -Usage of OSM IDs is recommended because they are server independent. Stable postcode refs should be used for artificial postcode results without an OSM object reference. `place_id`s are still required for results without either kind of stable reference (for example, countries). When a street is excluded via its OSM ID, then interpolations and TIGER data derived from that street are excluded as well. +Usage of OSM IDs is recommended because they are server independent. Stable postcode refs should be used for artificial postcode results without an OSM object reference. In postcode refs, spaces and hyphens are replaced with underscores. `place_id`s are still required for results without either kind of stable reference (for example, countries). When a street is excluded via its OSM ID, then interpolations and TIGER data derived from that street are excluded as well. This can be used to retrieve additional search results. For example, if a previous query only returned a few results, then including those here would -- 2.47.3