Merge pull request #1822 from lonvia/document-address-labels

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

diff --git a/docs/api/Search.md b/docs/api/Search.md
index ace6cc8de7df34571c334bd0d396f611703c17d3..c18655dcc03f570b866af1d94ed5d049423db633 100644 (file)
--- a/docs/api/Search.md
+++ b/docs/api/Search.md
@@ -92,8 +92,12 @@ comma-separated list of language codes.
 * `countrycodes=<countrycode>[,<countrycode>][,<countrycode>]...`
 
 Limit search results to one or more countries. `<countrycode>` must be the
 * `countrycodes=<countrycode>[,<countrycode>][,<countrycode>]...`
 
 Limit search results to one or more countries. `<countrycode>` must be the

-ISO 3166-1alpha2 code, e.g. `gb` for the United Kingdom, `de` for Germany.
+[ISO 3166-1alpha2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code,
+e.g. `gb` for the United Kingdom, `de` for Germany.

 
 

+Each place in Nominatim is assigned to one country code based
+on `admin_level=2` tags, in rare cases to none (for example in
+international waters outside any country).

 
 * `exclude_place_ids=<place_id,[place_id],[place_id]`
 
 
 * `exclude_place_ids=<place_id,[place_id],[place_id]`
 


@@ -168,21 +172,27 @@ This overrides the specified machine readable format. (Default: 0)
 ## Examples
 
 
 ## Examples
 
 

-##### XML with polygon points
+##### XML with kml polygon

 
 

-* [https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon=1&addressdetails=1](https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon=1&addressdetails=1)
-* [https://nominatim.openstreetmap.org/search/gb/birmingham/pilkington%20avenue/135?format=xml&polygon=1&addressdetails=1](https://nominatim.openstreetmap.org/search/gb/birmingham/pilkington%20avenue/135?format=xml&polygon=1&addressdetails=1)
-* [https://nominatim.openstreetmap.org/search/135%20pilkington%20avenue,%20birmingham?format=xml&polygon=1&addressdetails=1](https://nominatim.openstreetmap.org/search/135%20pilkington%20avenue,%20birmingham?format=xml&polygon=1&addressdetails=1)
+* [https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon_geojson=1&addressdetails=1](https://nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham&format=xml&polygon_geojson=1&addressdetails=1)

 
 ```xml
   <searchresults timestamp="Sat, 07 Nov 09 14:42:10 +0000" querystring="135 pilkington, avenue birmingham" polygon="true">
     <place
       place_id="1620612" osm_type="node" osm_id="452010817"
       boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224"
 
 ```xml
   <searchresults timestamp="Sat, 07 Nov 09 14:42:10 +0000" querystring="135 pilkington, avenue birmingham" polygon="true">
     <place
       place_id="1620612" osm_type="node" osm_id="452010817"
       boundingbox="52.548641204834,52.5488433837891,-1.81612110137939,-1.81592094898224"

-      polygonpoints="[['-1.81592098644987','52.5487429714954'],['-1.81592290792183','52.5487234624632'],...]"

       lat="52.5487429714954" lon="-1.81602098644987"
       display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
       class="place" type="house">
       lat="52.5487429714954" lon="-1.81602098644987"
       display_name="135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom"
       class="place" type="house">

+      <geokml>
+        <Polygon>
+          <outerBoundaryIs>
+            <LinearRing>
+              <coordinates>-1.816513,52.548756599999997 -1.816434,52.548747300000002 -1.816429,52.5487629 -1.8163717,52.548756099999999 -1.8163464,52.548834599999999 -1.8164599,52.548848100000001 -1.8164685,52.5488213 -1.8164913,52.548824000000003 -1.816513,52.548756599999997</coordinates>
+            </LinearRing>
+          </outerBoundaryIs>
+        </Polygon>
+      </geokml>

       <house_number>135</house_number>
       <road>Pilkington Avenue</road>
       <village>Wylde Green</village>
       <house_number>135</house_number>
       <road>Pilkington Avenue</road>
       <village>Wylde Green</village>