Batch Geocoder API Developer's Guide

Input data

The input data for batch geocoding requests consists of the addresses to be geocoded, while 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.

Data size limits

All input data must comply with the following rules:

The number of lines submitted for geocoding or reverse geocoding is limited to 1,000,000 (excluding the header)
The maximum request size is limited to 2GB uncompressed

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

You must provide the input data in a delimited file format. The field delimiter can be any of the following characters:

| (pipe, URL encoded: %7C)
; (semicolon, URL encoded: %3B)
: (colon, URL encoded: %3A)
, (comma, URL encoded: %2C)
\t (tab, URL encoded: %5Ct)

Batch geocoding input data

Just as with Geocoder API, the address data can be structured (qualified) or unstructured (freeform). The following is an example of 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|searchText|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

The column recId is optional. If provided, it is repeated in the output for reference. 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,searchText,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

A single double quote (") per input line is regarded as a regular character. The following example shows a correct input line.

recId,searchText,country 
1,O"Farell St San Francisco,USA

In comparison, the example shown below is invalid. There is no end quote, resulting in four instead of the three fields per input line the service expects.

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

Basic input fields

Input field names are not case sensitive. When no record ID is supplied (field name recId), then the Batch Geocoder generates it as a sequence starting from 1. recIds may contain numeric or alphanumeric characters. If all recIds of a batch job are numeric, then the Batch Geocoder sorts the results in numeric order. In all other cases the Batch Geocoder sorts the results in alphabetic order. If you want to retain the input order of the records in the result, do not provide a column with the field name recId.

Table 1. General
`recId`	record identifier

Table 2. Address, freeform
`searchText`	single line query string, may be enclosed in double quotes

Table 3. Address, qualified
`street`	Street name, which can include suite, apt and floor information.
`houseNumber`	The house number or house name.
`district`	Subdivision level below the city. Depending on the admin hierarchy in a country, this level may not be applicable (for example, USA: n/a, Germany: Ortsteil).
`city`	City name, as appropriate for the country specified (for example, USA: City, Germany: Gemeinde).
`postalCode`	Postal code defined by the government of the country.
`county`	Second subdivision below the country. Depending on the admin hierarchy in a country this level may not be applicable (for example, USA: County, Germany: Kreis).
`state`	First subdivision level below the country. You can specify a `state` using full or abbreviated notation. Use the category appropriate for the specified country (for example, USA: State, Germany: Bundesland).
`country`	Country either using the country code (3 bytes, ISO 3166-1-alpha-3) or the country name. To avoid ambiguity, we recommend you use the 3-letter ISO code and not spell out the name to avoid misspellings and issues with country names in different languages.

Table 4. Geographic coordinates, reverse geocoding
`mode`	One of three values: `retrieveAddresses` - Search for the closest street address or addresses `retrieveAreas` - Retrieve the administrative area information for the position provided in the request `trackPosition` - Retrieve street information based on a position and bearing
`pos`	`pos=lat,lon,bearing` Use with `mode=trackPosition` A position with latitude, longitude, and bearing. Bearing expresses the direction in which an asset is heading in degrees starting at true north and continuing clockwise around the compass. North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees.
`prox`	`prox=lat,lon,radius` Use with `mode=retrieveAddresses` and `retrieveAreas` A type of SpatialFilter. A spatial filter limits the search for any other attributes on the request. Proximity specifies a circle to search using a latitude, a longitude, and a radius in meters.

Table 5. Miscellaneous
`locationattributes`	query parameter needed for requesting special output fields, for instance, `mapReferenceID` and `mapReferenceMapVersion` are activated using the value `mr` for `locationattributes`
`addressattributes`	query parameter to request special address attributes
`responseattributes`	query parameter to request special response attributes
`mapview`	map view to be used for geocoding
`countryfocus`	country focus to be used for geocoding
`bbox`	bounding box filter to be used for geocoding
`prox`	proximity filter to be used for geocoding
`locationid`	location id of the requested object
`additionaldata`	additional query parameters to be used for geocoding
`gen`	generation parameter to be used for geocoding

For the detailed description of these parameters, see the https://developer.here.com/documentation/geocoder/dev_guide/topics/includes.html.

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. Here is an example of a reverse batch geocoding input file:

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

Basic input fields

When no record ID is supplied (field name recId), then the Batch Geocoder generates it as a sequence starting from 1. recIds may contain numeric or alphanumeric characters. If all recIds of a batch job are numeric, then the Batch Geocoder sorts the results in numeric order. In all other cases the Batch Geocoder sorts the results in alphabetic order. If you want to retain the input order of the records in the result, do not provide a column with field name recId.

Table 6. General
`recId`	record identifier

Table 7. Location
`prox`	proximity filter to be used for geocoding, includes three items of data: latitude, longitude and radius as a number of meters

Empty input data set

The service accepts requests even when the input file does not contain data to process. For example, when an input file contains only the header line, but no addresses to geocode or location coordinates to reverse geocode.

In such a case, the service accepts the job and generates a response as shown in Job submitted and accepted. Upon completion of the job, the output file contains the header line, but no results.