Use geocoding with HERE Batch API v7

The user wants to request a set of complete addresses corresponding to a data set of query strings.

This quick start only shows the first step in this process. For examples of the other steps, see Get job status and Get job results.

Request

The POST request below includes the serviceHrn 'hrn:here:service::olp-here:search-geocode-7' (URL-encoded: serviceHrn=hrn%3Ahere%3Aservice%3A%3Aolp-here%3Asearch-geocode-7) that indicates the request is for geocoding. Also specify the HTTP-Header Content-Type=text/plain.

POST https://batch.search.hereapi.com/v7/batch/jobs
?apiKey={YOUR_API_KEY}
&serviceHrn=hrn%3Ahere%3Aservice%3A%3Aolp-here%3Asearch-geocode-7
&inputDelimiter=%7C
&outputDelimiter=%7C
&outputColumns=positionLat,positionLng,addressLabel,addressHouseNumber,addressStreet,addressDistrict,addressCity,addressPostalCode,addressCounty,addressState,addressCountryCode

The following POST body includes the query string q and country to search in:

recId|q|country
0001|Invalidenstraße 116 10115 Berlin|DEU
0002|Am Kronberger Hang 8 65824 Schwalbach|DEU
0003|425 W Randolph St Chicago IL 60606|USA
0004|One Main Street Cambridge MA 02142|USA

With cURL and store jobId in environment. Variable YOUR_API_KEY has to be set:

resp=$(curl --request 'POST' \
  "https://batch.search.hereapi.com/v7/batch/jobs?serviceHrn=hrn%3Ahere%3Aservice%3A%3Aolp-here%3Asearch-geocode-7&inputDelimiter=%7C&outputDelimiter=%7C&outputColumns=position%7Ctitle%7Cid&startJob=true&outputType=csv&apiKey=${YOUR_API_KEY}" \
  --header 'accept: application/json' \
  --header 'Content-Type: text/plain' \
  --data 'recId|q|country
0001|Invalidenstraße 116 10115 Berlin|DEU
0002|Am Kronberger Hang 8 65824 Schwalbach|DEU
0003|425 W Randolph St Chicago IL 60606|USA
0004|One Main Street Cambridge MA 02142|USA')
echo $resp | jq
jobId=$(echo $resp | jq -r '.id')
echo Job Id is: $jobId

Response

The response contains a jobId. Use this jobId for all actions you want to perform on this job.

{
    "id": "<jobId>",
    "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
    "billingTags": [],
    "status": "submitted",
    "href": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>"
}

bash output:

$ echo $resp | jq
{
  "id": "<jobId>",
  "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
  "billingTags": [],
  "status": "queued",
  "href": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>"
}
$ echo Job Id is: $jobId
Job Id is: <jobId>

After starting the job, you can request the status of the job. See Get job status.

As soon as the status of the job is 'success', you can download the result of the batch job. For an example of how to download the results, see Get job results.

Result

The result will like this:

recId|seqNumber|seqLength|position|title|id
0001|1|1|(52.53086,13.38469)|Invalidenstraße 116, 10115 Berlin, Deutschland|here:af:streetsection:tVuvjJYhO86yd5jk1cmzNB:CgcIBCCE59BeEAEaAzExNg
0002|1|1|(50.16193,8.53361)|Am Kronberger Hang 8, Hillsite, 65824 Schwalbach am Taunus, Deutschland|here:af:streetsection:6cjWtEIO2t07E.pKRVV5bA:CgcIBCCa46pZEAEaATgiCEhpbGxzaXRl
0003|1|1|(41.88432,-87.63877)|425 W Randolph St, Chicago, IL 60606-1515, United States|here:af:streetsection:hdZ6xBRUraY46IQZCqZidD:CgcIBCDMlOElEAEaAzQyNQ
0004|1|1|(42.36225,-71.0803)|1 Main St, Cambridge, MA 02142-1517, United States|here:af:streetsection:k-3ojKsslOuU0B1PF4J4HD:CgcIBCCq3cJGEAEaATE

Request

Response

Result

Related information