add documentation for new extra field

[nominatim.git] / docs / api / Output.md

diff --git a/docs/api/Output.md b/docs/api/Output.md
index 3c541d33afe18c51c09bf88ac9b54e78431b3210..a5ec933e0fdabb172c9a198e994bed890aab3f88 100644 (file)
--- a/docs/api/Output.md
+++ b/docs/api/Output.md
@@ -12,7 +12,7 @@ a single place (for reverse) of the following format:
 
 ```
   {
 
 ```
   {

-    "place_id": "100149",
+    "place_id": 100149,

     "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
     "osm_type": "node",
     "osm_id": "107775",
     "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
     "osm_type": "node",
     "osm_id": "107775",


@@ -28,7 +28,7 @@ a single place (for reverse) of the following format:
       "city": "London",
       "state_district": "Greater London",
       "state": "England",
       "city": "London",
       "state_district": "Greater London",
       "state": "England",

-      "state_code": "ENG",
+      "ISO3166-2-lvl4": "GB-ENG",

       "postcode": "SW1A 2DU",
       "country": "United Kingdom",
       "country_code": "gb"
       "postcode": "SW1A 2DU",
       "country": "United Kingdom",
       "country_code": "gb"


@@ -98,13 +98,19 @@ The GeocodeJSON format follows the
 The following feature attributes are implemented:
 
  * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension, [see notes](#osm-reference))
 The following feature attributes are implemented:
 
  * `osm_type`, `osm_id` - reference to the OSM object (unofficial extension, [see notes](#osm-reference))

- * `type` - value of the main tag of the object (e.g. residential, restaurant, ...)
+ * `type` - the 'address level' of the object ('house', 'street', `district`, `city`,
+            `county`, `state`, `country`, `locality`)
+ * `osm_key`- key of the main tag of the OSM object (e.g. boundary, highway, amenity)
+ * `osm_value` - value of the main tag of the OSM object (e.g. residential, restaurant)

  * `label` - full comma-separated address
  * `name` - localised name of the place
  * `housenumber`, `street`, `locality`, `district`, `postcode`, `city`,
    `county`, `state`, `country` -
  * `label` - full comma-separated address
  * `name` - localised name of the place
  * `housenumber`, `street`, `locality`, `district`, `postcode`, `city`,
    `county`, `state`, `country` -

-   provided when it can be determined from the address
+   provided when it can be determined from the address (only with `addressdetails=1`)

  * `admin` - list of localised names of administrative boundaries (only with `addressdetails=1`)
  * `admin` - list of localised names of administrative boundaries (only with `addressdetails=1`)

+ * `extra` - dictionary with additional useful tags like `website` or `maxspeed`
+   (only with `extratags=1`)
+

 
 Use `polygon_geojson` to output the full geometry of the object instead
 of the centroid.
 
 Use `polygon_geojson` to output the full geometry of the object instead
 of the centroid.


@@ -127,7 +133,7 @@ formats depending on the API call.
   </result>
   <addressparts>
      <state>Bavaria</state>
   </result>
   <addressparts>
      <state>Bavaria</state>

-     <state_code>BY</state_code>
+     <ISO3166-2-lvl4>DE-BY</ISO3166-2-lvl4>

      <country>Germany</country>
      <country_code>de</country_code>
   </addressparts>
      <country>Germany</country>
      <country_code>de</country_code>
   </addressparts>


@@ -165,7 +171,7 @@ 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. https://www.openstreetmap.org/copyright"
                querystring="london" polygon="false" exclude_place_ids="100149"
 <searchresults timestamp="Sat, 11 Aug 18 11:55:35 +0000"
                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">
+               more_url="https://nominatim.openstreetmap.org/search?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" address_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"
   <place place_id="100149" osm_type="node" osm_id="107775" place_rank="15" address_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"


@@ -181,7 +187,7 @@ Additional information requested with `addressdetails=1`, `extratags=1` and
     <city>London</city>
     <state_district>Greater London</state_district>
     <state>England</state>
     <city>London</city>
     <state_district>Greater London</state_district>
     <state>England</state>

-    <state_code>ENG</state_code>
+    <ISO3166-2-lvl4>GB-ENG</ISO3166-2-lvl4>

     <postcode>SW1A 2DU</postcode>
     <country>United Kingdom</country>
     <country_code>gb</country_code>
     <postcode>SW1A 2DU</postcode>
     <country>United Kingdom</country>
     <country_code>gb</country_code>


@@ -208,8 +214,8 @@ be more than one. The attributes of that element contain:
  * `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 ([see notes](#boundingbox))
  * `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 ([see notes](#boundingbox))

- * `place_rank` - class [search rank](../develop/Ranking#search-rank)
- * `address_rank` - place [address rank](../develop/Ranking#address-rank)
+ * `place_rank` - class [search rank](../customize/Ranking.md#search-rank)
+ * `address_rank` - place [address rank](../customize/Ranking.md#address-rank)

  * `display_name` - full comma-separated address
  * `class`, `type` - key and value of the main OSM tag
  * `importance` - computed importance rank
  * `display_name` - full comma-separated address
  * `class`, `type` - key and value of the main OSM tag
  * `importance` - computed importance rank


@@ -233,7 +239,7 @@ on another server. It may even change its ID on the same server when it is
 removed and reimported while updating the database with fresh OSM data.
 It is thus not useful to treat it as permanent for later use.
 
 removed and reimported while updating the database with fresh OSM data.
 It is thus not useful to treat it as permanent for later use.
 

-The combination `osm_type`+`osm_id` is slighly better but remember in
+The combination `osm_type`+`osm_id` is slightly 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`,
 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`,


@@ -282,12 +288,12 @@ with a designation label. Per default the following labels may appear:
 
  * continent
  * country, country_code
 
  * continent
  * country, country_code

- * region, state, state_code, state_district, county
+ * region, state, state_district, county, ISO3166-2-lvl<admin_level>

  * municipality, city, town, village
  * city_district, district, borough, suburb, subdivision
  * hamlet, croft, isolated_dwelling
  * neighbourhood, allotments, quarter
  * municipality, city, town, village
  * city_district, district, borough, suburb, subdivision
  * hamlet, croft, isolated_dwelling
  * neighbourhood, allotments, quarter

- * city_block, residental, farm, farmyard, industrial, commercial, retail
+ * city_block, residential, farm, farmyard, industrial, commercial, retail

  * road
  * house_number, house_name
  * emergency, historic, military, natural, landuse, place, railway,
  * road
  * house_number, house_name
  * emergency, historic, military, natural, landuse, place, railway,