{"action":"opened","issue":{"url":"https://api.github.com/repos/cfpb/grasshopper/issues/18","labels_url":"https://api.github.com/repos/cfpb/grasshopper/issues/18/labels{/name}","comments_url":"https://api.github.com/repos/cfpb/grasshopper/issues/18/comments","events_url":"https://api.github.com/repos/cfpb/grasshopper/issues/18/events","html_url":"https://github.com/cfpb/grasshopper/issues/18","id":57643143,"number":18,"title":"ersi's \"GeoServices REST Specification\" for Geocoding?","user":{"login":"hkeeler","id":4269085,"avatar_url":"https://avatars.githubusercontent.com/u/4269085?v=3","gravatar_id":"","url":"https://api.github.com/users/hkeeler","html_url":"https://github.com/hkeeler","followers_url":"https://api.github.com/users/hkeeler/followers","following_url":"https://api.github.com/users/hkeeler/following{/other_user}","gists_url":"https://api.github.com/users/hkeeler/gists{/gist_id}","starred_url":"https://api.github.com/users/hkeeler/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hkeeler/subscriptions","organizations_url":"https://api.github.com/users/hkeeler/orgs","repos_url":"https://api.github.com/users/hkeeler/repos","events_url":"https://api.github.com/users/hkeeler/events{/privacy}","received_events_url":"https://api.github.com/users/hkeeler/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/cfpb/grasshopper/labels/question","name":"question","color":"cc317c"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2015-02-13T19:33:48Z","updated_at":"2015-02-13T19:33:48Z","closed_at":null,"body":"While stumbling around the [TIGER Products](https://www.census.gov/geo/maps-data/data/tiger.html) site, I came across their [REST Services](http://tigerweb.geo.census.gov/tigerwebmain/TIGERweb_restmapservice.html) page.  I honestly couldn't get a whole lot out of it since I don't speak the _Geo Jargon_ yet, but from there I came across [esri](http://www.esri.com/)'s [GeoServices REST Specification](http://www.esri.com/industries/landing-pages/geoservices/geoservices), which has the lofty goals of:\r\n\r\n>The GeoServices REST Specification provides a way for Web clients to communicate with geographic information system (GIS) servers through Representational State Transfer (REST) technology.\r\n\r\n>The specification is\r\n\r\n>* A proven and easy to understand method for a broad range of clients and applications to request map, feature, attribute, and image information from a GIS server.\r\n* A JSON-based, REST-ful specification that will make the GIS server instantly usable by thousands of developers working in popular client-side development environments with the ArcGIS Web mapping APIs for JavaScript™, Flex™, Silverlight®, iOS®, and Android™.\r\n\r\nSo, while checking out _that_ spec, I noticed they have a [Find Address \r\nCandidates](http://www.esri.com/~/media/Files/Pdfs/library/whitepapers/pdfs/geoservices-rest-spec.pdf#page=59) (sorry, PDF :disappointed:  ) endpoint, which looks something like:\r\n\r\n**Request:**\r\n\r\n```url\r\nhttp://myserver/rest/services/GeocodeUSA/GeocodeServer/findAddress\r\nCandidates?Address=380+New+York+Street&City= \r\nRedlands&State=CA&Zip=92373 \r\n```\r\n\r\n**Response:**\r\n\r\n```json\r\n{ \r\n    \"spatialReference\": {\"wkid\" : 4326}, \r\n    \"candidates\" : [{ \r\n         \"address\" : \"1 MASON ST\", \r\n         \"location\" : { \"x\" : -122.408951, \"y\" : 37.783206 }, \r\n         \"score\" : 75, \r\n         \"attributes\" : {\"StreetName\" : \"MASON\", \"StreetType\" : \"ST\"} \r\n     }, \r\n     { \r\n         \"address\" : \"49 MASON ST\", \r\n         \"location\" : { \"x\" : -122.408986, \"y\" : 37.783460 }, \r\n         \"score\" : 27, \r\n         \"attributes\" : {\"StreetName\" : \"MASON\", \"StreetType\" : \"ST\"} \r\n    }] \r\n} \r\n```\r\n\r\nUnfortunately, their example request and response don't really seem to have correlation...but you get the gist.  So, now I have some questions:\r\n\r\n1. Is there any utility is implementing their spec for our Geocoder APIs?\r\n    1. Is this spec widely adopted as they claim?\r\n    1. If we only implement a single service out of the many in the spec, would that lead to confusion?  The spec does state:\r\n\r\n        >Developers can choose how much or how little to implement. For example, if geocoding or \r\ngeoprocessing operations are not exposed by the GIS server, developers may not need to \r\nimplement the Geocode Service or GP Service piece of the specification.\r\n\r\n        ...and they _seem_ to have a mechanism for describing which of the services you have implemented.\r\n1. They return multiple possible results, with a `score` attribute associated with each.  There's not description of this _score_ in the docs, but I assume its a 1-100 scale of least-to-most likely matches.  This seems very similar to our \"cascading\" matches from different data sources.  Should _we_ include something like this?\r\n1. They return a `wkid` (Well-known ID).  Is this a proprietary ArcGIS thing, or something more widely adopted?  Would we use it?\r\n\r\nOverall, this API seems \"OK\".  I definitely feel like we could come up with something cleaner, but if enough folks are already using this, perhaps its worth considering?\r\n"}}