Get started with HERE Batch API v7

This section outlines how to get started quickly using HERE Batch API v7 on the HERE platform:

📘

Note

This section provides information on the minimum setup required to quickly begin using HERE Batch API v7. For more detailed information on HERE account setup, project creation, service linking, app registration, and authentication, see the Identity & Access Management Developer Guide.

Get a HERE account

Obtain access to the HERE platform through your organization administrator's invitation or contact us to get started.

• If your company has already established a HERE platform organization, contact your organization admin who can invite you to join the organization.
• If your company hasn’t established a HERE platform organization yet, contact us.

Create an app

You will need an app to be used with HERE Batch API v7.

Follow this steps to create an app:

1. Sign in to the HERE platform.
2. Open the Access Manager from the launcher.
3. On the Apps tab, click Register new app and provide the requested information.
4. Click Register. The platform creates a new app with a unique app ID.
5. On the Credentials tab, select API Keys and then click Create API key to generate a maximum of two API Keys for your application authentication credentials. The API key is created and displayed.

Run a job

The following example demonstrates how to create and start a job and download the result.

The input is a csv like file where the separator can be defined.

Each line represents one record and relates to one request to the backend.

New lines within a record are not supported.

The result is a similar csv like file where values from the backend response are mapped into columns.

To request the corresponding geocoordinates for a list of complete addresses, you must perform the following steps:

• Prepare the input file.
• Create a job and upload the input file.
• Wait until the geocoding process is completed. Alternatively, check the job status.
• Download the results.

Prepare input file

This example geocodes addresses and returns results in the language of the corresponding country.

Because the address structure is unknown, the request uses the free-text query with the q parameter.

The lang parameter defines the output language. For more information, see the Geocoder API.

The output has no defined order. To match each output line with its corresponding input, define a record id using the recId column.

Although the system can generate an id automatically, it's recommended to define it explicitly.

This is our input file:

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

The first line are the headers and the values are the input parameter for the geocode requests. (Except recId which is for HERE Batch API v7 internal use).

Create job

To create and run a job we send a POST request to /jobs endpoint with additional configuration as query parameter and some standard header.

The final request looks like this:

POST https://batch.search.hereapi.com/v7/batch/jobs?apiKey=${YOUR_API_KEY}&serviceHrn=hrn%3Ahere%3Aservice%3A%3Aolp-here%3Asearch-geocode-7
accept: application/json
Content-Type: text/plain

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

📘

Note

%3A is a colon :. The encoding is required as the unencoded character has a special meaning in URL context. Please review the documentation of your client if this encoding happens automatically. If yes, the parameter is encoded twice and won't work.

📘

Note

HERE Batch API v7 sets the limit parameter to 1 by default. We override this here for the sake of an example. See "Download result" section below.

The response to the above request includes the following high level elements:

• jobId that identifies the job created for the request which you can use to track the job progress and to request the results when the job is complete.
• The status of this job.
• The HRN of the backend service (hrn:here:service::olp-here:search-geocode-7)
• A self reference

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

📘

Note

When you create a job, it gets started by default. You can prevent it from starting immediately by creating the job with the parameter startJob=false. Then you can start the job with a later request at your desired time.

Check Job status

This is a tiny job. There is still some time for start-up and shut-down. We can just wait a few minutes or we check the status with the jobId from previous response.

See Job status list for details about possible states and there meaning.

GET  https://batch.search.hereapi.com/v7/batch/jobs/${jobId}?apiKey=${YOUR_API_KEY}
accept: application/json

Response:

{
  "id": "<jobId>",
  "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
  "billingTags": [],
  "status": "completed",
  "href": "https://batch.search.hereapi.com/v7/batch/jobs/JOB-3a81ce8e-612c-4e41-b468-103d766e3f9c",
  "created": "2024-12-11T10:59:05.937507Z",
  "started": "2024-12-11T10:59:16.794079Z",
  "ended": "2024-12-11T10:59:19.910476Z",
  "records": {
    "total": 4,
    "valid": 4,
    "invalid": 0,
    "processed": 4,
    "pending": 0,
    "succeeded": 4,
    "failed": 0
  },
  "resultsHref": "https://batch.search.hereapi.com/v7/batch/jobs/JOB-3a81ce8e-612c-4e41-b468-103d766e3f9c/results",
  "errorsHref": "",
  "outputType": "csv"
}

Status is completed and so we can download the result.

The status response has more details. There are:

• timestamps when the job was created, started and ended.
• counter about the records: total number, valid/invalid, processed, failed, etc.
• links to result and errors

See API reference for details.

Download result

After the job is completed, you can download the result:

GET https://batch.search.hereapi.com/v7/batch/jobs/<jobId>/results?apiKey=<ApiKey>' \
accept: text/plain

recId|seqNumber|seqLength|position|address|title
0001|1|1|(52.53086,13.38469)|Invalidenstraße 116, 10115 Berlin, Deutschland|Invalidenstraße 116, 10115 Berlin, Deutschland
0002|1|1|(50.16193,8.53361)|Am Kronberger Hang 8, Hillsite, 65824 Schwalbach am Taunus, Deutschland|Am Kronberger Hang 8, Hillsite, 65824 Schwalbach am Taunus, Deutschland
0003|1|2|(41.88432,-87.63877)|425 W Randolph St, Chicago, IL 60606-1515, United States|425 W Randolph St, Chicago, IL 60606-1515, United States
0003|2|2|(41.88426,-87.6152)|425 E Randolph St, Chicago, IL 60601, United States|425 E Randolph St, Chicago, IL 60601, United States
0004|1|1|(42.36225,-71.0803)|1 Main St, Cambridge, MA 02142-1517, United States|1 Main St, Cambridge, MA 02142-1517, United States

The first three columns are fixed. These are the recId to identify the related input line, seqNumber and seqLength. seqLength is the total number of results the related input line has. seqNumber is a counter of each of these lines.

In this example all but recId 0003 (425 Randolph St Chicago IL 60606) have just one result. For recId 0003 we see that there is a 'W' - West (reqNumber: 1) and 'E' - East (reqNumber: 2) Randolph St.

The other columns are the default for Forward Geocoding if no outputColumns parameter is set.