Geocoding APIs
Our Geocoding APIs support both geocoding and reverse geocoding.
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 | 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. | string | Princeton | |
state | The two letter state (or country) abbreviation. | string | NJ | |
postcode | The ZIP or Postal Code | string | 08540 | |
country | The country code using the format set by
countryAbbrevType. (FIPS is the default format.) | 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 | The language to use in results. For reverse geocoding only. | string | ENUS - U.S. English(Default) ENGB - Great Britain English DE - German FR - French ES - Spanish IT - Italian | |
assetId | The ID of the asset (device, vehicle or driver) associated with this request. | string | abc1234 | |
matchNamedRoadsOnly | When looking up coordinates, this forces reverse geocoding to match named roads only | boolean | ||
maxCleanupMiles | When looking up coordinates, this sets a maximum radius, in miles, in which to find the closest matching road | double | 5.5 | |
includePostedSpeedLimit | For users licensed for speed limit data, this parameter will include the posted speed limit in the response. | boolean | ||
heading | Speed limits may differ based on direction. This parameter is used with includePostedSpeedLimit
to increase accuracy of getting the correct speed limit. | double | 0 - North 90 - East 180 - South 270 - West | |
includeLinkInfo | Unique road link identifiers are supplied when this is set to true. | boolean | ||
speedLimitPref | Preferred speed limit source. | string | Default Premium (NA only) Navteq (Outside NA) LinkBased (NA only) | |
timestamp | The time (UTC assumed if none specified) at the location which will be used to determine whether daylight savings time will be applied on the output time zone. | string | 2008-05-01T07:34:42-5:00 or 2008-05-01 7:34 AM | |
includeTrimblePlaceIds | Set to true to return any TrimblePlaceIds and Place names associated with the geocoded location. Those details are returned within the PlaceName parameter. Default is false. | Boolean | True False | |
| Both | ||||
countryAbbrevType | The abbreviation format for countries. | Enum | FIPS(Default) ISO2 ISO3 GENC2 GENC3 | |
region | The data region in which the address or coordinates lie. | Enum | 0 - Unknown 1 - AF 2 - AS 3 - EU 4 - NA(Default) 5 - OC 6 - SA 7 - ME | |
dataset | For users licensed for multiple regional datasets. Read more about setting the dataset. | Enum | PCM_EU PCM_OC PCM_SA PCM_ME PCM_AS PCM_AF PCM_WW(Worldwide) PCM_GT(GeoTrack) Current(Default) PCM18-PCM33 |
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
}