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 mispellings 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 paramters 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/rest-apis/documentation/batch-geocode.

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.