Batch API response (QM focus)

[awolfe76]

This is a question to get the conversation started on the batch API response for M3.

• Can more than one result be returned per query?
• Can we have no results returned, or will there always be something (maybe just low relevancy)?
  • If multiples are returned is the first one the best? Add relevancy to determine the best?
• Adding a status per query ('OK', 'No results', 'Multiple Results')?
• Add keys for app specific (e.g. QM) queries?
• Should we introduce FeatureCollection for results per query?

A possible example:

[
  {
    "type": "FeatureCollection",
    "query": "638 Louise Terrace, Loomis, California, 81985",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -74.518537,
            179.083152,
            0
          ]
        },
        "properties": {
          "address": "637 Louise Terrace, Loomis, California, 81985",
          "alt_addresses": "",
          "load_date": 1284882682262,
          "relevancy": 0.99
          // QM fields
          "county": "",
          "census_block": 2.03,
          "rural_underserved": false          
        }
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -74.518537,
            179.083152,
            0
          ]
        },
        "properties": {
          "address": "636 Louise Terrace, Loomis, California, 81985",
          "alt_addresses": "",
          "load_date": 1284882682262,
          "relevancy": 0.99
          // QM fields
          "county": "",
          "census_block": 2.03,
          "rural_underserved": false
        }
      }
    ],
    "status": "OK"
  }
]

[jmarin]

• Can more than one result be returned per query? We are not doing this right now, but it is possible. Some geocoding services only return one (i.e. census, it is ONE interpolated point)
• Can we have no results returned, or will there always be something (maybe just low relevancy)? No results is a valid return. There are addresses that can't be found at all, even though they look fine to the parser
• If multiples are returned is the first one the best? Add relevancy to determine the best? The first one is usually the closest match. We can add a field that has a "quality" or "match" score (taken from underlying Elasticsearch results, or doing our own)
• Adding a status per query ('OK', 'No results', 'Multiple Results')? Yes, this is coming, in a PR that will be merged soon
• Add keys for app specific (e.g. QM) queries? Hmmm not sure we want to do this, it couples service with clients in a subtle way (number of clients could be n). I think grasshopper is "one" geocoder that provides a default cascading experience to some backend geocoding microservices. How these are composed can change, there could be a QM client that consumes part of these, or that composes them in a different way.
• Should we introduce FeatureCollection for results per query? It's possible. We have gone a different route for now (upcoming PR, will have documentation in docs folder), but we can discuss. Your example json reads as "array of feature collections" to me (though there is only one)

[awolfe76]

Thanks @jmarin .

I'm ok with only one result, certainly simplifies things on the front-end. In QM-land we were showing multiples (and giving the option to choose), but having only one possible response removes that need ... which seems good to me, for a version 1.

Same for no results.

So, for the additional fields (QM example), are you saying we'll a call to a QM API which in turn will handle the geocoder call as well? And piece it all together? Again, sounds good just want to make sure I understand. Seems like the response in the QM case could be very similar to the geocoder response, with a few additional fields.

For the FeatureCollection, the array was to show that there could be more than one, but yeah, I only included one. Though it might not be necessary if we have only 0 or 1 response per address. Features would be fine, as long as we have the actual query in there too. Maybe as a property value, really only necessary for batch.

[
    {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -74.518537,
            179.083152,
            0
          ]
        },
        "properties": {
          // the query
          "query": "636 Louise Terrace, Loomis, California, 81985",
          "address": "636 Louise Terrace, Loomis, California, 81985",
          "alt_addresses": "",
          "load_date": 1284882682262,
          "relevancy": 0.99
        }
    },
    // as many others as required
]

[jmarin]

@awolfe76 Thanks, this gives me something to start chewing on. Will update this with comments as I dive deeper into the implementation