Output data

The output can be either a column-based format using the provided delimiter or JSONL. Depending on the target service there are some default columns (see below). Additional columns are defined by the outputColumns parameter.

Each output line references the related input line by recId. If no reqId is provided in the input, it will be generated.

Column-Based

The output uses a CSV-like format, but you can define the column delimiter with the outputDelimiter parameter.

If the outputDelimiter is part of a value, the value is put in double quotes ".

If a certain field does not exist in a reponse, the related column is empty.

Arrays are difficult to represent in a column-based format. Some complex array structures can't be used at all.

When possible, the service combines array elements into a single field using a comma , or plus + as separator.

Standard Columns

The following columns are always present in the response. If they are missing in the outputColumns parameter, they are added by the system.

Default Columns

If the outputColumns parameter is empty or omitted at job creation time, the following default columns will be used as output format:

Customer defined columns

With the outputColumns parameter it is possible to define your own list of output columns. This overrides the default columns.

The standard columns will always be added, if missing.

If we look at the documentation of the related backend service e.g. Geocode, the output is in JSON format. Take the json path to the requested field and concatenate the keys in camelCase.

HERE Batch API v7 does not support backend service features that are subject to additional pricing. The retrieval of speed limit data is one example.

Special Case

For fields with coordinates, there are is optional special output formats.

Please note that access is an array. As such accessLat and accessLng will also be a formatted as array: <lat>,<lat>

Examples

As an example for the default way of creating output fields, we'll look at an excerpt of the response sample of a successful reverse geocoding request:

{
  ...,
  "address": {
    "label": "string",
    "countryCode": "string",
    "countryName": "string",
    "stateCode": "string",
    "state": "string",
    "countyCode": "string",
    "county": "string",
    "city": "string",
    "district": "string",
    "subdistrict": "string",
    "street": "string",
    "streets": [
      "string1",
      "string2"
    ],
    "block": "string",
    "subblock": "string",
    "postalCode": "string",
    "houseNumber": "string",
    "building": "string"
  },
  ...
}

From this snippet you can infer, e.g. an output field of addressCountryCode, or a field of addressCity.

In the example below, the complete output for the example input data in Input data can be found. 'outputColumns' parameter for this is recId|seqNumber|seqLength|positionlat|positionlng|addressHouseNumber|addressStreet|addressCity|addressPostalCode|addressCountry as also the first line of the output shows.

recId|seqNumber|seqLength|position|address|title
1|1|1|(41.88432,-87.63877)|425 W Randolph St, Chicago, IL 60606-1515, United States|425 W Randolph St, Chicago, IL 60606-1515, United States
2|1|1|(42.35093,-71.07152)|31 St James Ave, Boston, MA 02116-2975, United States|31 St James Ave, Boston, MA 02116-2975, United States
3|1|1|(52.53041,13.38527)|Invalidenstraße 117, 10115 Berlin, Deutschland|Invalidenstraße 117, 10115 Berlin, Deutschland

For the detailed description of possible output fields see HERE Geocoding and Search API v7

JSONL (ALPHA)

JSONL is a flavor of JSON where the 'L' stands for "line". With this format only a line is valid JSON.

There are no array brackets at the beginning and end and no comma as element separator at the end of each line.

To parse this format, read one line and pass it to your JSON parser. This approach supports streamed processing and reduces memory usage, since it doesn't require loading the entire file at once.

Unlike column-based output, JSONL links each line to a single input line and its corresponding backend response. An envelope is put around the backend response with recId property referencing the input line and results array with the backend response.

Projection (ALPHA)

To reduce the output file size, you can return a partial JSON response instead of the full response.

For this outputFilter parameter is used to define single properties or full sub objects.

Multiple values can be separated by comma ,.

Each part of the response JSON that should be mapped to the result is defined as json path.

The definition is case-sensitive.

Examples

The following example assumes that only id, title, position, and label (formatted address) are needed.

All properties, except the label, are located at the top level of the response object. The label property is nested inside the address object.

To extract these fields, set the outputFilter parameter outputFilter=position,title,id,address.label.

Taking the Input data from before, the result will be:

{"recId":"1","results":[{"position":{"lat":41.88432,"lng":-87.63877},"title":"425 W Randolph St, Chicago, IL 60606-1515, United States","id":"here:af:streetsection:hdZ6xBRUraY46IQZCqZidD:CgcIBCDMlOElEAEaAzQyNQ","address":{"label":"425 W Randolph St, Chicago, IL 60606-1515, United States"}}]}
{"recId":"2","results":[{"position":{"lat":42.35093,"lng":-71.07152},"title":"31 St James Ave, Boston, MA 02116-2975, United States","id":"here:af:streetsection:ER45TeNFspfeURmIX7YnpD:CggIBCDT9YLfAhABGgIzMQ","address":{"label":"31 St James Ave, Boston, MA 02116-2975, United States"}}]}
{"recId":"3","results":[{"position":{"lat":52.53041,"lng":13.38527},"title":"Invalidenstraße 117, 10115 Berlin, Deutschland","id":"here:af:streetsection:tVuvjJYhO86yd5jk1cmzNB:CgcIBCCf2912EAEaAzExNw","address":{"label":"Invalidenstraße 117, 10115 Berlin, Deutschland"}}]}

For better readablity here the fist line pretty printed:

{
  "recId": "1",
  "results": [
    {
      "position": {
        "lat": 41.88432,
        "lng": -87.63877
      },
      "title": "425 W Randolph St, Chicago, IL 60606-1515, United States",
      "id": "here:af:streetsection:hdZ6xBRUraY46IQZCqZidD:CgcIBCDMlOElEAEaAzQyNQ",
      "address": {
        "label": "425 W Randolph St, Chicago, IL 60606-1515, United States"
      }
    }
  ]
}

Please note, that the label property remains nested inside the address object, but it's the only property extracted from that object.

The position is the full sub object.

📘

Note

The default limit=1 applies, so HERE Batch API v7 returns only one result per input. Unlike column-based output, increasing the limit doesn't change the number of lines. Instead, the service includes all results in a single line within the results array.

Related information

• Special case: No match