Document nearby endpoint

[orangejulius]

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]

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 pelias/api#546

[abustamam]

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.