Single Search Geocoding API
Contents
Our Single Search service allows you to geocode an address that a user submits as a single string of text—similar to a query on a web search engine. It returns an array of locations that match the search text. It can also help provide more relevant search results, giving you the ability to search based on the current location (a longitude/latitude point).
Single Search is our most advanced API for geocoding. It allows you to search for addresses, coordinates, places, and points of interest throughout the world. We recommended it for all new implementations.
We also offer a suite of Geocoding APIs that separately supports forward, reverse, and batch geocoding. These APIs provide similar results as Search, but require a more structured input. They are intended for special cases where the customer requirements and user input is more narrowly defined.
With your API key, you can test out the Single Search service by going here.
Getting Started
The single search service is available through the following URL:
https://singlesearch.alk.com/{region}/api/{endpoint}?authToken={your-api-key}
- In order to get a valid URL to the single search service, replace {region} above with one of the supported regions: NA, WW, EU
- You will need a valid API key to replace {your-api-key}
- Replace {endpoint} with one of the endpoints below
Endpoints
GET /search
/search is the main geocoding URL and supports the parameters below.
Name | Description | Data Type | Required |
---|---|---|---|
authToken
| Provided API Key | Yes | |
query
| String indicating the text to search for |
string | Yes |
maxResults
| Limits search results by the specified number. Must be a value between 1 and 100. |
Int | No |
currentLonLat
| The current longitude and latitude, where longitude and latitude are either decimal or integer coordinates. |
Complex | No |
excludeResultsFor Replaces excludedSearchTypes , which has been deprecated
| A comma-separated list of InterpTypes to exclude from the search. Available types: Country, State, County, City, ZIP, SPLC, Street, RouteNumber, RouteAlpha, POI, POIStreet, FullPostCode, POIType, CrossStreet, LatLon, and CustomPlace. |
string | No |
includeOnly
| A comma-separated list of InterpTypes to include in the search response. Allowed filters: Country, State, County, City, Zip, SPLC, Street, RouteNumber, RouteAlpha, POI, POIStreet, FullPostCode, POIType, CrossStreet, LatLon, CustomPlace, CustomPlaceStreet and None. (Example: includeOnly=CustomPlace,Street. This will return only custom place and streets that match with the search string.) |
string | No |
poiCategories
| A comma-separated list of Points of Interest (POI) category names by which you want to filter all POI results. A GET call to /search/poiCategories can be used to retrieve the current list of categories available for filtering. |
string | No |
countries
| A comma-separated list of country codes by which you want to filter all results. It defaults to ISO format. |
string | No |
countryType
| The standard for country abbreviations: ISO, FIPS, GENC2, and GENC3. |
string | No |
states
| A comma-separated list of state abbreviations by which you want to filter all results. |
string | No |
include
| Set to include=Meta to include additional metadata in your results, such as road grid and link information as well as the confidence level of the search results. (See QueryConfidence in response parameters below.)
|
string | No |
useCustomPlaces
| If set to true, returns any custom places in the account where the location’s PlaceId or PlaceName starts with the query string. Those results will be included in the result list before any single search results. |
boolean | No |
separateHN
| Sets whether the house number should be returned as a separate field from the rest of the street address. Default is false. |
boolean | No |
getAllHNRanges
| If set to true, all potential house number ranges will be returned for a particular street match. Default is false. |
boolean | No |
includeTrimblePlaceIds
| Set to true to return the TrimblePlaceId , PlaceName and SiteName for a location, if they exist. Default is false.
|
boolean | No |
lang
| The language to use in results. en-us - U.S. English (Default) en-gb - Great Britain English de - German fr - French es - Spanish it - Italian |
string | No |
These additional parameters below are only applicable when performing a reverse geocode search using latitude/longitude coordinates.
Name | Description | Data Type | Required |
---|---|---|---|
matchNamedRoadsOnly
| When looking up coordinates, this forces reverse geocoding to match named roads only. |
boolean | No |
maxCleanupMiles
| When looking up coordinates, this sets a maximum radius, in miles, in which to find the closest matching road. |
double | No |
heading
| Used to determine which road link to snap to. For instance, when crossing a highway. Values are: 0 - North 90 - East 180 - South 270 - East |
double | No |
GET /search/types
/search/types returns the list of search’s known InterpTypes (See list above under includeOnly
parameter). These are independent of the region.
GET /search/poiCategories
/search/poiCategories returns the list of search’s acceptable POI categories for filtering. These are dependent on the region.
GET /search/countries
/search/countries returns the list of search’s acceptable countries for filtering. These are dependent on the region.
GET /search/states
/search/states returns the list of search’s acceptable states for filtering. These are dependent on the region.
Example Queries
/search?query=1 independence way, princeton, nj, 08540&countries=US&states=NJ, NM
/search?query=123&maxResults=101
/search?query=1¤tLonLat=-74.600291,40.360869
/search?query=1 independence way, princeton, nj, 08540¤tLonLat=-74600291,40360869
/search?query=1 independence way, princeton, nj, 08540&excludeResultsFor=POI,POItype
/search?query=1 independence way, princeton, nj, 08540&poiCategories=Airport, bank, CAT scales
/search?query=1 independence way, princeton, nj, 08540&countries=US
/search?query=1 independence way, princeton, nj, 08540&countries=US&countryType=ISO
/search?query=1 independence way, princeton, nj, 08540&states=NJ
/search?query=40.3559242765905,-74.451975067144&includeTrimblePlaceIds=true
Fielded Search
You can also use keywords within a search string to help narrow your results. The keywords available are: housenumber
(or hn
), route
(or rt
), street
, county
, city
, zip
, splc
, fullpostcode
, fpc
, poi
, state
, and country
.
Example
/search?query=49 Easton Ave New Brunswick state:NJ
Adding the keyword “state” forces “NJ” to be interpreted as a state, and it ensures no other term in the string can be interpreted as a state.
By adding quotation marks, multiple search terms can be grouped together with a keyword.
Example
/search?query=49 street:"Easton Ave" New Brunswick state:NJ
This forces “Easton Ave” to be the only street match.
Single Search Response
The response will include a list of resulting locations. Below are descriptions of response parameters and error codes, as well as a sample request and response.
Response Parameters
Name | Description | Type |
---|---|---|
Address
| The details about the location. |
Complex |
Coords
| The details about the longitude/latitude. |
Complex |
Region
| Indicates the region of the location. |
Enum |
POITypeID
| The type of POI based on data defines. Ex: TypeID_TruckService = 144 or TypeID_MajorAirport = 101 |
Int |
PersistentPOIID
| A persistent ID between different versions of map data. |
Complex |
ResultType
| Indicates the type of match with the search string. |
Int 0 = Country 1 = State 2 = County 3 = City 4 = Zip 5 = SPLC 6 = Street 7 = RouteNumber 8 = RouteAlpha 9 = POI 10 = POIStreet 11 = FullPostCode 12 = POIType 13 = CrossStreet 14 = LatLon 15 = CustomPlace 16 = None |
ShortString
| Complete address that matches with the query string. |
string |
PlaceId
| Unique custom place or company id. |
Alphanumeric |
Err
| Refer the section on error codes. |
Int |
QueryConfidence
| The confidence level of the search results. Included in response only if request has include=Meta
|
Int |
TrimblePlaceId
| The identifier for a location in the Trimble MAPS Places database, which includes tens of thousands of commercial locations across North America that serve the transportation industry. This ID can be used to call additional information about the Place using our Places API. |
String |
PlaceName
| The name of the Place in the Trimble MAPS database. |
String |
SiteName
| The name of the Site in the Trimble MAPS database. |
String |
Address
Name | Description | Type |
---|---|---|
StreetAddress
| The house number and street name. Ex: 1 Independence Way |
string |
City
| The name of the city. Ex: Princeton |
string |
State
| The two letter state abbreviation. Ex: NJ |
string |
Zip
| The postal code or ZIP. Ex: 08540 |
string |
County
| The county or jurisdiction. Ex: Mercer |
string |
Country
| The code for the country. |
string |
CountryFullName
| The full name of the country. |
string |
SPLC
| The Standard Point Location code to use in place of street/city/state/zip. |
string |
Coords
Name | Description | Type |
---|---|---|
Lat
| Latitude |
string |
Lon
| Longitude |
string |
Error Codes
Error Code | Error |
---|---|
0 | OK |
1 | NoGlobals |
2 | GeoGlobals |
3 | GridGlobals |
4 | POIGlobals |
5 | InvalidID |
6 | NotImplemented |
7 | NoQuery |
8 | NoQueryAfterFormatting |
9 | NoAllowedInterps |
10 | InvalidNumResultsRequested |
11 | NoDataLoaded |
12 | DataLoad |
13 | BadData |
14 | FileMissing |
15 | FolderIndexOOB |
16 | CityFileClientOOB |
17 | OOB |
18 | FileIO |
19 | Memory |
20 | NoPreviousSearch |
21 | ThreadStart |
22 | ThreadEnqueue |
23 | ObjectNotInitialized |
24 | POIData |
25 | Internal |
26 | QueryIsNotUTF8 |
27 | InvalidQuery |
28 | InvalidInterpRankingSettings |
29 | InvalidParameters |
30 | SynonymVersionMismatch |
31 | SynonymAmbiguityMismatch |
32 | FrequenciesDisabled |
33 | TimeOut |
34 | InvalidInputCountry |
35 | InvalidInputState |
36 | StateIsNotPartOfCountry |
37 | IndexVersionMismatch |
38 | InvalidLatLonForRegion |
39 | Unknown |
Sample Request
Here is an example for the query “1 Independence Way”.
The URL for the request is:
https://singlesearch.alk.com/na/api/search?authToken=<APIKEY>&query=1%20independence%20way
Sample Response
The full response for the above request is:
{
"Err": 0,
"Locations": [
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Cranston",
"State": "RI",
"StateName": "Rhode Island",
"Zip": "02921",
"County": "Providence",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "41.78962",
"Lon": "-71.500717"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Cranston, RI, US, Providence 02921"
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Jersey City",
"State": "NJ",
"StateName": "New Jersey",
"Zip": "07305",
"County": "Hudson",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "40.688876",
"Lon": "-74.073607"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Jersey City, NJ, US, Hudson 07305"
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Brenham",
"State": "TX",
"StateName": "Texas",
"Zip": "77833",
"County": "Washington",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "30.249221",
"Lon": "-96.363437"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Brenham, TX, US, Washington 77833"
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Marblehead",
"State": "MA",
"StateName": "Massachusetts",
"Zip": "01945",
"County": "Essex",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "42.498706",
"Lon": "-70.851927"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Marblehead, MA, US, Essex 01945"
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Princeton",
"State": "NJ",
"StateName": "New Jersey",
"Zip": "08540",
"County": "Mercer",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "40.360393",
"Lon": "-74.599275"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Princeton, NJ, US, Mercer 08540"
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Edgewater",
"State": "NJ",
"StateName": "New Jersey",
"Zip": "07020",
"County": "Bergen",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "40.809012",
"Lon": "-73.984801"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Edgewater, NJ, US, Bergen 07020"
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Falmouth",
"State": "ME",
"StateName": "Maine",
"Zip": "04105",
"County": "Cumberland",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "43.761429",
"Lon": "-70.325684"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Falmouth, ME, US, Cumberland 04105"
}
]
}
Sample Request with Metadata
Here is an example for the query “1 Independence Way”.
The URL for the request is:
https://singlesearch.alk.com/na/api/search?authToken=<APIKEY>&query=1%20independence%20way&include=Meta
Sample Response with Metadata
{
"Err": 0,
"ErrString": "OK",
"QueryConfidence": 3,
"TimeInMilliseconds": 94,
"GridDataVersion": "GRD_ALK.NA.2020.01.15.5.1.1",
"CommitID": "copilot-10.16.0.1-661-g99fa6054be8: 04/09/2020 14:48",
"Locations": [
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Cranston",
"State": "RI",
"StateName": "Rhode Island",
"Zip": "02921",
"County": "Providence",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "41.78962",
"Lon": "-71.500717"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Cranston, RI, US, Providence 02921",
"GridID": 6393356,
"LinkID": 394,
"Percent": 2126
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Jersey City",
"State": "NJ",
"StateName": "New Jersey",
"Zip": "07305",
"County": "Hudson",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "40.688876",
"Lon": "-74.073607"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Jersey City, NJ, US, Hudson 07305",
"GridID": 10008076,
"LinkID": 198,
"Percent": 354
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Brenham",
"State": "TX",
"StateName": "Texas",
"Zip": "77833",
"County": "Washington",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "30.249221",
"Lon": "-96.363437"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Brenham, TX, US, Washington 77833",
"GridID": 16623332,
"LinkID": 246,
"Percent": 2033
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Marblehead",
"State": "MA",
"StateName": "Massachusetts",
"Zip": "01945",
"County": "Essex",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "42.498706",
"Lon": "-70.851927"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Marblehead, MA, US, Essex 01945",
"GridID": 58972684,
"LinkID": 424,
"Percent": 2840
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Princeton",
"State": "NJ",
"StateName": "New Jersey",
"Zip": "08540",
"County": "Mercer",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "40.360393",
"Lon": "-74.599275"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Princeton, NJ, US, Mercer 08540",
"GridID": 15414796,
"LinkID": 885,
"Percent": 5000
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Edgewater",
"State": "NJ",
"StateName": "New Jersey",
"Zip": "07020",
"County": "Bergen",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "40.809012",
"Lon": "-73.984801"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Edgewater, NJ, US, Bergen 07020",
"GridID": 8250892,
"LinkID": 396,
"Percent": 6642
},
{
"Address": {
"StreetAddress": "1 Independence Way",
"City": "Falmouth",
"State": "ME",
"StateName": "Maine",
"Zip": "04105",
"County": "Cumberland",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "43.761429",
"Lon": "-70.325684"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 6,
"ShortString": "1 Independence Way, Falmouth, ME, US, Cumberland 04105",
"GridID": 11520524,
"LinkID": 122,
"Percent": 838
}
]
}
Sample Request with includeTrimblePlaceIds=true
Here is an example query using coordinates for a Costco distribution center in New Jersey.
The URL for the request is:
https://singlesearch.alk.com/na/api/search?authToken=<APIKEY>&query=40.3559242765905,-74.451975067144&includeTrimblePlaceIds=true
Sample Response with includeTrimblePlaceIds=true
{
"Err": 0,
"Locations": [
{
"Address": {
"StreetAddress": "",
"City": "Monroe Township",
"State": "NJ",
"StateName": "New Jersey",
"Zip": "08831",
"County": "Middlesex",
"Country": "US",
"CountryFullName": "United States",
"SPLC": null
},
"Coords": {
"Lat": "40.355924",
"Lon": "-74.451975"
},
"Region": 4,
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 14,
"ShortString": "Monroe Township, NJ, US, Middlesex 08831"
},
{
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 17,
"ShortString": "0xztR_iLMWM0eZWyV3GACigA, Costco #175",
"TrimblePlaceId": "0xztR_iLMWM0eZWyV3GACigA",
"PlaceName": "Costco #175",
"SiteName": "Costco #175"
},
{
"POITypeID": 0,
"PersistentPOIID": -1,
"SiteID": -1,
"ResultType": 17,
"ShortString": "0x4Y4CTmYr6kauPugLT9k4zg, Costco #265",
"TrimblePlaceId": "0x4Y4CTmYr6kauPugLT9k4zg",
"PlaceName": "Costco #265",
"SiteName": "Costco #175"
}
]
}