# Place Output
-The [\reverse](Reverse.md), [\search](Search.md) and [\lookup](Lookup.md)
+The [/reverse](Reverse.md), [/search](Search.md) and [/lookup](Lookup.md)
API calls produce very similar output which is explained in this section.
There is one section for each format which is selectable via the `format`
parameter.
The possible fields are:
- * `place_id` - reference to the Nominatim internal database ID
+ * `place_id` - reference to the Nominatim internal database ID (see notes below)
* `osm_type`, `osm_id` - reference to the OSM object
* `boundingbox` - area of corner coordinates
* `lat`, `lon` - latitude and longitude of the centroid of the object
### GeoJSON
-This format follows the [RFC7946](http://geojson.org). Every feature includes
+This format follows the [RFC7946](https://geojson.org). Every feature includes
a bounding box (`bbox`).
The feature list has the following fields:
- * `place_id` - reference to the Nominatim internal database ID
+ * `place_id` - reference to the Nominatim internal database ID (see notes below)
* `osm_type`, `osm_id` - reference to the OSM object
* `category`, `type` - key and value of the main OSM tag
* `display_name` - full comma-separated address
* `importance` - computed importance rank
* `icon` - link to class icon (if available)
* `address` - dictionary of address details (only with `addressdetails=1`)
- * `extratags` - dictionary with additional useful tags like website or maxspeed
+ * `extratags` - dictionary with additional useful tags like `website` or `maxspeed`
(only with `extratags=1`)
* `namedetails` - dictionary with full list of available names including ref etc.
```
<reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
- attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright"
+ attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
<result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY"
lat="48.9467562" lon="11.4038717"
The place information can be found in the `result` element. The attributes of that element contain:
- * `place_id` - reference to the Nominatim internal database ID
+ * `place_id` - reference to the Nominatim internal database ID (see notes below)
* `osm_type`, `osm_id` - reference to the OSM object
* `ref` - content of `ref` tag if it exists
* `lat`, `lon` - latitude and longitude of the centroid of the object
* `boundingbox` - comma-separated list of corner coordinates
-The full address address of the result can be found in the content of the
+The full address of the result can be found in the content of the
`result` element as a comma-separated list.
Additional information requested with `addressdetails=1`, `extratags=1` and
```
<searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
- attribution="Data © OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright"
+ attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
querystring="london" polygon="false" exclude_place_ids="100149"
more_url="https://nominatim.openstreetmap.org/search.php?q=london&addressdetails=1&extratags=1&exclude_place_ids=100149&format=xml&accept-language=en-US%2Cen%3Bq%3D0.7%2Cde%3Bq%3D0.3">
<place place_id="100149" osm_type="node" osm_id="107775" place_rank="15"
boundingbox="51.3473219,51.6673219,-0.2876474,0.0323526" lat="51.5073219" lon="-0.1276474"
- display_name="London, Greater London, England, SW1A 2DU, United Kingdom"
+ display_name="London, Greater London, England, SW1A 2DU, United Kingdom"
class="place" type="city" importance="0.9654895765402"
icon="https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png">
<extratags>
The place information can be found in the `place` elements, of which there may
be more than one. The attributes of that element contain:
- * `place_id` - reference to the Nominatim internal database ID
+ * `place_id` - reference to the Nominatim internal database ID (see notes below)
* `osm_type`, `osm_id` - reference to the OSM object
* `ref` - content of `ref` tag if it exists
* `lat`, `lon` - latitude and longitude of the centroid of the object
Additional information requested with `extratags=1` and `namedetails=1` can
be found in extra elements as sub-element of each place.
+
+## Notes on field values
+
+### place_id is not a persistent id
+
+The `place_id` is created when a Nominatim database gets installed. A
+single place will have a different value on another server or even when
+the same data gets re-imported. It's thus not useful to treat it as
+permanent for later use.
+
+The combination `osm_type`+`osm_id` is slighly better but remember in
+OpenStreetMap mappers can delete, split, recreate places (and those
+get a new `osm_id`), there is no link between those old and new ids.
+Places can also change their meaning without changing their `osm_id`,
+e.g. when a restaurant is retagged as supermarket. For a more in-depth
+discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID).
+
+Nominatim merges some places (e.g. center node of a city with the boundary
+relation) so `osm_type`+`osm_id`+`class_name` would be more unique.
+
+### boundingbox
+
+Comma separated list of min latitude, max latitude, min longitude, max longitude.
+The whole planet would be `-90,90,-180,180`.
projects / nominatim.git / blobdiff