Single Search API

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).

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}

1. In order to get a valid URL to the single search service, replace {region} above with one of the supported regions: NA, WW, EU
2. You will need a valid API key to replace {your-api-key}
3. Replace {endpoint} with one of the endpoints below

Endpoints

GET /search

/search is the main geocoding URL and supports the parameters below.

These additional parameters below are only applicable when performing a reverse geocode search using latitude/longitude coordinates.

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=CA, US, GL&states=NJ, NM
• /search?query=123&​maxResults=101
• /search?query=1&​currentLonLat=-74.600291,40.360869
• /search?query=1 independence way, princeton, nj, 08540&​currentLonLat=-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), county, city, zip, splc, fullpostcode, fpc, poi, state, and county.

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

Address

Coords

Error Codes

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",
        "SPLC": null
      },
      "Coords": {
        "Lat": "41.789618",
        "Lon": "-71.500716"
      },
      "Region": 4,
      "POITypeID": 0,
      "PersistentPOIID": -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",
        "SPLC": null
      },
      "Coords": {
        "Lat": "40.688876",
        "Lon": "-74.073607"
      },
      "Region": 4,
      "POITypeID": 0,
      "PersistentPOIID": -1,
      "ResultType": 6,
      "ShortString": "1 Independence Way, Jersey City, NJ, US, Hudson 07305"
    },
    {
      "Address": {
        "StreetAddress": "1 Independence Way",
        "City": "Princeton",
        "State": "NJ",
        "StateName": "New Jersey",
        "Zip": "08540",
        "County": "Mercer",
        "Country": "US",
        "SPLC": null
      },
      "Coords": {
        "Lat": "40.360399",
        "Lon": "-74.59927"
      },
      "Region": 4,
      "POITypeID": 0,
      "PersistentPOIID": -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",
        "SPLC": null
      },
      "Coords": {
        "Lat": "40.809012",
        "Lon": "-73.984801"
      },
      "Region": 4,
      "POITypeID": 0,
      "PersistentPOIID": -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",
        "SPLC": null
      },
      "Coords": {
        "Lat": "43.761429",
        "Lon": "-70.325684"
      },
      "Region": 4,
      "POITypeID": 0,
      "PersistentPOIID": -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

{
  "TimeInMilliseconds": 10,
  "Locations": [
    {
      "GridID": 15414796,
      "Percent": 5000,
      "LinkID": 271,
      "POITypeID": 0,
      "ResultType": 6,
      "ShortString": "1 Independence Way, Princeton, NJ, Mercer 08540",
      "Address": {
        "StreetAddress": "1 Independence Way",
        "City": "Princeton",
        "State": "NJ",
        "Zip": "08540",
        "County": "Mercer",
        "Country": "US",
        "SPLC": null
      },
      "Coords": {
        "Lat": "40.360399",
        "Lon": "-74.59927"
      },
      "Region": 4
    }
  ],
  "GridDataVersion": "GRD_ALK.NA.2017.01.12.11.1.1",
  "QueryConfidence": 1,
  "ID": 8394,
  "Err": 0,
  "ErrString": "OK"
}

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"
    }
  ]
}