diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index d2fe03d0..f335060f 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -9,6 +9,7 @@ file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/appendix) ADD_CUSTOM_TARGET(doc COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/admin ${CMAKE_CURRENT_BINARY_DIR}/admin COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/develop ${CMAKE_CURRENT_BINARY_DIR}/develop + COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/api ${CMAKE_CURRENT_BINARY_DIR}/api COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/index.md ${CMAKE_CURRENT_BINARY_DIR}/index.md COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/bash2md.sh ${PROJECT_SOURCE_DIR}/vagrant/Install-on-Centos-7.sh ${CMAKE_CURRENT_BINARY_DIR}/appendix/Install-on-Centos-7.md COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/bash2md.sh ${PROJECT_SOURCE_DIR}/vagrant/Install-on-Ubuntu-16.sh ${CMAKE_CURRENT_BINARY_DIR}/appendix/Install-on-Ubuntu-16.md diff --git a/docs/api/Lookup.md b/docs/api/Lookup.md new file mode 100644 index 00000000..3b6472ad --- /dev/null +++ b/docs/api/Lookup.md @@ -0,0 +1,75 @@ +## Address lookup + +Lookup the address of one or multiple OSM objects like node, way or relation. + +### Parameters +``` + https://nominatim.openstreetmap.org/lookup? +``` + +* `format=[xml|json]` + + * Output format + +* `json_callback=` + + * Wrap json output in a callback function (JSONP) i.e. `()` + +* `accept-language=` + + * Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header. + * Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes. + +* `osm_ids=[N|W|R],…,[N|W|R]` + + * If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string. + * This information will be kept confidential and only used to contact you in the event of a problem, see [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details. + +* `extratags=1` + * Include additional information in the result if available, e.g. wikipedia link, opening hours. + +* `namedetails=1` + * Include a list of alternative names in the results. + * These may include language variants, references, operator and brand. + +### Example + +* [https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189](https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189) + +```xml + + + Manchester + Greater Manchester + North West England + England + United Kingdom + gb + + + Brandenburg Gate + 1 + Pariser Platz + Mitte + Mitte + Berlin + Berlin + 10117 + Germany + de + + + Berlin + Berlin + Germany + de + + +``` diff --git a/docs/api/Reverse.md b/docs/api/Reverse.md new file mode 100644 index 00000000..999827a1 --- /dev/null +++ b/docs/api/Reverse.md @@ -0,0 +1,132 @@ +## Reverse Geocoding + +Reverse geocoding generates an address from a latitude and longitude. The optional `zoom` parameter specifies the level of detail required in terms of something suitable for a Leaflet.js/OpenLayers/etc. zoom level. + +### Parameters +``` +https://nominatim.openstreetmap.org/reverse? +``` + +* `format=[xml|json|jsonv2]` + + * Output format. + * `jsonv2` adds the next fields to response: + * `place_rank` + * `category` + * `type` + * `importance` + * `addresstype` + +* `json_callback=` + + * Wrap json output in a callback function (JSONP) i.e. `()` + +* `accept-language=` + + * Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header. + * Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes. + +* `osm_type=[N|W|R]` `osm_id=` + * A specific osm node / way / relation to return an address for + * **Please use this in preference to lat/lon where possible** + +* `lat=` `lon=` + * The location to generate an address for + +* `zoom=[0-18]` + * Level of detail required where `0` is country and `18` is house/building + +* `addressdetails=[0|1]` + * defaults to 0 + * Include a breakdown of the address into elements + +* `email=` + + * If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string. + * This information will be kept confidential and only used to contact you in the event of a problem, see [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details. + +* `polygon_geojson=1` + * Output geometry of results in geojson format. + +* `polygon_kml=1` + * Output geometry of results in kml format. + +* `polygon_svg=1` + * Output geometry of results in svg format. + +* `polygon_text=1` + * Output geometry of results as a WKT. + +* `extratags=1` + * Include additional information in the result if available, e.g. wikipedia link, opening hours. + +* `namedetails=1` + * Include a list of alternative names in the results. + * These may include language variants, references, operator and brand. + +### Example + +* [https://nominatim.openstreetmap.org/reverse?format=xml&lat=52.5487429714954&lon=-1.81602098644987&zoom=18&addressdetails=1](https://nominatim.openstreetmap.org/reverse?format=xml&lat=52.5487429714954&lon=-1.81602098644987&zoom=18&addressdetails=1) + +```xml + + + 135, Pilkington Avenue, Wylde Green, City of Birmingham, West Midlands (county), B72, United Kingdom + + + 135 + Pilkington Avenue + Wylde Green + Sutton Coldfield + City of Birmingham + West Midlands (county) + B72 + United Kingdom + gb + + +``` + +##### Example with `format=jsonv2` + +* [https://nominatim.openstreetmap.org/reverse?format=jsonv2&lat=-34.44076&lon=-58.70521](https://nominatim.openstreetmap.org/reverse?format=jsonv2&lat=-34.44076&lon=-58.70521) + +```json +{ + "place_id":"134140761", + "licence":"Data © OpenStreetMap contributors, ODbL 1.0. http:\/\/www.openstreetmap.org\/copyright", + "osm_type":"way", + "osm_id":"280940520", +"lat":"-34.4391708", + "lon":"-58.7064573", + "place_rank":"26", + "category":"highway", + "type":"motorway", + "importance":"0.1", + "addresstype":"road", + "display_name":"Autopista Pedro Eugenio Aramburu, El Triángulo, Partido de Malvinas Argentinas, Buenos Aires, 1.619, Argentina", + "name":"Autopista Pedro Eugenio Aramburu", + "address":{ + "road":"Autopista Pedro Eugenio Aramburu", + "village":"El Triángulo", + "state_district":"Partido de Malvinas Argentinas", + "state":"Buenos Aires", + "postcode":"1.619", + "country":"Argentina", + "country_code":"ar" + }, + "boundingbox":["-34.44159","-34.4370994","-58.7086067","-58.7044712"] +} +``` + +### Hierarchy + +* Admin level => XML entity + * 2 => `` + * 4 => `` + * 5 => `` + * 6 + * 7 => `` + * 8 => `` + * 9 => `` + * 10 => `` diff --git a/docs/api/Search.md b/docs/api/Search.md new file mode 100644 index 00000000..e166abaf --- /dev/null +++ b/docs/api/Search.md @@ -0,0 +1,216 @@ + +## Search +Nominatim indexes named (or numbered) features with the OSM data set and a subset of other unnamed features (pubs, hotels, churches, etc) + +Search terms are processed first left to right and then right to left if that fails. + +Both searches will work: [pilkington avenue, birmingham](//nominatim.openstreetmap.org/search?q=pilkington+avenue,birmingham), [birmingham, pilkington avenue](//nominatim.openstreetmap.org/search?q=birmingham,+pilkington+avenue) + +(Commas are optional, but improve performance by reducing the complexity of the search.) + +Where house numbers have been defined for an area they should be used: [135 pilkington avenue, birmingham](//nominatim.openstreetmap.org/search?q=135+pilkington+avenue,+birmingham) + +### Special Keywords +Various keywords are translated into searches for specific osm tags (e.g. Pub => amenity=pub). A current list of [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases) processed is available. + +### Parameters + +``` + https://nominatim.openstreetmap.org/search? + https://nominatim.openstreetmap.org/search/? +``` + +* `format=[html|xml|json|jsonv2]` + + * Output format + * defaults to `html` + + +* `json_callback=` + + * Wrap json output in a callback function (JSONP) i.e. `()` + +* `accept-language=` + + * Preferred language order for showing search results, overrides the value specified in the "Accept-Language" HTTP header. + * Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes. + +* `q=` + + * Query string to search for. + * Alternatively can be entered as: + + * `street= ` + * `city=` + * `county=` + * `state=` + * `country=` + * `postalcode=` + + **(experimental)** Alternative query string format for structured requests. +Structured requests are faster and require fewer server resources. **Do not combine with `q=` parameter**. + +* `countrycodes=[,][,]...` + + * Limit search results to a specific country (or a list of countries). + * `` should be the ISO 3166-1alpha2 code, e.g. `gb` for the United Kingdom, `de` for Germany, etc. + +* `viewbox=,,,` + * The preferred area to find search results. Any two corner points of the box are accepted in any order as long as they span a real box. + +* `bounded=[0|1]` + * defaults to 0 + * Restrict the results to only items contained with the viewbox (see above). + * Restricting the results to the bounding box also enables searching by amenity only. + * For example a search query of just `"[pub]"` would normally be rejected but with `bounded=1` will result in a list of items matching within the bounding box. + +* `polygon=[0|1]` + * defaults to 0 + * Output polygon outlines for items found **(deprecated, use one of the polygon_* parameters instead)** + +* `addressdetails=[0|1]` + * defaults to 0 + * Include a breakdown of the address into elements + +* `email=` + + * If you are making large numbers of request please include a valid email address or alternatively include your email address as part of the User-Agent string. + * This information will be kept confidential and only used to contact you in the event of a problem, see [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details. + +* `exclude_place_ids=` + * defaults to 10 + * Limit the number of returned results. + +* `dedupe=[0|1]` + * defaults to 1 + * Sometimes you have several objects in OSM identifying the same place or object in reality. The simplest case is a street being split in many different OSM ways due to different characteristics. + * Nominatim will attempt to detect such duplicates and only return one match; this is controlled by the dedupe parameter which defaults to 1. Since the limit is, for reasons of efficiency, enforced before and not after de-duplicating, it is possible that de-duplicating leaves you with less results than requested. + +* `debug=[0|1]` + * defaults to 0 + * Output assorted developer debug information. Data on internals of nominatim "Search Loop" logic, and SQL queries. The output is (rough) HTML format. This overrides the specified machine readable format. + +* `polygon_geojson=1` + * Output geometry of results in geojson format. + +* `polygon_kml=1` + * Output geometry of results in kml format. + +* `polygon_svg=1` + * Output geometry of results in svg format. + +* `polygon_text=1` + * Output geometry of results as a WKT. + +* `extratags=1` + * Include additional information in the result if available, e.g. wikipedia link, opening hours. + +* `namedetails=1` + * Include a list of alternative names in the results. + * These may include language variants, references, operator and brand. + +### Examples + +* [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/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/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) + +```xml + + + 135 + Pilkington Avenue + Wylde Green + Sutton Coldfield + City of Birmingham + West Midlands (county) + B72 + United Kingdom + gb + + +``` + +* [https://nominatim.openstreetmap.org/search/Unter%20den%20Linden%201%20Berlin?format=json&addressdetails=1&limit=1&polygon_svg=1](https://nominatim.openstreetmap.org/search/Unter%20den%20Linden%201%20Berlin?format=json&addressdetails=1&limit=1&polygon_svg=1) + +```json + { + "address": { + "city": "Berlin", + "city_district": "Mitte", + "construction": "Unter den Linden", + "continent": "European Union", + "country": "Deutschland", + "country_code": "de", + "house_number": "1", + "neighbourhood": "Scheunenviertel", + "postcode": "10117", + "public_building": "Kommandantenhaus", + "state": "Berlin", + "suburb": "Mitte" + }, + "boundingbox": [ + "52.5170783996582", + "52.5173187255859", + "13.3975105285645", + "13.3981599807739" + ], + "class": "amenity", + "display_name": "Kommandantenhaus, 1, Unter den Linden, Scheunenviertel, Mitte, Berlin, 10117, Deutschland, European Union", + "importance": 0.73606775332943, + "lat": "52.51719785", + "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright", + "lon": "13.3978352028938", + "osm_id": "15976890", + "osm_type": "way", + "place_id": "30848715", + "svg": "M 13.397511 -52.517283599999999 L 13.397829400000001 -52.517299800000004 13.398131599999999 -52.517315099999998 13.398159400000001 -52.517112099999999 13.3975388 -52.517080700000001 Z", + "type": "public_building" + } +``` + +* [https://nominatim.openstreetmap.org/?format=json&addressdetails=1&q=bakery+in+berlin+wedding&format=json&limit=1](https://nominatim.openstreetmap.org/?format=json&addressdetails=1&q=bakery+in+berlin+wedding&format=json&limit=1) + +```json + { + "address": { + "bakery": "B\u00e4cker Kamps", + "city_district": "Mitte", + "continent": "European Union", + "country": "Deutschland", + "country_code": "de", + "footway": "Bahnsteig U6", + "neighbourhood": "Sprengelkiez", + "postcode": "13353", + "state": "Berlin", + "suburb": "Wedding" + }, + "boundingbox": [ + "52.5460929870605", + "52.5460968017578", + "13.3591794967651", + "13.3591804504395" + ], + "class": "shop", + "display_name": "B\u00e4cker Kamps, Bahnsteig U6, Sprengelkiez, Wedding, Mitte, Berlin, 13353, Deutschland, European Union", + "icon": "https://nominatim.openstreetmap.org/images/mapicons/shopping_bakery.p.20.png", + "importance": 0.201, + "lat": "52.5460941", + "licence": "Data \u00a9 OpenStreetMap contributors, ODbL 1.0. https://www.openstreetmap.org/copyright", + "lon": "13.35918", + "osm_id": "317179427", + "osm_type": "node", + "place_id": "1453068", + "type": "bakery" + } +``` \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b0aee5d0..b2ff881c 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -5,6 +5,10 @@ site_url: http://nominatim.org repo_url: https://github.com/openstreetmap/Nominatim pages: - 'Introduction' : 'index.md' + - 'API Reference': + - 'Search': 'api/Search.md' + - 'Reverse': 'api/Reverse.md' + - 'Address Lookup': 'api/Lookup.md' - 'Administration Guide': - 'Basic Installation': 'admin/Installation.md' - 'Importing and Updating' : 'admin/Import-and-Update.md'