docs/api/Output.md

   1 # Place Output
   2
   3 The [/reverse](Reverse.md), [/search](Search.md) and [/lookup](Lookup.md)
   4 API calls produce very similar output which is explained in this section.
   5 There is one section for each format. The format correspond to what was
   6 selected via the `format` parameter.
   7
   8 ## JSON
   9
  10 The JSON format returns an array of places (for search and lookup) or
  11 a single place (for reverse) of the following format:
  12
  13 ```
  14   {
  15     "place_id": "100149",
  16     "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
  17     "osm_type": "node",
  18     "osm_id": "107775",
  19     "boundingbox": ["51.3473219", "51.6673219", "-0.2876474", "0.0323526"],
  20     "lat": "51.5073219",
  21     "lon": "-0.1276474",
  22     "display_name": "London, Greater London, England, SW1A 2DU, United Kingdom",
  23     "class": "place",
  24     "type": "city",
  25     "importance": 0.9654895765402,
  26     "icon": "https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png",
  27     "address": {
  28       "city": "London",
  29       "state_district": "Greater London",
  30       "state": "England",
  31       "postcode": "SW1A 2DU",
  32       "country": "United Kingdom",
  33       "country_code": "gb"
  34     },
  35     "extratags": {
  36       "capital": "yes",
  37       "website": "http://www.london.gov.uk",
  38       "wikidata": "Q84",
  39       "wikipedia": "en:London",
  40       "population": "8416535"
  41     }
  42   }
  43 ```
  44
  45 The possible fields are:
  46
  47  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
  48  * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
  49  * `boundingbox` - area of corner coordinates ([see notes](#boundingbox))
  50  * `lat`, `lon` - latitude and longitude of the centroid of the object
  51  * `display_name` - full comma-separated address
  52  * `class`, `type` - key and value of the main OSM tag
  53  * `importance` - computed importance rank
  54  * `icon` - link to class icon (if available)
  55  * `address` - dictionary of address details (only with `addressdetails=1`,
  56    [see notes](#addressdetails))
  57  * `extratags` - dictionary with additional useful tags like website or maxspeed
  58    (only with `extratags=1`)
  59  * `namedetails` - dictionary with full list of available names including ref etc.
  60  * `geojson`, `svg`, `geotext`, `geokml` - full geometry
  61    (only with the appropriate `polygon_*` parameter)
  62
  63 ## JSONv2
  64
  65 This is the same as the JSON format with two changes:
  66
  67  * `class` renamed to `category`
  68  * additional field `place_rank` with the search rank of the object
  69
  70 ## GeoJSON
  71
  72 This format follows the [RFC7946](https://geojson.org). Every feature includes
  73 a bounding box (`bbox`).
  74
  75 The properties object has the following fields:
  76
  77  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
  78  * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
  79  * `category`, `type` - key and value of the main OSM tag
  80  * `display_name` - full comma-separated address
  81  * `place_rank` - class search rank
  82  * `importance` - computed importance rank
  83  * `icon` - link to class icon (if available)
  84  * `address` - dictionary of address details (only with `addressdetails=1`,
  85    [see notes](#addressdetails))
  86  * `extratags` - dictionary with additional useful tags like `website` or `maxspeed`
  87    (only with `extratags=1`)
  88  * `namedetails` - dictionary with full list of available names including ref etc.
  89
  90 Use `polygon_geojson` to output the full geometry of the object instead
  91 of the centroid.
  92
  93 ## GeocodeJSON
  94
  95 The GeocodeJSON format follows the
  96 [GeocodeJSON spec 0.1.0](https://github.com/geocoders/geocodejson-spec).
  97 The following feature attributes are implemented:
  98
  99  * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension, [see notes](#osm-reference))
 100  * `type` - value of the main tag of the object (e.g. residential, restaurant, ...)
 101  * `label` - full comma-separated address
 102  * `name` - localised name of the place
 103  * `housenumber`, `street`, `locality`, `district`, `postcode`, `city`,
 104    `county`, `state`, `country` -
 105    provided when it can be determined from the address
 106  * `admin` - list of localised names of administrative boundaries (only with `addressdetails=1`)
 107
 108 Use `polygon_geojson` to output the full geometry of the object instead
 109 of the centroid.
 110
 111 ## XML
 112
 113 The XML response returns one or more place objects in slightly different
 114 formats depending on the API call.
 115
 116 ### Reverse
 117
 118 ```
 119 <reversegeocode timestamp="Sat, 11 Aug 18 11:53:21 +0000"
 120                 attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
 121                 querystring="lat=48.400381&lon=11.745876&zoom=5&format=xml">
 122   <result place_id="179509537" osm_type="relation" osm_id="2145268" ref="BY" place_rank="15" address_rank="15"
 123           lat="48.9467562" lon="11.4038717"
 124           boundingbox="47.2701114,50.5647142,8.9763497,13.8396373">
 125        Bavaria, Germany
 126   </result>
 127   <addressparts>
 128      <state>Bavaria</state>
 129      <country>Germany</country>
 130      <country_code>de</country_code>
 131   </addressparts>
 132   <extratags>
 133     <tag key="place" value="state"/>
 134     <tag key="wikidata" value="Q980"/>
 135     <tag key="wikipedia" value="de:Bayern"/>
 136     <tag key="population" value="12520000"/>
 137     <tag key="name:prefix" value="Freistaat"/>
 138   </extratags>
 139 </reversegeocode>
 140 ```
 141
 142 The attributes of the outer `reversegeocode` element return generic information
 143 about the query, including the time when the response was sent (in UTC),
 144 attribution to OSM and the original querystring.
 145
 146 The place information can be found in the `result` element. The attributes of that element contain:
 147
 148  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
 149  * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
 150  * `ref` - content of `ref` tag if it exists
 151  * `lat`, `lon` - latitude and longitude of the centroid of the object
 152  * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
 153
 154 The full address of the result can be found in the content of the
 155 `result` element as a comma-separated list.
 156
 157 Additional information requested with `addressdetails=1`, `extratags=1` and
 158 `namedetails=1` can be found in extra elements.
 159
 160 ### Search and Lookup
 161
 162 ```
 163 <searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
 164                attribution="Data © OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright"
 165                querystring="london" polygon="false" exclude_place_ids="100149"
 166                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">
 167   <place place_id="100149" osm_type="node" osm_id="107775" place_rank="15" address_rank="15"
 168          boundingbox="51.3473219,51.6673219,-0.2876474,0.0323526" lat="51.5073219" lon="-0.1276474"
 169          display_name="London, Greater London, England, SW1A 2DU, United Kingdom"
 170          class="place" type="city" importance="0.9654895765402"
 171          icon="https://nominatim.openstreetmap.org/images/mapicons/poi_place_city.p.20.png">
 172     <extratags>
 173       <tag key="capital" value="yes"/>
 174       <tag key="website" value="http://www.london.gov.uk"/>
 175       <tag key="wikidata" value="Q84"/>
 176       <tag key="wikipedia" value="en:London"/>
 177       <tag key="population" value="8416535"/>
 178     </extratags>
 179     <city>London</city>
 180     <state_district>Greater London</state_district>
 181     <state>England</state>
 182     <postcode>SW1A 2DU</postcode>
 183     <country>United Kingdom</country>
 184     <country_code>gb</country_code>
 185   </place>
 186 </searchresults>
 187 ```
 188
 189 The attributes of the outer `searchresults` or `lookupresults` element return
 190 generic information about the query:
 191
 192  * `timestamp` - UTC time when the response was sent
 193  * `attribution` - OSM licensing information
 194  * `querystring` - original query
 195  * `polygon` - true when extra geometry information was requested
 196  * `exclude_place_ids` - IDs of places that should be ignored in a follow-up request
 197  * `more_url` - search call that will yield additional results for the query
 198    just sent
 199
 200 The place information can be found in the `place` elements, of which there may
 201 be more than one. The attributes of that element contain:
 202
 203  * `place_id` - reference to the Nominatim internal database ID ([see notes](#place_id-is-not-a-persistent-id))
 204  * `osm_type`, `osm_id` - reference to the OSM object ([see notes](#osm-reference))
 205  * `ref` - content of `ref` tag if it exists
 206  * `lat`, `lon` - latitude and longitude of the centroid of the object
 207  * `boundingbox` - comma-separated list of corner coordinates ([see notes](#boundingbox))
 208  * `place_rank` - class [search rank](../develop/Ranking#search-rank)
 209  * `address_rank` - place [address rank](../develop/Ranking#address-rank)
 210  * `display_name` - full comma-separated address
 211  * `class`, `type` - key and value of the main OSM tag
 212  * `importance` - computed importance rank
 213  * `icon` - link to class icon (if available)
 214
 215 When `addressdetails=1` is requested, the localised address parts appear
 216 as subelements with the type of the address part.
 217
 218 Additional information requested with `extratags=1` and `namedetails=1` can
 219 be found in extra elements as sub-element of `extratags` and `namedetails`
 220 respectively.
 221
 222
 223 ## Notes on field values
 224
 225 ### place_id is not a persistent id
 226
 227 The `place_id` is an internal identifier that is assigned data is imported
 228 into a Nominatim database. The same OSM object will have a different value
 229 on another server. It may even change its ID on the same server when it is
 230 removed and reimported while updating the database with fresh OSM data.
 231 It is thus not useful to treat it as permanent for later use.
 232
 233 The combination `osm_type`+`osm_id` is slighly better but remember in
 234 OpenStreetMap mappers can delete, split, recreate places (and those
 235 get a new `osm_id`), there is no link between those old and new ids.
 236 Places can also change their meaning without changing their `osm_id`,
 237 e.g. when a restaurant is retagged as supermarket. For a more in-depth
 238 discussion see [Permanent ID](https://wiki.openstreetmap.org/wiki/Permanent_ID).
 239
 240 If you need an ID that is consistent over multiple installations of Nominatim,
 241 then you should use the combination of `osm_type`+`osm_id`+`class`.
 242
 243 ### OSM reference
 244
 245 Nominatim may sometimes return special objects that do not correspond directly
 246 to an object in OpenStreetMap. These are:
 247
 248 * **Postcodes**. Nominatim returns an postcode point created from all mapped
 249   postcodes of the same name. The class and type of these object is `place=postcdode`.
 250   No `osm_type` and `osm_id` are included in the result.
 251 * **Housenumber interpolations**. Nominatim returns a single interpolated
 252   housenumber from the interpolation way. The class and type are `place=house`
 253   and `osm_type` and `osm_id` correspond to the interpolation way in OSM.
 254 * **TIGER housenumber.** Nominatim returns a single interpolated housenumber
 255   from the TIGER data. The class and type are `place=house`
 256   and `osm_type` and `osm_id` correspond to the street mentioned in the result.
 257
 258 Please note that the `osm_type` and `osm_id` returned may be changed in the
 259 future. You should not expect to only find `node`, `way` and `relation` for
 260 the type.
 261
 262 ### boundingbox
 263
 264 Comma separated list of min latitude, max latitude, min longitude, max longitude.
 265 The whole planet would be `-90,90,-180,180`.
 266
 267 Can be used to pan and center the map on the result, for example with leafletjs
 268 mapping library
 269 `map.fitBounds([[bbox[0],bbox[2]],[bbox[1],bbox[3]]], {padding: [20, 20], maxzoom: 16});`
 270
 271 Bounds crossing the antimeridian have a min latitude -180 and max latitude 180,
 272 essentially covering the entire planet
 273 (see [issue 184](https://github.com/openstreetmap/Nominatim/issues/184)).
 274
 275 ### addressdetails
 276
 277 Address details in the xml and json formats return a list of names together
 278 with a designation label. Per default the following labels may appear:
 279
 280  * continent
 281  * country, country_code
 282  * region, state, state_district, county
 283  * municipality, city, town, village
 284  * city_district, district, borough, suburb, subdivision
 285  * hamlet, croft, isolated_dwelling
 286  * neighbourhood, allotments, quarter
 287  * city_block, residental, farm, farmyard, industrial, commercial, retail
 288  * road
 289  * house_number, house_name
 290  * emergency, historic, military, natural, landuse, place, railway,
 291    man_made, aerialway, boundary, amenity, aeroway, club, craft, leisure,
 292    office, mountain_pass, shop, tourism, bridge, tunnel, waterway
 293
 294 They roughly correspond to the classification of the OpenStreetMap data
 295 according to either the `place` tag or the main key of the object.