Skip to main content
RESTful APIs

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 /locations resource allows you to find GPS coordinates as well as complete address information for a given street address.

  • Reverse geocoding with the /locations/reverse resource 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. Go here or run a states and countries search if you are unsure of an 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. In some situations, the service will still return a road at a greater distance, but it will return at best a Confidence Level 3 rating. Be sure to check ConfidenceLevel and DistanceFromRoad in your geocoding call response before navigating to a geocoded address. 
double
5.5
includePostedSpeedLimit For users licensed for speed limit data, this parameter will include the posted speed limit in the response. 
boolean
SpeedLimitOption In a reverse geocoding batch POST request, SpeedLimitOption is an object with the following parameters:

CurrentSpeed
Heading
Vehicle
IgnoreDefaultSpeeds 

object
"SpeedLimitOption": {
"CurrentSpeed": 40,
"Heading": 180,
"Vehicle": 0,
"IgnoreDefaultSpeeds": true
},
currSpeed
POST: CurrentSpeed 		The current speed of the vehicle. This parameter is used with the includePostedSpeedLimit query parameter to increase accuracy of getting the correct speed limit. 
integer
55
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
ignoreDefaultSpeeds Set to true to return null rather than Trimble MAPS defined road speeds in situations where no link-based or Premium posted speed limits are available. This parameter is used with includePostedSpeedLimit and defaults to false. 
boolean
includeLinkInfo Unique road link identifiers are supplied when this is set to true. 
boolean
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
units Specifies whether English or metric units are used. 
Enum
0 - English (Imperial)(Default)
1 - Metric
2 - Regional (The units used in the geocoded country)
vehicle The vehicle type 
Enum
0 - Truck (Default)
1 - LightTruck
2 - Auto
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-PCMXX ("XX" is the most current version of PC*MILER. Call /pcmversion to see the latest versions available.)

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
}
Last updated November 23, 2021.
Contents