Batch Geocoder API Developer's Guide

Input Data

Input data consists of the addresses to be geocoded. Your input must abide by the following limitations:
  • The number of lines to geocode is limited to 1,000,000 (excluding the header)
  • The maximum request size is limited to 2GB uncompressed
If the request exceeds these limitations, the request returns an error and the addresses 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)
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 the address as freeform with a country code qualifier using "|" as a delimiter.
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:
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. Below is an example where the delimiter is a comma and the input contains commas.
1,"Sturmstraße 8, 80687 München",DEU 
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.

1,O"Farell St San Francisco,USA
The input line below is invalid. The end quote is missing, resulting in four instead of the expected three fields per input line.
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 will generate one 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 simply do not provide a column with field name recId.

Table 1. General
recId identifies input address in the response
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


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.



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, e.g. 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, please consult the Geocoder API Developer's Guide.