From bbe7859fc3b44f853657b8c2a0404a096ac54e05 Mon Sep 17 00:00:00 2001 From: Joxit Date: Thu, 28 Nov 2019 11:49:34 +0100 Subject: [PATCH 1/2] Add categories section for place endpoint --- autocomplete.md | 2 +- place.md | 17 +++++++++++++++-- search.md | 2 +- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/autocomplete.md b/autocomplete.md index 5dad130..54fd8ce 100644 --- a/autocomplete.md +++ b/autocomplete.md @@ -219,6 +219,6 @@ Sometimes your work might require that all the search results be from a particul | `boundary.circle.radius` | floating point number | no | 50 | `35` | | `sources` | string | no | all sources: osm,oa,gn,wof | openstreetmap,wof | | `layers` | string | no | all layers: address,venue,neighbourhood,locality,borough,localadmin,county,macrocounty,region,macroregion,country,coarse,postalcode | address,venue | -| `boundary.country` | string | no | none | 'GBR,FRA' | +| `boundary.country` | string | no | none | `GBR,FRA` | | `boundary.gid` | Pelias `gid` | no | none | `whosonfirst:locality:101748355` | | `size` | integer | no | 10 | 20 | diff --git a/place.md b/place.md index dbb8dbf..186d4d8 100644 --- a/place.md +++ b/place.md @@ -20,7 +20,13 @@ To search for more than one `/place` in a request, join multiple values together The results are returned in the order requested. -### Error handling +## Gets the categories in responses + +You can get some metadata from places such as categories. Categories let you know how to classify an element. For example the `Château de Versailles` (`Palace of Versailles`) in OpenStreetMap is classified as `entertainment`. + +> [/v1/place?__categories&ids=openstreetmap:venue:relation/1149002__](https://pelias.github.io/compare/#/v1/place%3Fcategories&ids=openstreetmap:venue:relation/1149002) + +## Error handling If you enter a valid `gid` that cannot be found or has "expired" due to a newer build, you may get empty results. The request will NOT return an error. @@ -28,8 +34,15 @@ If the structure of your `gid` is invalid, an error will be returned as part of Keep in mind that if you enter a `gid` that cannot be found in a list of multiple IDs, then the `features` array in the response contains a different number of elements than the number of requests. For example, your request may have three IDs requested but only two results returned. The reason for this is that the `features` section of the response is GeoJSON-compliant, and JSON does not allow a way to convey an exception condition (not even an empty JSON element, `{}`). For this reason, if your application is dependent upon the results mapping directly to the individual input requests in order, then you'll have to do your own bookkeeping to handle exception conditions. -### :warning: Datasets without stable IDs +## :warning: Datasets without stable IDs Due to the ever-changing nature of most open-datasets used by Pelias, some `gids` can change merely by importing newer data. Both Geonames and Who's on First have excellent, stable IDs and should not cause trouble. However, OpenAddresses and OpenStreetMap do _not_ have stable IDs. Be careful. + +## Available places parameters + +| Parameter | Type | Required | Default | Example | +| --- | --- | --- | --- | --- | +| `gid` | string | yes | none | `whosonfirst:borough:421205771` | +| `categories` | none | no | none | Check only if the query parameter is present | diff --git a/search.md b/search.md index f1ab42e..6530e8f 100644 --- a/search.md +++ b/search.md @@ -386,5 +386,5 @@ Here's a list of the types of places you could find in the results, sorted by gr | `boundary.gid` | Pelias `gid` | no | none | `whosonfirst:locality:101748355` | | `sources` | string | no | all sources: osm,oa,gn,wof | openstreetmap,wof | | `layers` | string | no | all layers: address,venue,neighbourhood,locality,borough,localadmin,county,macrocounty,region,macroregion,country,coarse,postalcode | address,venue | -| `boundary.country` | string | no | none | 'GBR,FRA' | +| `boundary.country` | string | no | none | `GBR,FRA` | | `size` | integer | no | 10 | 20 | From 7573a60cc67c81b8699edbe1531310c154a669e7 Mon Sep 17 00:00:00 2001 From: missinglink Date: Thu, 21 Jan 2021 12:48:19 +1300 Subject: [PATCH 2/2] reword title --- place.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/place.md b/place.md index 186d4d8..1ffdd2a 100644 --- a/place.md +++ b/place.md @@ -20,7 +20,7 @@ To search for more than one `/place` in a request, join multiple values together The results are returned in the order requested. -## Gets the categories in responses +## Return categories in responses You can get some metadata from places such as categories. Categories let you know how to classify an element. For example the `Château de Versailles` (`Palace of Versailles`) in OpenStreetMap is classified as `entertainment`.