have to consider GeoReport v2's use of API keys. I'd like to propose a solution
that effectively provides universal discovery (that is, allows a client to find
relevant jurisdictions where it can create service requests) in light of the v2
API key requirement and the reality of widely-adopted SaaS endpoints. This
solution does not require a central service provider, but merely adapts two
methods discussed last year that we (Alexandria) launched this past January:
GET /boundaries.FMT
This describes a simple, rectangular bounding box. We will not accept tickets
for points outside this. A client can use this to spot obvious location
problems without any additional network traffic. Sample URL:
http://request.alexandriava.gov/GeoReport/Service.ashx/boundaries.xml?jurisdiction_id=alexandriava.gov
GET /validate/location.FMT
Pass in at least lat + long and it will return a list of zero or more matching
jurisdictions. We will not accept tickets for any points that fail this test,
or where our_jurisdiction is false. With this, a client like our
Call.Click.Connect. website can give the customer immediate, authoritative
feedback about a specific point. Sample URL:
http://request.alexandriava.gov/GeoReport/Service.ashx/validate/location.xml?long=-77.0427417755127&lat=38.8052361218662&jurisdiction_id=alexandriava.gov
How does this help with universal discovery?
There are a number of vendors like SeeClickFix, Fix311, and Connected Bits that
provide Open311 layers to multiple jurisdictions. I expect that such vendors
would normally accept the same Open311 API key for multiple jurisdictions: get
a SCF key that works for Washington, DC, and it should work for any of the
dozens of other SCF jurisdictions (http://seeclickfix.com/open311) Right? So
here's what I'd propose for addressing discovery of all "available" (meaning
those that will accept my service requests) jurisdictions.
Enhance /boundaries.FMT so that if no jurisdiction_id is passed
A) a <jurisdictions> element would be added inside <boundaries> containing
information about each jurisdiction served by the endpoint -- at least the
jurisdiction_id value, the jurisdiction name, and its bounding box
B) the bottom/left/top/right at the root of the <boundaries> element should
describe a bounding box containing *all* jurisdictions in that <jurisdictions>
element
A client would simply keep track of the endpoint URL for each of its API keys
and obtain this boundaries information from each of those endpoints. The
jurisdiction boundaries information would allow the client to narrow down the
list of possible jurisdictions.
A client that wants to check for a specific location would call
/validate/location.FMT for any endpoint whose bounding box[es] (probably
already cached) contained that point.
Below is an example of what a multi-jurisdiction boundaries.xml for Washington
DC and Alexandria, VA might look like. If the client isn't sure of the exact
problem location, it could at least use this to present to the user a list of
distance-sorted choices (maybe I want to report a pothole in Alexandria but
waited until I parked in DC to open my app -- in that case the bounding box
info also helps load a useful map).
<boundaries>
<!-- The following describes a rectangle containing both DC and Alexandria.
If your point isn't in here, no need to examine the jurisdictions
element. -->
<bottom>38.7858448444005</bottom>
<left>-77.1443260290448</left>
<top>38.995573</top>
<right>-76.909554</right>
<!-- Now we provide separate bounding boxes for specific jurisdictions -->
<jurisdictions>
<jurisdiction>
<jurisdiction_id>alexandriava.gov</jurisdiction_id>
<jurisdiction_name>City of Alexandriava, VA</jurisdiction_name>
<our_jurisdiction>true</our_jurisdiction>
<!-- this rectangle contains Alexandria -->
<bottom>38.7858448444005</bottom>
<left>-77.1443260290448</left>
<top>38.8449444072655</top>
<right>-77.0372775288873</right>
<jurisdiction>
<jurisdiction>
<jurisdiction_id>dc.gov</jurisdiction_id>
<jurisdiction_name>Washington, DC</jurisdiction_name>
<our_jurisdiction>false</our_jurisdiction>
<!-- this rectangle contains DC. Its southwest corner overlaps the
northeast corner of Alexandria's bounding box -->
<bottom>38.791607</bottom>
<left>-77.119217</left>
<top>38.995573</top>
<right>-76.909554</right>
<jurisdiction>
</jurisdictions>
</boundaries>