Input data

The input data is organized in records. A record is one line in the input file and represents one call to the related backend.

The input data for batch geocoding requests consists of the addresses to be geocoded.

The input data for reverse batch geocoding is a set of locations defined by the WGS-84 compliant latitude and longitude geocoordinates and a radius around each location.

The input data for lookup by id consists of Location ID as results of a geocoding or discover search. [//]: # (TODO: Mark this as important)

📘

Note

Usually only the best match is important. That's why HERE Batch API v7 sets the limit parameter to 1 by default. This can be overridden by adding an input column with a default value e.g. limit=5 as last column in inputColumns respectively fist line. See "Default Values" below.

Data size limits

The maximum request size is limited to 500MB uncompressed. One record is limited to 4KB. See Limits and performance for details.

A request exceeding these limits produces an error, and the addresses or locations are not processed.

Content Types

Currently only text/plain is supported.

This format is derived from CSV format with some differences:

• New line is not supported. Also not in a quoted cell. A new line always ends a record. Next line is a new record.

This could lead to errors if the next line does not have all required columns.

• The field delimiter can be any single character, but we recommend using one of the following:
  • | (pipe, URL encoded: %7C)
  • ; (semicolon, URL encoded: %3B)
  • : (colon, URL encoded: %3A)
  • , (comma, URL encoded: %2C)
  • \t (tab, use tab character in a file, URL encoded: %5Ct)
• To include the delimiter character within a cell value (instead of treating it as a delimiter), make sure the field value is enclosed in quotation marks.
• A quoted section starts and ends with the double quote character ". It can start or end anywhere within a cell.
• To put the double quote character " into the value
  • put double quotes around the value, so the section is quoted
  • put two double quotes into the quoted section.

📘

Note

This will be reduced to one in the output. You can quote the whole value between the delimiters, but quoting only around the double quote itself is also enough. Both approaches produce the same output. See the examples below.

Examples

The delimiter in all examples is a comma ,.

Escape a comma in value:

recId,q
001,"some, street"

The of q parameter will be: q=some, street The same output could be achieved with:

recId,q
001,some", "street

Escape a double quotes in value:

recId,q
001,"some, ""street"""

The output of q parameter will be: q=some, "street" Note the three double quotes at the end. The first two are converted into one double quote in the output, and the third ends the quoted section.

The same output can be achieved with:

recId,q
001,some, """"street""""

The two quoted sections in the q column and within both sections there is only one double quote escaped.

This example is organized as follows:

• The first double quote starts a quoted section.
• The next two double quotes is the escape sequence for one double quote in the output.
• The fourth double quote ends the quoted section.

The same repeats after the word "street".

Compressed data

Input data can also be sent as a gzip-compressed plain text file. See Gzip compression.

Default values

If you need to set one parameter for all records to the same value, set a default value in the header instead of repeating it in every line.

Place these headers at the end of the line so that record lines can end early. If the column with the default value appears in the middle of the line, insert an empty field by placing two delimiters next to each other.

To define a default value, write the header name followed by an equal character and then the default value. For example, to set the language parameter by default to German, set lang=de-DE.

This default value will be taken for missing or empty fields. You can still assign a value to override the default.

Example

The following example illustrates how to set a default for country to USA (country=USA), and the language to English (lang=en-US), but override this for some lines.

recId|q|country=USA|lang=en-US
1|425 W Randolph St, Chicago Illinois 60606 
2|31 St James Ave Boston MA 02116
3|31 St James Ave Boston MA 02116||de-DE
4|10115 Berlin Invalidenstrasse 117|DEU
5|10115 Berlin Invalidenstrasse 117|DEU|de-DE

Line 1 and 2 use the default values and are just two columns shorter.

In line 3 we want to set the lang parameter, but keep country on default. For this we have an empty field (||) followed by the lang values for this line de.

In line 4 we want the other way around, define the country as DEU, but keep default language. We just write DEU in country column and omit the rest.

In line 5 we override both. For this line both defaults are ignored.

Common input fields

Input field names are not case-sensitive.

Each record has an optional Record ID. If provided, it is repeated in the output for reference.

When no Record ID is supplied (field name recId), then one is generated. recId is of type String and should not be expected to be in any order.

The Record ID has to be unique within a Job.

Batch geocoding input data

Just as with Geocoder API, the address data can be structured (qualified) or unstructured (freeform). The following example shows an input file with free-form addresses with a country code qualifier using "|" as a delimiter.

The first line is a header that lists the names of the columns in the input file.

recId|q|country 
1|425 W Randolph St, Chicago Illinois 60606|USA 
2|31 St James Ave Boston MA 02116|USA 
3|10115 Berlin Invalidenstrasse 117|DEU

The following is an example of the same addresses in fully qualified form:

recId|street|city|postalCode|country
1|425 Randolph St|Chicago||USA
2|31 St James Ave|Boston|02116|USA 
3|Invalidenstrasse 117|Berlin|10115|DEU
4|One Main Street Cambridge MA 02142|USA|5

If you have an occurrence of the delimiter character in the data, you must enclose the data in double quotes. The example below illustrates a case where the delimiter is a comma and the input contains commas.

recId,q,country 
1,"Sturmstraße 8, 80687 München", DEU 
2,"Milano", ITA 
3,"Rom", ITA 
4,"Tecklenburger Straße, Westerkappeln 49492", DEU 
5,"425 W Randolph St Chicago, Illinois, 60606", USA

In comparison, the example shown below is invalid. The number of quotes is not balanced.

recId,q,country 
1,"Sturmstraße 8, 80687 München,DEU

Basic input fields

📘

Note

We build the qq parameter from these fields. It is also possible to provide the qq parameter directly in the defined format. If both, the qq parameter and one of the sub-parameter above are used, the qq parameter takes priority and the sub-parameters are ignored!

For a full list of input parameters for geocode endpoint see Geocoder API

Reverse batch geocoding input data

The input data for reverse batch geocoding must also be provided in a delimited file. The first line is a header that lists the names of the columns in the input file.

The following example shows a reverse batch geocoding input file:

recId|in
0001|52.505308,13.327739,250
0002|49.917257,8.486488,250
0003|51.119593,7.399356,250
...   

HERE Batch API v7 supports the Geocoder format for a circle circle:{latitude},{longitude};r={radius}.

To simplify the input structure, a sequence of three numbers—two -- decimals and one integer -- separated by any of the following delimiters ([/;, :|=]) is also supported.

This is shown in the example.

Basic input fields

📘

Note

Either "at" or "in" are required, but they cannot be used both at once.

For a full list of input parameters for revgeocode endpoint see Geocoder API

Lookup By ID

The input data for lookup by ID batch request has to be provided like the others, in a delimited file. The first line is the header containing the name of the columns in the input file. The following example shows a lookup with optional parameters lang and politicalView.

recId,id,lang,politicalView
01,here:pds:place:238aabd1-5ac31a4d053a00ddb7555829ec6feb2c,de-DE,ARG
02,here:pds:place:238aabd1-5ac31a4d053a00ddb7555829ec6feb2c,de-DE,GBR
...

Basic input fields

For a full list of input parameters for lookup endpoint see Geocoder API

Empty input data set

Empty input is not allowed. The service with return a HTTP 400 error with a related message when creating a job without at least one valid record.