Define API for validating specific problem geolocation

[peterwtux]

We use /location.xml?long=-x&lat=y to allow clients to test whether we will accept tickets for a specific geolocation. Like /boundaries.FMT, this allows clients to quickly give feedback on a point and keep the customer from wasting time entering more info about a point where we cannot provide service. Sample output:

Good point:

<response>
<location_found>true</location_found> (boolean; indicates we're confident where the point is)
<jurisdictions> (array of relevant jurisdictions)
<jurisdiction>
<jurisdiction_id>someplace.gov</jurisdiction_id>
<our_jurisdiction>true</our_jurisdiction> (we will accept tickets for this jurisdiction)
<location_ok>true</location_ok> (yes, for this location)
</jurisdiction>
</jurisdictions>
</response>

Bad point:

<response>
<jurisdictions></jurisdictions>
</response>

[peterwtux]

I'd like to suggest extending this in three ways:

1. allow the jurisdiction response object to include an optional "address_string" value (to allow this method to be used as a reverse geocoder)
2. allow the jurisdiction response object to include an optional "error_description" attribute
3. accept an optional input argument service_code

Also I suggest extending GET /services/[service_code].[format] to include an optional "validate_location" boolean response attribute of the service_definition element. If true, validate_location indicates that the client should use /location.xml?long=-x&lat=y&service_code=z to validate a specific location for that specific service code before trying to create a service request for that service code (and that the service might reject requests for locations that might be acceptable for other service codes).

Any non-empty error_description should be shown to the client for any jurisdiction element where our_jurisidiction is true, to explain why the location is being rejected.

Any non-empty address_string should be suggested to the client for any jurisdiction element where location_ok is true.

This would allow more intelligent handling of requests, whether it's for purely spatial reasons like only accepting pothole requests for roadway locations maintained by the jurisdiction, or for other reasons like during a winter storm not accepting snow removal requests on public streets that have not yet been plowed and are not expected to be passable yet.