Dec 19, 2013 ... /api/v2/geo/geocode?addr=200 State St, Albany NY&format=xml. To output JSON
-P a .... A sample batch geocoding request in PHP:
Sage Documentation Release 2.0
Ash Islam
December 19, 2013
Contents
i
ii
Sage Documentation, Release 2.0
The SAGE API exposes methods for geocoding, address correction, and district assignment given addresses or geocoordinates as input. The API supports JSON, JSON-P, and XML output formats. SAGE is also able to handle BluebirdCRM district assignment requests.
Contents
1
Sage Documentation, Release 2.0
2
Contents
CHAPTER 1
Basics
The API requests must be crafted to match the following structure: /api/v2//?params..
All API requests need to be validated using an assigned API key however it is not required when requests are made from within the NY Senate’s network. The key is supplied using the query parameter key: /api/v2//?&key=YOUR KEY HERE
The default output format is JSON. To change the output to XML or JSON-P simply set the format query parameter to xml or jsonp. For example to set to xml: /api/v2/geo/geocode?addr=200 State St, Albany NY&format=xml
To output JSON-P a callback must also be specified.: /api/v2/geo/geocode?addr=200 State St, Albany NY&format=jsonp&callback=methodName
3
Sage Documentation, Release 2.0
4
Chapter 1. Basics
CHAPTER 2
Groups
Each API method belongs in a logical group in order to make it easy to understand the goal of the request. The supported types for the group segment are as follows: Group address geo district street map
Description Address Lookup and Validation Geocode and Reverse Geocode District Assignment Street Lookup Map Data
5
Sage Documentation, Release 2.0
6
Chapter 2. Groups
CHAPTER 3
Methods
3.1 Common Query Parameters Many of the methods listed below follow a similar convention for inputting addresses or geo-coordinates. To supply a single address string use the parameter addr: /api/v2//?addr=200 State St, Albany NY 12210
To supply the individual components use the following parameters: addr1, addr2, city, state, zip5, zip4. The above query would be written as: /api/v2//?addr1=200 State St&city=Albany&state=NY&zip5=12210
Geo-coordinate pairs can be supplied to the appropriate method using lat and lon: /api/v2//?lat=43.00&lon=-73.10
Address, Geo, and District API calls allow for specifying a provider to carry out the request: /api/v2//?provider=PROVIDER_NAME
3.2 Address The following methods are implemented for the address service: Method validate citystate zipcode
Description Validate the given address Lookup the city and state given the zipcode Lookup the zipcode given a street address
The available providers are: Provider usps uspsais
Description USPS AMS Address Correction USPS AIS Address Correction
The usage of validate with an address input:
7
Sage Documentation, Release 2.0
/api/v2/address/validate?addr1=44 Fairlawn Avenue&city=Albany&state=NY
The validated response: { "status" : "SUCCESS", "source" : "USPSAMS", "messages" : [ ], "address" : { "addr1" : "44 Fairlawn Ave", "addr2" : "", "city" : "Albany", "state" : "NY", "zip5" : "12203", "zip4" : "1914" }, "validated" : true, "statusCode" : 0, "description" : "Success." }
A failed validation response: { "status" : "NO_ADDRESS_VALIDATE_RESULT", "source" : "USPSAMS", "messages" : [ ], "address" : null, "validated" : false, "statusCode" : 73, "description" : "The address could not be validated." }
Caution: USPS address validation requires addr1, city and state explicitly specified in the query parameters. Given a query that is missing those fields, USPS will not be used to perform validation and another provider will be used instead. The punct parameter can be supplied if abbreviations require a period appended to them. Simply add punct=true to the url to enable punctuation. The usage of citystate with a zip code input: /api/v2/address/citystate?zip5=12210
The city/state response: { "status" : "SUCCESS", "source" : "USPSAMS", "messages" : [ ], "city" : "ALBANY", "state" : "NY", "zip5" : "12210", "statusCode" : 0, "description" : "Success." }
A failed city/state response with invalid input:
8
Chapter 3. Methods
Sage Documentation, Release 2.0
{ "status" : "NO_ADDRESS_VALIDATE_RESULT", "source" : "USPSAMS", "messages" : [ "Invalid Zip Code." ], "city" : "", "state" : "", "zip5" : "", "statusCode" : 73, "description" : "The address could not be validated." }
The usage of zipcode: /api/v2/address/zipcode?addr1=44 Fairlawn Avenue&city=Albany&state=NY
The zipcode response: { "status" : "SUCCESS", "source" : "USPSAMS", "messages" : [ ], "zip5" : "12203", "zip4" : "1914", "statusCode" : 0, "description" : "Success." }
A failed zipcode response, similar to the failed validate response: { "status" : "NO_ADDRESS_VALIDATE_RESULT", "source" : "USPSAMS", "messages" : [ ], "zip5" : null, "zip4" : null, "statusCode" : 73, "description" : "The address could not be validated." }
Note: Zipcode lookup has the same USPS constraints as the validate method To force the request to use a certain provider supply the query parameter provider: /api/v2/address/?&provider=usps /api/v2/address/?&provider=uspsais
3.3 Geo The following methods are implemented for the geo service: Method geocode revgeocode
Description Geocode the given address Obtain address from given coordinate pair
The available providers ordered from most accurate to least are:
3.3. Geo
9
Sage Documentation, Release 2.0
Provider yahoo mapquest tiger ruby osm
Description Free YQL service from Yahoo. (recommended) Free MapQuest geocoding service In-database geocoding using census data Ruby implementation using census data Open Street Maps API
API Limits ~20000 day 5000 day? Unlimited Unlimited 1 per sec?
Methods have the following optional parameters: Param provider useFallback
Description Specify which geocode provider to use first (see above table) If false and provider is set, only the provider will be used for the request.
For example to use just yahoo without falling back to other providers in case of error: /api/v2/geo/?&provider=yahoo&useFallback=false
3.3.1 Geocode The usage of geocode with an address input: /api/v2/geo/geocode?addr=200 State St, Albany NY 12210 /api/v2/geo/geocode?addr1=200 State St&city=Albany&state=NY&zip5=12210
The geocode response: { "status" : "SUCCESS", "source" : "GeoCache", "messages" : [ ], "address" : { "addr1" : "200 State St", "addr2" : "", "city" : "Albany", "state" : "NY", "zip5" : "12210", "zip4" : "" }, "geocode" : { "lat" : 42.65203, "lon" : -73.75759, "quality" : "HOUSE", "method" : "YahooDao" }, "geocoded" : true, "statusCode" : 0, "description" : "Success." }
The source indicates where the response was returned from whereas geocode.method indicates where the geocode was computed. The address is typically a normalized representation of the input address but it depends on the geocode provider used. The geocode.quality metric indicates the accuracy/confidence level of the geocode. A successful geocode response will have one of the following quality levels ordered from most accurate to least: • POINT
10
Chapter 3. Methods
Sage Documentation, Release 2.0
• HOUSE • ZIP_EXT • STREET • ZIP An unsuccessful response will resemble the following: { "status" : "NO_GEOCODE_RESULT", "source" : "TigerGeocoder", "messages" : [ ], "address" : null, "geocode" : null, "geocoded" : false, "statusCode" : 71, "description" : "Geocode service returned no results." }
A RESPONSE_PARSE_ERROR status will also indicate a failed geocode operation.
3.3.2 Reverse Geocode The usage of revgeocode with a coordinate pair input: api/v2/geo/revgeocode?lat=42.652030&lon=-73.757590
The reverse geocode response: { "status" : "SUCCESS", "source" : "Yahoo", "messages" : [ ], "address" : { "addr1" : "200 State St", "addr2" : "", "city" : "Albany", "state" : "NY", "zip5" : "12210", "zip4" : "" }, "geocode" : { "lat" : 42.65204, "lon" : -73.757602, "quality" : "HOUSE", "method" : "YahooDao" }, "revGeocoded" : true, "statusCode" : 0, "description" : "Success." }
It is identical to the geocode response except for the revGeocoded field that indicates whether the reverse geocoding succeeded.
3.3. Geo
11
Sage Documentation, Release 2.0
3.3.3 Batch Geocode Multiple addresses can be geocoded with a single query using the batch api call. The format of the batch geocoding call is: /api/v2/geo/geocode/batch
The format of the batch reverse geocoding call is: /api/v2/geo/revgeocode/batch
The addresses for geocoding and points for reverse geocoding must be JSON encoded and sent in the POST request payload. The fields are identical to the query parameter fields for both address and point. Likewise any options can be specified the same way as the single request version. For example to specify provider: /api/v2/geo/geocode/batch?provider=PROVIDER_NAME
A sample batch geocoding request in PHP:
