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

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

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

NameDescriptionData TypeRequired
authTokenProvided API KeyYes
queryString indicating the text to search forstringYes
maxResultsLimits search results by the specified number. Must be a value between 1 and 100.IntNo
currentLonLatThe current longitude and latitude, where longitude and latitude are either decimal or integer coordinates.ComplexNo
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.
stringNo
includeOnlyA 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.)stringNo
poiCategoriesA comma-separated list of Point of Interest (POI) category names by which you want to filter all POI results.stringNo
countriesA comma-separated list of country codes by which you want to filter all results. It defaults to ISO format.stringNo
countryTypeThe standard for country abbreviations: ISO, FIPS, GENC2, and GENC3.stringNo
statesA comma-separated list of state abbreviations by which you want to filter all results.stringNo
includeSet 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.)stringNo
useCustomPlacesIf 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.booleanNo
separateHNSets whether the house number should be returned as a separate field from the rest of the street address. Default is false.booleanNo
getAllHNRangesIf set to true, all potential house number ranges will be returned for a particular street match. Default is false.booleanNo

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

Results

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

NameDescriptionType
AddressThe details about the location.Complex
CoordsThe details about the longitude/latitude.Complex
RegionIndicates the region of the location.Enum
POITypeIDThe type of POI based on data defines.
Ex: TypeID_TruckService = 144 or TypeID_MajorAirport = 101
Int
PersistentPOIIDA persistent ID between different versions of map data.Complex
ResultTypeIndicates 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
ShortStringComplete address that matches with the query string.string
PlaceIdUnique custom place or company id.Alphanumeric
ErrRefer the section on error codes.Int
QueryConfidenceThe confidence level of the search results. Included in response only if request has include=MetaInt

Address

NameDescriptionType
StreetAddressThe house number and street name.
Ex: 1 Independence Way
string
CityThe name of the city.
Ex: Princeton
string
StateThe two letter state abbreviation.
Ex: NJ
string
ZipThe postal code or ZIP.
Ex: 08540
string
CountyThe county or jurisdiction.
Ex: Mercer
string
CountryThe name of the countrystring
SPLCThe Standard Point Location code to use in place of street/city/state/zip.string

Coords

NameDescriptionType
LatLatitudestring
LonLongitudestring

Error Codes

Error CodeError
0OK
1NoGlobals
2GeoGlobals
3GridGlobals
4POIGlobals
5InvalidID
6NotImplemented
7NoQuery
8NoQueryAfterFormatting
9NoAllowedInterps
10InvalidNumResultsRequested
11NoDataLoaded
12DataLoad
13BadData
14FileMissing
15FolderIndexOOB
16CityFileClientOOB
17OOB
18FileIO
19Memory
20NoPreviousSearch
21ThreadStart
22ThreadEnqueue
23ObjectNotInitialized
24POIData
25Internal
26QueryIsNotUTF8
27InvalidQuery
28InvalidInterpRankingSettings
29InvalidParameters
30SynonymVersionMismatch
31SynonymAmbiguityMismatch
32FrequenciesDisabled
33TimeOut
34InvalidInputCountry
35InvalidInputState
36StateIsNotPartOfCountry
37IndexVersionMismatch
38InvalidLatLonForRegion
39Unknown

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"
}
Last updated November 2, 2019.