Add detail to query params for providers

[asadowns]

For trips and status_changes break query params
out into their own section.

Add more detail around how to specify time
and location based parameters.

For location this is just a suggestion.

There may be url length concerns when passing in large polygons
in query params.

A better approach might be to pass in service_area id or
use a location filter based on the token and
filter data further after retrieval

Comments welcome.

[hunterowens]

@asadowns any thoughts on a POST based implementation? It was raised as an issue in #78

[oderby]

Currently the documentation for the /service_areas endpoint of the Agency API states that it's a GET request with a Body containing provider_id and service_id. Per discussion in #78 - is that something you feel like fixing here @asadowns @thekaveman or would you rather I open a separate PR?

[thekaveman]

@oderby you are absolutely correct, good catch. I think opening a separate PR for that fix makes sense.

provider and agency are kind of evolving a different pace right now but eventually as more clarity is realized, the two should align pretty well.

[thekaveman]

Most of this looks really good.

For the location querying, I am concerned about URL length restrictions for complex polygons. Here's another idea I had for this:

• event_location a lat/lon pair
• radius in meters

Which would return events (trips and status_changes) that correspond to the given radius around the given point.

Not as clean as packaging up an exact polygon or some of the other JWT ideas we've discussed, but it's simple from an API perspective.

[thekaveman]

I like the bounding box approach, but I have a slight complication to bring up:

None of this addresses AND vs. OR - what if I want to query for all trips that started OR ended in my bounding box. With standard querystring semantics, this is an AND. (Of course I could always issue 2 requests and merge on the backend).

Another way to express this, albeit changing the wording and perhaps original intent of the spec, is to replace start_location and end_location params with the single bbox param; this would imply querying for all trips with any observed point in the bounding box. This removes the start/end type querying and grouping from the API and forces it on to the data layer, but I'd argue it makes sense there as the needs will be different for each use-case.

The bbox param would translate to status change querying and semantics as well (vs. start_location, end_location which don't really make sense for status change, or something else entirely, specific to status change).