Geocoding APIs
Contents
Our Geocoding APIs separately support forward, reverse, and batch geocoding. For new implementations, we recommend using our Single Search API which can do all of these things. While both services offer similar results, Search has more features and can accept many types of input in a single API.
-
Geocoding with the
/locationsresource allows you to find GPS coordinates as well as complete address information for a given street address. -
Reverse geocoding with the
/locations/reverseresource instead takes in a single pair of coordinates and returns the approximate address on which that point is located. With additional licensing, a road’s speed limit information can also be provided when reverse geocoding a location.
Batch Geocoding
If you are looking to geocode or reverse geocode a batch of addresses or GPS coordinates all at once, you can use our /locations/address/batch and /locations/reverse/batch resources.
Interactive Examples
The following pages include interactive examples where you can test our Location APIs after entering your API key in the YOUR API KEY HERE box.
Below you will find descriptions of the parameters shared among these APIs, as well as sample requests and responses.
Location Request Parameters
| Data Element | Description | Data Type | Value/Example | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Geocoding | street | The house number and street name in a single string. Note: Batch geocoding calls use an Address object. |
string | 1 Independence Way | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| city | The name of the city. Wildcard search is not supported for city field. The stringSearch field
should be used for wildcard searches. Note: Batch geocoding calls use an Address object.
|
string | Princeton | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| state | The two letter state (or country) abbreviation. Go here or run a states and countries search if you are unsure of an abbreviation. Note: Batch geocoding calls use an Address object. |
string | NJ | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| postcode | The ZIP or Postal Code. Only 5-digit ZIP codes are supported in the U.S. (No ZIP+4 codes.) Note: Batch geocoding calls use an Address object. |
string | 08540 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| country | The country code using the format set by
countryAbbrevType. (FIPS is the default format.) Note: Batch geocoding calls use an Address object.
|
string | UK | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| searchString | Allows searching of [ZIP] [city,] [state][; street address] or [splc] all on one line. Individual
street/city/state/postcode/splc fields will be ignored when this is used. If street address is supplied, it
requires a ZIP and/or city and must be prefaced by a semicolon. A location can also be entered in this field as a latitude/longitude point. |
string | 08540 Princeton, NJ; 457 N Harrison St or 08540 or Princeton or 36.093508,-86.058374 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| postcodeFilter | The postal code filter; use this to filter ZIP codes by country. (North America only) |
string | US to indicate US ZIP codes only Mexico to indicate Mexican postal codes only Both to indicate both | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| citySearchFilter | The city search filter; use this to filter pure city search. Overridden if address is provided. |
Enum |
Set to 0 to return cities and corresponding ZIPs (Default); Set to 1 to return city centers only (no ZIPs). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| splc | The Standard Point Location code to use in place of street/city/state/ZIP |
string | 392832000 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| list | The number of matches to display if geocoding results in a less than perfect match. |
string | 4 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Reverse Geocoding | Coords | Contains geographic coordinates used in reverse geocoding. The coordinates are represented by a comma separated pair of floating point numbers representing longitude and latitude, in that order. We recommend six digits after the decimal point for increased accuracy. |
Double Array | -76.123456,42.123456 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lang POST: PreferredCityLanguage
|
Sample Geocode Request
https://pcmiler.alk.com/apis/rest/v1.0/Service.svc/locations?street=1600%20Pennsylvania%20Avenue%20Northwest&city=Washington&state=DC&postcode=20500&country=US
Sample Geocode Response
{
"Address": {
"StreetAddress": "1600 Pennsylvania Avenue Northwest",
"City": "Washington",
"State": "DC",
"Zip": "20500",
"County": "District of Columbia",
"Country": "United States",
"SPLC": null,
"CountryPostalFilter": 0,
"AbbreviationFormat": 0,
"StateName": "District of Columbia",
"StateAbbreviation": "DC",
"CountryAbbreviation": "US"
},
"Coords": {
"Lat": "38.898730",
"Lon": "-77.036679"
},
"Region": 4,
"Label": "",
"PlaceName": "",
"TimeZone": "EDT",
"Errors": [],
"SpeedLimitInfo": null,
"ConfidenceLevel": "Exact",
"DistanceFromRoad": null,
"CrossStreet": null
}
Sample Reverse Geocode Request
https://pcmiler.alk.com/apis/rest/v1.0/Service.svc/locations/reverse?coords=-71.227186,46.813427&matchNamedRoadsOnly=true&maxCleanupMiles=5.5
Sample Reverse Geocode Response
{
"Address": {
"StreetAddress": "270 Rue Saint Joseph Est",
"City": "Quebec",
"State": "QC",
"Zip": "G1K 3A9",
"County": "",
"Country": "Canada",
"SPLC": null,
"CountryPostalFilter": 0,
"AbbreviationFormat": 0,
"StateName": "Quebec",
"StateAbbreviation": "QC",
"CountryAbbreviation": "CA"
},
"Coords": {
"Lat": "46.813427",
"Lon": "-71.227186"
},
"Region": 4,
"Label": "",
"PlaceName": "",
"TimeZone": "EDT",
"Errors": [],
"SpeedLimitInfo": null,
"ConfidenceLevel": "Exact",
"DistanceFromRoad": 0.003,
"CrossStreet": null
}