GuidesAPI Reference
Guides
  1. Batch API v7 Developer Guide
  2. HERE Batch API v7 Concepts

Submitting a batch job

Your initial submission must conform with the Input data guidelines. You can use the optional input fields to provide additional information to control how the job is run. The HERE Batch API v7 handles the geocoding, reverse geocoding and lookup requests asynchronously. For more information on the lifecycle of a request, see Request lifecycles and jobs. For more details about the result of a job, see Reading batch request output.

To retrieve the output of a successful batch request, you must follow the steps below:

  1. Upload your data with a POST request to the resource /jobs.
  2. Using the jobId value contained in the response to your data upload request, start the job with a PUT /batch/jobs/<jobId>/start request if it is not automatically started.
  3. Check the status of the job with a GET request. You can only download the results when the job status is completed.
  4. Using the jobId value contained in the response to your data upload request, download the results by sending a GET /batch/jobs/<jobId>/results request or a GET /batch/jobs/<jobId>/errors to download an error report.

When you submit a request with wget or cURL, check the field names (for example &outputColumns=recId,…) and the field delimiter in the request for both the input and the output. wget and cURL return the response "400 Bad Request" if there is an issue or when the delimiter defined as query parameter does not match the delimiter in the input file. Both, wget and cURL, need a content type to be specified in the header. You can upload a compressed file in gzip format when setting the respective Content-Encoding header. For more information, see Gzip compression.

Parameters

The only required parameter is serviceHrn which defines the backend API as Geocode, Reverse Geocode or Lookup. inputDelimiter and inputColumns define the format of the input file. For more information, see the Input data.

Similarly, outputDelimiter and outputColumns define the output format. For more information, see the Output data.

📘

Note

The delimiter of input and output can be different.

There are also parameters unrelated to the backend API, but used within HERE Batch API v7. startJob starts the job right after upload (default) or waits for a request to PUT /batch/jobs/<jobId>/start. tag helps grouping and finding certain jobs again. billingTags is used to split and group costs on your invoice. The notificationIds is about receiving a push in case the status changes. See the separate Notifications section for details.

wget

For wget use the header

Content-Type: text/plain

Example of a geocoding request:

echo "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
" > addresses.txt

wget --header="Content-Type: text/plain; charset=UTF-8" \
     --header="Accept: application/json" \
     --header="Authorization: Bearer ${YOUR_BEARER_TOKEN}" \
     --post-file=addresses.txt \
"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"

cURL

If you use cURL, be sure to use the following header

Content-Type: text/plain

Example of a geocoding request:

echo "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
" > addresses.txt

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" \
  --header "Authorization: Bearer ${YOUR_BEARER_TOKEN}" \
  --header  'accept: application/json' \
  --header  'Content-Type: text/plain' \
  --data-binary @addresses.txt
📘

Note

Instead of bearer token you can also pass an ApiKey as query parameter. Add &apiKey=${YOUR_API_KEY} at the end of the URL.

📘

Note

%7C is the pipe char | %3A is a colon :

Related information

Updated this month