From cc4bbec1147bdf50acb9d1e74ebb620bfc7ea757 Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Thu, 15 Mar 2018 17:32:11 -0400 Subject: [PATCH] A little work on the place documentation --- place.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/place.md b/place.md index 94d02c7..b284b1f 100644 --- a/place.md +++ b/place.md @@ -1,7 +1,9 @@ -# Search an ID to get details on a place +# `/v1/place` endpoint for details When you know an identification number and the source it came from, you can use Pelias to get details on the location. +For now, the `/place` endpoint returns exactly the same data that any other would. However, in the future, we plan to allow more information, perhaps [geometries](https://github.com/pelias/whosonfirst/issues/19#issuecomment-370545690) to be returned here. + The `/place` endpoint accepts Pelias `gid` strings that get returned for every exactly matched record in query responses. These `gid` strings should not be built manually, but rather used directly as-is to lookup additional details on the location that `gid` refers to. For example, this `/place` query looks up the Eiffel Tower in OpenStreetMap (OSM): @@ -18,10 +20,16 @@ To search for more than one `/place` in a request, join multiple values together The results are returned in the order requested. +### 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. If the structure of your `gid` is invalid, an error will be returned as part of the GeoJSON structure. 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: It is important to not use any `gid` values to attempt `/place` queries after longer than an hour. These IDs are not intended to be stable across builds, as datasets are used that do not have consistent 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.