search

pelias / documentation

All things documentation for Pelias
Creative Commons Attribution 4.0 International
227 stars 99 forks source link

Document nearby endpoint #227

Open orangejulius opened 6 years ago

orangejulius commented 6 years ago

The nearby endpoint is mysterious and undocumented. It is definitely in an alpha state, but should still be documented as such.

One problem is that I cannot find much in the way of a design document or even the original PR which added the nearby endpoint.

We may have to reverse engineer the functionality from the acceptance tests

orangejulius commented 6 years ago

Update: the original design document for the nearby endpoint lives here: https://github.com/pelias/pelias/wiki/Proposal:-Categories-Filter#nearby

The pull request where most of the original work was done is https://github.com/pelias/api/pull/546

abustamam commented 6 years ago

Will /nearby replace /reverse?

After reading through the PR, namely the sanitizer test, it seems like it also supports the following:

{ 
  'point.lat': 0,
  'point.lon': 0,
  'boundary.circle.lat': 0,
  'boundary.circle.lon': 0,
  'boundary.circle.radius': 0,
  size: 10
}

Additionally, categories does not appear to be well-documented, even in that design document. The pelias-categories repo from which we check for valid categories seems to just have a stubbed true function.

I've been using the /nearby endpoint in one of my apps so let me know if you need help documenting use cases.