RESTful APIs

Geocode with search

Contents

The Single Search Geocoding API takes in a string of text with details about a location, and it returns comprehensive data—address, latitude/longitude coordinates, and more—about the best matching locations in the Trimble Maps database.

The API has a wide range of uses—from finding coordinates for an address (or finding an address from coordinates) to verifying and standardizing address information. Those results can then be displayed through your own application or plugged into other Trimble Maps APIs for tasks such as truck routing, mapping, and mileage calculations.

The steps below can help ensure you get the best results from every search.

Place
The results of a search displayed on a map.

Search is performed through a GET method call to the Single Search API. All API calls require an API key for authentication. You can immediately request a trial API key by clicking on GET AN API KEY at the top of this screen.

The single search service is available through the following URL:

https://singlesearch.alk.com/{region}/api/search?authToken={your-api-key}

In order to get a valid URL to the single search service, replace {region} with one of the supported regions: NA, WW, EU, AS, AF, SA, or OC

Step 1: Input a quality query

As the name implies, Single Search is built to accept any type of location query as a single string of text. (Similar to a web search engine.) However, providing a higher quality query helps the service provide the best results.

  • Addresses should be as complete and accurate as possible, including the street number and name, city, country or state, and ZIP/postal code. Separate each item with a comma. (Example: 1 independence way, princeton, nj, 08540)
  • Latitude/longitude coordinates should be six decimal places. (Example: 121.290867,-37.957791)
  • Parking instructions, phone numbers, and other extraneous information should be left out of the query.

The query parameter is populated with your text search string when making the API call.

While query is the only required parameter for a search, there are several recommended parameters that can help you refine your results.

Parameter Description Required? Example
currentLonLat The current longitude and latitude, where longitude and latitude are either decimal or integer coordinates. This is helpful for searches that only require results from nearby locations. While currentLonLat directs the service to search nearby, the service will continue to look farther away if there are no local matches. N currentLonLat=121.290867,-37.957791
countries A comma-separated list of country codes by which you want to filter all results. This limits the search to specific countries. N countries=FR
states A comma-separated list of state abbreviations by which you want to filter all results. This limits the search to specific states. N states=NJ,PA
lang The language to use in results. U.S. English is the default. N lang=IT

Step 3: Set optional parameters, if necessary

The API supports also a number of other parameters that are helpful depending on your use case, or in situations where you need to call information from other Trimble Maps APIs.

Parameter Description Required? Example
includeOnly or
excludeResultsFor 		These parameters are filters when you only want search to return results that match certain elements in the query string. Allowable filters are: Country, State, County, City, POBox, Zip, SPLC, Street, RouteNumber, RouteAlpha, POI, POIStreet, FullPostCode, POIType, CrossStreet, LatLon, CustomPlace, and None. N includeOnly=Zip,Street
(This will return only ZIP codes and streets that match with the search string.)
include Set include to meta to retrieve additional metadata in your results, including the confidence level of the search results. This is important when you are using location data for truck routing and you want to be sure you are selecting the best location from the search results. A low score suggests the result does not match at least part of the address in the query. N include=Meta
includeTrimblePlaceIds (North America Only) Set to true to return the TrimblePlaceId, PlaceName and SiteName for a location, if they exist. Default is false. The TrimblePlaceId can then be plugged into the Places API to retrieve a wealth of additional information about the location. N includeTrimblePlaceIds=true

Sample Request - Street Search in Europe

https://singlesearch.alk.com/eu/api/search?authToken=​{APIKEY}&query=Tiroler%20Strasse,%2013187%20Berlin,%20BE,%20DE,%20Berlin&​currentLonLat=-13%2E400291,52%2E520869&countries=D&lang=de&include=Meta&includeOnly=streets

Sample Response 

{
  "Err": 0,
  "ErrString": "OK",
  "QueryConfidence": 1,
  "TimeInMilliseconds": 15,
  "GridDataVersion": "GRD_NT.EU.2021.03.1.2.1.1",
  "CommitID": "pcmws-24.0.0.0-340-ge5f1ca6b930: 12/13/2021 20:32",
  "Locations": [
    {
      "Address": {
        "StreetAddress": "Tiroler Straße",
        "City": "Berlin",
        "State": "BE",
        "StateName": "Berlin",
        "Zip": "13187",
        "County": "Berlin",
        "Country": "DE",
        "CountryFullName": "Deutschland",
        "SPLC": null
      },
      "Coords": {
        "Lat": "52.55956",
        "Lon": "13.402335"
      },
      "StreetCoords": {
        "Lat": "52.55956",
        "Lon": "13.402335"
      },
      "Region": 3,
      "POITypeID": 0,
      "PersistentPOIID": -1,
      "SiteID": -1,
      "ResultType": 6,
      "ShortString": "Tiroler Straße, 13187 Berlin, BE, DE, Berlin",
      "GridID": 22201938,
      "LinkID": 217,
      "Percent": 5000
    }
  ]
}

Sample Request - Address Search in North America

https://singlesearch.alk.com/na/api/search?authToken=​{APIKEY}&query=3611%20South%20Northpointe%20Drive,%20Fresno,%20CA,%2093725&​currentLonLat=121%2E290867,-37%2E957791&countries=US&include=Meta&includeTrimblePlaceIds=true

Sample Response 

{
  "Err": 0,
  "ErrString": "OK",
  "QueryConfidence": 1,
  "TimeInMilliseconds": 16,
  "GridDataVersion": "GRD_ALK.NA.2021.04.17.9.1.1",
  "CommitID": "pcmws-24.0.0.0-340-ge5f1ca6b930: 12/13/2021 20:32",
  "Locations": [
    {
      "Address": {
        "StreetAddress": "3611 South Northpointe Drive",
        "City": "Fresno",
        "State": "CA",
        "StateName": "California",
        "Zip": "93725",
        "County": "Fresno",
        "Country": "US",
        "CountryFullName": "United States",
        "SPLC": null
      },
      "Coords": {
        "Lat": "36.681229",
        "Lon": "-119.769273"
      },
      "StreetCoords": {
        "Lat": "36.681231",
        "Lon": "-119.770307"
      },
      "Region": 4,
      "POITypeID": 1800,
      "PersistentPOIID": 1340829,
      "SiteID": -1,
      "ResultType": 10,
      "ShortString": "Amazon, 3611 South Northpointe Drive, Fresno, CA, US, Fresno 93725",
      "TrimblePlaceId": "0xcCZYcAOBIkaL3SyX-JYtjA",
      "GridID": 13595428,
      "LinkID": 307,
      "Percent": 6388
    }
  ]
}
Last updated January 9, 2023.
Contents