Single Search Batch

Contents

In addition to the GET interface that supports one location search at a time, the Single Search Geocoder is also available in a POST batch interface. The batch interface supports the same options and functionality as the GET interface but processes up to 50,000 location queries in a single request.

Workflow

Batch Single Search requires three steps:

Authenticate your Trimble Maps API key and receive a JSON Web Token (JWT). All subsequent requests must pass the JWT in the request header.
Submit a POST request with your batch of queries. The service can support up to 50,000 queries per call.
Retrieve the results of your request with a GET request to the service and the URL provided in the response to the POST call made in Step 2.

Service Authentication

Every web service request needs to be authenticated. You just need to use your API key to create a temporary JSON Web Token (JWT). This JWT is used to authenticate both the batch request, and the Single Search requests defined in the batch.

`POST` /api/authenticate

This service returns a JSON Web Token (JWT). This is a temporary token that authenticates and authorizes you to use other services.

Resource URL

https://singlesearch.alk.com/api/authenticate

Request

POST Body:

Name	Description	Data Type	Required
`apiKey`	Your API key	string	Y
`refreshToken`	Used to get a new access token when the token generated by passing your API key expires.	Alphanumeric	N

Response

Name	Description	Data Type
`access-token`	The JWT used to authenticate other API calls.	Alphanumeric
`token-type`	This value will always be `Bearer`.	string
`expires_in`	The number of seconds until the token expires.	Integer
`refresh_token`	When your token expires, `refresh_token` can be used to get a new access token.	Alphanumeric
`scope`	This value will always be `offline_access`.	string

Sample Request

{
  "apiKey": "{your API key}"
}

Sample Response

{
  "access_token": "{your token}",
  "token_type": "Bearer",
  "expires_in": 21600,
  "refresh_token": "15XDtk4RWj2Kz7fwCiBvRvMrPQNkFHSb",
  "scope": "offline_access"
}

Search Batch Service

Once you have a JWT, you can create new batches and download the responses for your batched requests using the endpoints described below.

`POST` /api/batch

To create a new batch, you will make a POST call to the the /api/batch endpoint. The POST body includes the URL for the target Single Search endpoint and requests—an array of parameter strings for each query. The endpoints and parameters are the same as those available for the traditional (one-request-at-a-time) Single Search service. They are described in detail here.

A batch can only target one Single Search endpoint. (The JWT will be passed on to the target service so you don’t need to authenticate each individual query.)

Resource URL

https://singlesearch.alk.com/api/batch

Authentication HEADER:

Key	Value
Authorization	bearer {the JWT you created earlier}

POST Body:

Name	Description	Data Type	Required
`url`	The target URL used for each of the batch API calls.	string	Yes
`requests`	An array of strings, each containing the parameters used for a single call.	array of string	Yes

Response

Name	Description	Data Type
`jobId`	The unique identifier for your job used in subsequent calls	string
`href`	Provided for convenience, the url used to GET the job results	string

Sample Request

{
  "url": "https://singlesearch.alk.com/na/api/search",
  "requests": [
    "query=1 independence way, princeton, nj, 08540&countries=US&states=NJ, NM",
    "query=1 independence way, princeton, nj, 08540&currentLonLat=-74600291,40360869",
    "query=1 independence way, princeton, nj, 08540&excludeResultsFor=POI,POItype",
    "query=1 independence way, princeton, nj, 08540&poiCategories=Airport, bank, CAT scales",
    "query=1 independence way, princeton, nj, 08540&countries=US",
    "query=1 independence way, princeton, nj, 08540&countries=US&countryType=ISO",
    "query=1 independence way, princeton, nj, 08540&states=NJ",
    "query=40.3559242765905,-74.451975067144&includeTrimblePlaceIds=true"
  ]
}

Sample Response

{
  "jobId": "dd9e6994-040c-4a4d-8097-208892acaee0",
  "href": "https://singlesearch.alk.com/api/batch?jobId=dd9e6994-040c-4a4d-8097-208892acaee0&offset=0&limit=0"
}

Search Batch Results

Once you have created a batch job you can make a GET request to retrieve the results. Depending on the size of the job and the search time for each query, results may be available in just a few minutes or they may take some time. Please see Ways to Improve Search Speed and Results for some tips.

`GET` /api/batch

Using the jobId and the url provided in the response to the POST call, make a GET call to get the results. The format of the url is /api/batch/{your jobId}. (Include your JWT in the Authorization header for each request.) There are also optional parameters to facilitate paging through results.

Resource URL

https://singlesearch.alk.com/api/batch/{jobId}?offset={zero based index}&limit={page limit}

Request Parameters

Name	Description	Data Type	Required
`jobId`	The Id for the batch job that was returned by the POST request.	string	Y
`offset`	The number of `requests` to skip when returning results. This is used to page or index into the results.	integer	N
`limit`	The maximum number of query results to return in this request. Combined with the `offset`, this can be used to more easily page through large numbers of results.	integer	N

Response

Name	Description	Data Type	Required
`url`	The url used to make all of the requests.	array of Responses	N
`responses`	A list of responses to each query in the requested range.	array of Responses	N
`nextOffset`	An optional offset value which will allow you to get the next set. Omitted if there are none remaining.	integer	N
`next`	An optional URL to get the next set with the same limit. Omitted if there are none remaining.	integer	N
`errors`	An optional list of errors with an indication of criticality and a text description. Omitted if no errors were encountered retrieving the batch. This doesn’t account for any errors in the `requests` in the batch.	array of Errors	N

Sample Request

{Authorization header}

https://singlesearch.alk.com/api/batch/5a3ef38e-6b51-4912-b451-050ecd51a2d2?offset=0&limit=10

Sample Response

{
  "url": "https://singlesearch.alk.com/na/api/search",
  "responses": [
    {
      "request": "countryType=ISO&getAllHNRanges=false&include=Meta&maxResults=20&query=BNSF%20-%20Cicero%2C%20IL&separateHN=false&includeTrimblePlaceIds=true",
      "statusCode": 200,
      "response": "{\"Err\":0,\"ErrString\":\"OK\",\"QueryConfidence\":1,\"TimeInMilliseconds\":0,\"GridDataVersion\":\"GRD_ALK.NA.2022.01.17.9.1.1\",\"CommitID\":\"pcmws-24.0.0.0-691-gb704bee7cb5: 02/02/2022 20:34\",\"Locations\":[{\"Address\":{\"StreetAddress\":\"5601 West 26th Street\",\"City\":\"Cicero\",\"State\":\"IL\",\"StateName\":\"Illinois\",\"Zip\":\"60804\",\"County\":\"Cook\",\"Country\":\"US\",\"CountryFullName\":\"United States\",\"SPLC\":null},\"Coords\":{\"Lat\":\"41.843436\",\"Lon\":\"-87.760653\"},\"StreetCoords\":{\"Lat\":\"41.843487\",\"Lon\":\"-87.760655\"},\"Region\":4,\"POITypeID\":1700,\"PersistentPOIID\":-1,\"SiteID\":-1,\"ResultType\":9,\"ShortString\":\"BNSF - Cicero, IL\",\"GridID\":232162316,\"LinkID\":347,\"Percent\":8759}]}"
    },
    .....
    {
      "request": "countryType=ISO&getAllHNRanges=false&include=Meta&maxResults=20&query=BNSF%20-%20Cicero%2C%20IL&separateHN=false&includeTrimblePlaceIds=true",
      "statusCode": 200,
      "Response": "{\"Err\":0,\"ErrString\":\"OK\",\"QueryConfidence\":1,\"TimeInMilliseconds\":0,\"GridDataVersion\":\"GRD_ALK.NA.2022.01.17.9.1.1\",\"CommitID\":\"pcmws-24.0.0.0-691-gb704bee7cb5: 02/02/2022 20:34\",\"Locations\":[{\"Address\":{\"StreetAddress\":\"5601 West 26th Street\",\"City\":\"Cicero\",\"State\":\"IL\",\"StateName\":\"Illinois\",\"Zip\":\"60804\",\"County\":\"Cook\",\"Country\":\"US\",\"CountryFullName\":\"United States\",\"SPLC\":null},\"Coords\":{\"Lat\":\"41.843436\",\"Lon\":\"-87.760653\"},\"StreetCoords\":{\"Lat\":\"41.843487\",\"Lon\":\"-87.760655\"},\"Region\":4,\"POITypeID\":1700,\"PersistentPOIID\":-1,\"SiteID\":-1,\"ResultType\":9,\"ShortString\":\"BNSF - Cicero, IL\",\"GridID\":232162316,\"LinkID\":347,\"Percent\":8759}]}"
    }
  ],
  "errors": []
}

Errors

The are three categories of errors that may be returned by the service.

Category	Description
Information	This doesn’t indicate a problem but may be useful.
Urgent	In order to correctly interpret the results, you need to be aware of the reported issue.
Critical	The results could not be returned as requested or at this time.

Example Error Messages

Category	Message	Description	Code
Information	The requested range extends beyond the last request in the batch	Explains why the number of requests returned is less than the limit	100
Urgent	Not all requested results are available at this time, the batch is still processing	We were able to get you some of the range you requested but there are some requests still pending. The `next` and `nextOffset` will indicate where you can pick up. This is important because when this happens you aren’t looking at pages of equal size and even numbering.	200
Critical	The `jobId` you have provided is either incorrect or no longer exists.	This may mean that the job is too old and has been deleted or it may be an incorrect `jobId`.	300
Critical	Offset cannot be greater than the number of requests in the batch	While it isn’t an error to extend the limit past the end of the requests, it is an error to ask for a starting index beyond the last request.	301
Critical	The offset cannot be negative	The request list is a zero-based index.	302
Critical	The limit must be greater than 0	It is an error to limit the number of requests returned to 0.	303
Critical	Results are not available at this time, the batch is still processing	We weren’t able to retrieve any of your the requested results, try again later.	304

Sample Response With Information

{
  "url": "https://singlesearch-aws-qa.alk.com/ww/api/search",
  "responses": [
    {
      "index": 0,
      "request": "query=1%20independence%20way,%20princeton,%20nj,%2008540&countries=US&states=NJ,%20NM",
      "statusCode": 200,
      "response": {
        "Err": 0,
        "Locations": [
          {
            "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.361007",
              "Lon": "-74.599268"
            },
            "Region": 4,
            "POITypeID": 1128,
            "PersistentPOIID": 2014,
            "SiteID": -1,
            "ResultType": 10,
            "ShortString": "Trimble Maps, 1 Independence Way, Princeton, NJ, US, Mercer 08540"
          },
          {
            "Address": {
              "StreetAddress": "1 Independence Way # 200",
              "City": "Princeton",
              "State": "NJ",
              "StateName": "New Jersey",
              "Zip": "08540-6638",
              "County": "Mercer",
              "Country": "US",
              "CountryFullName": "United States",
              "SPLC": null
            },
            "Coords": {
              "Lat": "40.361076",
              "Lon": "-74.599327"
            },
            "Region": 4,
            "POITypeID": 128,
            "PersistentPOIID": -1,
            "SiteID": -1,
            "ResultType": 10,
            "ShortString": "S&P Global, 1 Independence Way # 200, Princeton, NJ, US, Mercer 08540-6638"
          }
        ]
      }
    },
    {
      "index": 1,
      "request": "query=1%20independence%20way,%20princeton,%20nj,%2008540&%E2%80%8BcurrentLonLat=-74600291,40360869",
      "statusCode": 200,
      "response": {
        "Err": 0,
        "Locations": [
          {
            "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.361007",
              "Lon": "-74.599268"
            },
            "Region": 4,
            "POITypeID": 1128,
            "PersistentPOIID": 2014,
            "SiteID": -1,
            "ResultType": 10,
            "ShortString": "Trimble Maps, 1 Independence Way, Princeton, NJ, US, Mercer 08540"
          },
          {
            "Address": {
              "StreetAddress": "1 Independence Way # 200",
              "City": "Princeton",
              "State": "NJ",
              "StateName": "New Jersey",
              "Zip": "08540-6638",
              "County": "Mercer",
              "Country": "US",
              "CountryFullName": "United States",
              "SPLC": null
            },
            "Coords": {
              "Lat": "40.361076",
              "Lon": "-74.599327"
            },
            "Region": 4,
            "POITypeID": 128,
            "PersistentPOIID": -1,
            "SiteID": -1,
            "ResultType": 10,
            "ShortString": "S&P Global, 1 Independence Way # 200, Princeton, NJ, US, Mercer 08540-6638"
          }
        ]
      }
    }
  ],
  "responseCount": 2,
  "errors": [
    {
      "level": "Information",
      "code": 100,
      "message": "The requested range extends beyond the last request in the batch"
    }
  ]
}

Sample Responses With Errors

{
    "jobId": "dd9e6994-040c-4a4d-8097-208892acaee0",
    "href": "https://singlesearch.alk.com/api/batch?jobId=dd9e6994-040c-4a4d-8097-208892acaee0&offset=0&limit=0"
}

{
  "url": "https://singlesearch.alk.com/na/api/search",
  "responses": [],
  "nextOffset": 0,
  "next": "https://singlesearch.alk.com/api/Batch?jobid=1167e61a-2cfe-40a4-8a13-0f07e1c54654",
  "errors": [
    {
      "level": "Critical",
      "code": 304
      "message": "Results are not available at this time, the batch is still processing"
    }
  ]
}

{
  "errors": [
    {
      "level": "Critical",
      "code": 300,
      "message": "The jobId you have provided is either incorrect or no longer exists"
    }
  ]
}

`GET` /api/batch/jobs

The /api/batch/jobs endpoint allows you to get a list of all the jobs you have on the server. Jobs older than a few weeks may be deleted without notification.

Resource URL

https://singlesearch.alk.com/api/batch/jobs

Sample Response

{
"batches": [
    {
      "jobId": "0215e7b8-bec7-4035-83e7-562d0c7de684",
      "href": "http://singlesearch.alk.com/api/batch?jobId=0215e7b8-bec7-4035-83e7-562d0c7de684&offset=0&limit=0"
    },
    {
      "jobId": "04001675-083b-464b-a473-a7c2553fbd9c",
      "href": "http://singlesearch.alk.com/api/batch?jobId=04001675-083b-464b-a473-a7c2553fbd9c&offset=0&limit=0"
    }
}

`DELETE` /api/batch

Jobs are automatically deleted after a few weeks so you may never need to delete jobs but if you do need to delete a job, just use the delete HTTP method including the job id you would like to delete in the url as follows

Resource URL

https://singlesearch.alk.com/api/batch/{jobId}

Request Parameters

Name	Description	Data Type	Required
`jobId`	The Id for the batch job that was returned by the POST request.	string	Y

WEB SDK & APIs

INTERACTIVE MAPS

SOAP APIs (Web Services)

RESTful APIs (Web Services)

MOBILE SDK & APIs

COPILOT NAVIGATION

INTERACTIVE MAPS

Single Search Batch

Workflow

Service Authentication

POST /api/authenticate

Resource URL

Request

Response

Sample Request

Sample Response

Search Batch Service

POST /api/batch

Resource URL

Authentication HEADER:

POST Body:

Response

Sample Request

Sample Response

Search Batch Results

GET /api/batch

Resource URL

Request Parameters

Response

Sample Request

Sample Response

Errors

Example Error Messages

Sample Response With Information

Sample Responses With Errors

GET /api/batch/jobs

Resource URL

Sample Response

DELETE /api/batch

Resource URL

Request Parameters

`POST` /api/authenticate

`POST` /api/batch

`GET` /api/batch

`GET` /api/batch/jobs

`DELETE` /api/batch