From 879f818d810d9418183f62fe2f991347aae78569 Mon Sep 17 00:00:00 2001 From: marc tobias Date: Mon, 9 Jul 2018 16:06:48 +0200 Subject: [PATCH] add geojson,geocodejson formats to API documentation --- docs/api/Lookup.md | 45 ++++++++++++++++++- docs/api/Reverse.md | 104 +++++++++++++++++++++++++++++++++++++++++++- docs/api/Search.md | 90 ++++++++++++++++++++++++++++++++++++-- 3 files changed, 231 insertions(+), 8 deletions(-) diff --git a/docs/api/Lookup.md b/docs/api/Lookup.md index 3b6472ad..21c0bab2 100644 --- a/docs/api/Lookup.md +++ b/docs/api/Lookup.md @@ -7,9 +7,10 @@ Lookup the address of one or multiple OSM objects like node, way or relation. https://nominatim.openstreetmap.org/lookup? ``` -* `format=[xml|json]` +* `format=[xml|json|geojson]` * Output format + * Defaults to `xml` * `json_callback=` @@ -41,7 +42,9 @@ Lookup the address of one or multiple OSM objects like node, way or relation. ### Example -* [https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189](https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189) +##### XML + +[https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189](https://nominatim.openstreetmap.org/lookup?osm_ids=R146656,W104393803,N240109189) ```xml @@ -73,3 +76,41 @@ Lookup the address of one or multiple OSM objects like node, way or relation. ``` + +##### JSON with extratags + +[https://nominatim.openstreetmap.org/lookup?osm_ids=W50637691&format=json](https://nominatim.openstreetmap.org/lookup?osm_ids=W50637691&format=json) + +```json +[ + { + "place_id": "84271358", + "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright", + "osm_type": "way", + "osm_id": "50637691", + "lat": "52.39955055", + "lon": "13.04806574678", + "display_name": "Brandenburger Tor, Brandenburger Straße, Nördliche Innenstadt, Innenstadt, Potsdam, Brandenburg, 14467, Germany", + "class": "historic", + "type": "city_gate", + "importance": "0.221233780277011", + "address": { + "address29": "Brandenburger Tor", + "pedestrian": "Brandenburger Straße", + "suburb": "Nördliche Innenstadt", + "city": "Potsdam", + "state": "Brandenburg", + "postcode": "14467", + "country": "Germany", + "country_code": "de" + }, + "extratags": { + "image": "http://commons.wikimedia.org/wiki/File:Potsdam_brandenburger_tor.jpg", + "wikidata": "Q695045", + "wikipedia": "de:Brandenburger Tor (Potsdam)", + "wheelchair": "yes", + "description": "Kleines Brandenburger Tor in Potsdam" + } + } +] +``` diff --git a/docs/api/Reverse.md b/docs/api/Reverse.md index 0c3c3d65..ee8c3ea5 100644 --- a/docs/api/Reverse.md +++ b/docs/api/Reverse.md @@ -7,9 +7,10 @@ Reverse geocoding generates an address from a latitude and longitude. The optio https://nominatim.openstreetmap.org/reverse? ``` -* `format=[xml|json|jsonv2]` +* `format=[xml|json|jsonv2|geojson|geocodejson]` - * Output format. + * Output format + * defaults to `xml` * `jsonv2` adds the next fields to response: * `place_rank` * `category` @@ -125,6 +126,105 @@ https://nominatim.openstreetmap.org/reverse? } ``` +##### Example with `format=geojson` + +* [https://nominatim.openstreetmap.org/reverse?format=geojson&lat=44.50155&lon=11.33989](https://nominatim.openstreetmap.org/reverse?format=geojson&lat=44.50155&lon=11.33989) + +```json +{ + "type": "FeatureCollection", + "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright", + "features": [ + { + "type": "Feature", + "properties": { + "place_id": "18512203", + "osm_type": "node", + "osm_id": "1704756187", + "place_rank": "30", + "category": "place", + "type": "house", + "importance": "0", + "addresstype": "place", + "name": null, + "display_name": "71, Via Guglielmo Marconi, Saragozza-Porto, Bologna, BO, Emilia-Romagna, 40122, Italy", + "address": { + "house_number": "71", + "road": "Via Guglielmo Marconi", + "suburb": "Saragozza-Porto", + "city": "Bologna", + "county": "BO", + "state": "Emilia-Romagna", + "postcode": "40122", + "country": "Italy", + "country_code": "it" + } + }, + "bbox": [ + 11.3397676, + 44.5014307, + 11.3399676, + 44.5016307 + ], + "geometry": { + "type": "Point", + "coordinates": [ + 11.3398676, + 44.5015307 + ] + } + } + ] +} +``` + +##### Example with `format=geocodejson` + +[https://nominatim.openstreetmap.org/reverse?format=geocodejson&lat=60.2299&lon=11.1663](https://nominatim.openstreetmap.org/reverse?format=geocodejson&lat=60.2299&lon=11.1663) + +```json +{ + "type": "FeatureCollection", + "geocoding": { + "version": "0.1.0", + "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright", + "licence": "ODbL", + "query": "60.229917843587,11.16630979382" + }, + "features": { + "type": "Feature", + "properties": { + "geocoding": { + "place_id": "42700574", + "osm_type": "node", + "osm_id": "3110596255", + "type": "house", + "accuracy": 0, + "label": "1, Løvenbergvegen, Mogreina, Ullensaker, Akershus, 2054, Norway", + "name": null, + "housenumber": "1", + "street": "Løvenbergvegen", + "postcode": "2054", + "county": "Akershus", + "country": "Norway", + "admin": { + "level7": "Ullensaker", + "level4": "Akershus", + "level2": "Norway" + } + } + }, + "geometry": { + "type": "Point", + "coordinates": [ + 11.1658572, + 60.2301296 + ] + } + } +} +``` + ### Hierarchy * Admin level => XML entity diff --git a/docs/api/Search.md b/docs/api/Search.md index 17e74587..e2c55fa5 100644 --- a/docs/api/Search.md +++ b/docs/api/Search.md @@ -20,7 +20,7 @@ Various keywords are translated into searches for specific osm tags (e.g. Pub => https://nominatim.openstreetmap.org/search/? ``` -* `format=[html|xml|json|jsonv2]` +* `format=[html|xml|json|jsonv2|geojson|geocodejson]` * Output format * defaults to `html` @@ -121,9 +121,12 @@ Structured requests are faster and require fewer server resources. **Do not comb ### Examples + +##### XML with polygon points + * [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) +* [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) ```xml @@ -147,7 +150,9 @@ Structured requests are faster and require fewer server resources. **Do not comb ``` -* [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 with SVG polygon + +[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 { @@ -185,7 +190,9 @@ Structured requests are faster and require fewer server resources. **Do not comb } ``` -* [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 with address details + +[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 { @@ -220,3 +227,78 @@ Structured requests are faster and require fewer server resources. **Do not comb "type": "bakery" } ``` + +##### GeoJSON + +[https://nominatim.openstreetmap.org/search?q=17+Strada+Pictor+Alexandru+Romano%2C+Bukarest&format=geojson](https://nominatim.openstreetmap.org/search?q=17+Strada+Pictor+Alexandru+Romano%2C+Bukarest&format=geojson) + +```json +{ + "type": "FeatureCollection", + "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright", + "features": [ + { + "type": "Feature", + "properties": { + "place_id": "35811445", + "osm_type": "node", + "osm_id": "2846295644", + "display_name": "17, Strada Pictor Alexandru Romano, Bukarest, Bucharest, Sector 2, Bucharest, 023964, Romania", + "place_rank": "30", + "category": "place", + "type": "house", + "importance": 0.62025 + }, + "bbox": [ + 26.1156689, + 44.4354754, + 26.1157689, + 44.4355754 + ], + "geometry": { + "type": "Point", + "coordinates": [ + 26.1157189, + 44.4355254 + ] + } + } + ] +} +``` + +##### GeocodeJSON + +[https://nominatim.openstreetmap.org/search?q=%CE%91%CE%B3%CE%AF%CE%B1+%CE%A4%CF%81%CE%B9%CE%AC%CE%B4%CE%B1%2C+%CE%91%CE%B4%CF%89%CE%BD%CE%B9%CE%B4%CE%BF%CF%82%2C+Athens%2C+Greece&format=geocodejson](https://nominatim.openstreetmap.org/search?q=%CE%91%CE%B3%CE%AF%CE%B1+%CE%A4%CF%81%CE%B9%CE%AC%CE%B4%CE%B1%2C+%CE%91%CE%B4%CF%89%CE%BD%CE%B9%CE%B4%CE%BF%CF%82%2C+Athens%2C+Greece&format=geocodejson) + +```json +{ + "type": "FeatureCollection", + "geocoding": { + "version": "0.1.0", + "attribution": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright", + "licence": "ODbL", + "query": "Αγία Τριάδα, Αδωνιδος, Athens, Greece" + }, + "features": [ + { + "type": "Feature", + "properties": { + "geocoding": { + "type": "place_of_worship", + "label": "Αγία Τριάδα, Αδωνιδος, Άγιος Νικόλαος, 5º Δημοτικό Διαμέρισμα Αθηνών, Athens, Municipality of Athens, Regional Unit of Central Athens, Region of Attica, Attica, 11472, Greece", + "name": "Αγία Τριάδα", + "admin": null + } + }, + "geometry": { + "type": "Point", + "coordinates": [ + 23.72949633941, + 38.0051697 + ] + } + } + ] +} +``` \ No newline at end of file -- 2.39.5