Conventions for returning GeoJSON via API

Question

I have a queryable API that returns one or more GeoJSON FeatureCollections. Currently the response looks something like this:

{
  "success": {
    "data": {
      "layer1": {"type": "FeatureCollection"....},
      "layer2": {"type": "FeatureCollection"....}
    }
}

However, while trying to view the results in QGIS I realized this might not be the best approach (as QGIS doesn't allow you to specify an access key when adding a GeoJSON layer via a URI). I think this is generally a sensible design, except that I can't find any other examples of returning GeoJSON as part of a larger JSON structure.

Is there anything wrong with a GeoJSON feature (specifically a FeatureCollection, but really any type) being part of another "document"?

Though GeoJSON is JSON, I can also see a strong argument that if a user requests a resource as GeoJSON, it is rational to expect a valid GeoJSON document in return.

Answer 1

You'll have to patch existing software in order to use such a format, but there's nothing wrong with embedding GeoJSON in other JSON formats. JSON is super extensible like this. Every object is its own namespace.

If you look in the other direction, there are some applications, namely Leaflet, http://geojson.io, Fiona's command line programs, that will accept "bare" features and geometries. Applications that are more layer oriented (QGIS, ogr2ogr) typically do not and will require a feature collection.

If you have to have 2 layers in a single JSON document and don't want to write a new plugin for QGIS or a new driver for OGR, I suggest turning the layer/feature relationship inside out: have one feature collection and let features bear the name of a layer in their properties object.

{ "type": "FeatureCollection", "features": [
  { "type": "Feature", "id": "1", "properties": { "layer": "one" }},
  { "type": "Feature", "id": "2", "properties": { "layer": "two" }}
  ... 
  ] 
}

This approach has good default usability and most software will easily be able to break out the layers by selecting on the layer property. This multilayer profile of GeoJSON could be improved by adding a list of layers layers: ["one", "two"] to the feature collection (but now I'm just hand-waving).