Input waypoints

[perrygeo]

The directions, distance and surface APIs all require input waypoints. Let's specify this in more detail...

At the python SDK level, all of the services take an iterable/list of GeoJSON-like feature mappings. At the command line, it's not clear to me exactly what the inputs will be.

The CLI will take x and normalize it to a list of features where x could potentially be

• line-delimited GeoJSON features on the stdin stream (output of fio cat)
• path to a GeoJSON file containing a featurecollection of points (probably the most common case?)
• paths to GeoJSON files each containing point features (makes interop with geocoding easier since you're likely to get one feature per call)
• stream or file of GeoJSON geometries
• stream or multiple args with JSON arrays of coordinate pairs "[lat, lon]" (ala the input to reverse geocoder)
• ... others? ...

So the question is, What types of inputs will we support for waypoints? On one hand I want to support the most common workflows even if that means accepting a bunch of different input formats. On the other hand, unix design principles - let other tools do the lifting to get data into our expected format.

And on a related note, if we're accepting GeoJSON and the service requires points, how should we handle other geometry types? Automatically explode multipoints and lines to points? Skip them? Be strict? Most of these validation decisions will likely be implemented at the SDK level but it might be useful to discuss them in this context.

cc @sgillies

[sgillies]

Seems to me that we've got to support at least these two inputs:

• streams of coordinate pairs (either as JSON or comma-delimited pairs), the most abstract input
• geocoding output, the least abstract input

Let's put other possible inputs (GeoJSON geometries) aside for now.

To generate a list of waypoints from a list of addresses, a user needs to make multiple geocoding requests, select from multiple results for each, and probably ends up with a feature collection containing point-of-interest type features. Agree with your assessment above that this is the most common use case.

In converting those types of features to points, I think the least surprising thing to do is to compute a centroid of the feature geometry instead of exploding them into multiple points. The workflow is something like this, right?

  Geocoding stuff --> FeatureCollection --> list of [x, y] centers --> API

What doesn't exist yet is the utility that merges the best points of interest from every address query into one feature collection. Do we want to provide such glue for users?

[perrygeo]

utility that merges the best points of interest from every address query into one feature collection

It's a bit funky but cat, jq and fio collect can already do that:

cat <(x-mapbox geocoding "Portland, OR" | jq -c .features[0]) \
    <(x-mapbox geocoding "Bend, OR" | jq -c .features[0]) \
    <(x-mapbox geocoding "Corvallis, OR" | jq -c .features[0]) \
    | fio collect > points_featurecollection.geojson

[sgillies]

Your bash fu is strong, @perrygeo.

[perrygeo]

So the current supported input options are:

• Coordinate pair(s) of the form [0, 0] or 0,0 or 0 0
• An input stream/file(s) containing either a GeoJSON Feature or FeatureCollection.
• For functions that accept points only, any non-point feature is silently filtered out.

[perrygeo]

Calling it good for now