Skip to main content

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:

  1. Authenticate your Trimble Maps API key and receive a JSON Web Token (JWT). All subsequent requests must pass the JWT in the request header.
  2. Submit a POST request with your batch of queries. The service can support up to 50,000 queries per call.
  3. 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:

NameDescriptionData TypeRequired
apiKeyYour API key
string
Y
refreshTokenUsed to get a new access token when the token generated by passing your API key expires.
Alphanumeric
N

Response

NameDescriptionData Type
access-tokenThe JWT used to authenticate other API calls.
Alphanumeric
token-typeThis value will always be Bearer.
string
expires_inThe number of seconds until the token expires.
Integer
refresh_tokenWhen your token expires, refresh_token can be used to get a new access token.
Alphanumeric
scopeThis 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:

KeyValue
Authorizationbearer {the JWT you created earlier}

POST Body:

NameDescriptionData TypeRequired
urlThe target URL used for each of the batch API calls.
string
Yes
requestsAn array of strings, each containing the parameters used for a single call.array of
string
Yes

Response

NameDescriptionData Type
jobIdThe unique identifier for your job used in subsequent calls
string
hrefProvided 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

NameDescriptionData TypeRequired
jobIdThe Id for the batch job that was returned by the POST request.
string
Y
offsetThe number of requests to skip when returning results. This is used to page or index into the results.
integer
N
limitThe 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

NameDescriptionData TypeRequired
urlThe url used to make all of the requests.array of
Responses
N
responsesA list of responses to each query in the requested range.array of
Responses
N
nextOffsetAn optional offset value which will allow you to get the next set. Omitted if there are none remaining.
integer
N
nextAn optional URL to get the next set with the same limit. Omitted if there are none remaining.
integer
N
errorsAn 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.

CategoryDescription
InformationThis doesn’t indicate a problem but may be useful.
UrgentIn order to correctly interpret the results, you need to be aware of the reported issue.
CriticalThe results could not be returned as requested or at this time.

Example Error Messages

CategoryMessageDescriptionCode
InformationThe requested range extends beyond the last request in the batchExplains why the number of requests returned is less than the limit100
UrgentNot all requested results are available at this time, the batch is still processingWe 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
CriticalThe 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
CriticalOffset cannot be greater than the number of requests in the batchWhile 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
CriticalThe offset cannot be negativeThe request list is a zero-based index.302
CriticalThe limit must be greater than 0It is an error to limit the number of requests returned to 0.303
CriticalResults are not available at this time, the batch is still processingWe 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

NameDescriptionData TypeRequired
jobIdThe Id for the batch job that was returned by the POST request.
string
Y
Last updated September 5, 2022.