Batch Geocoder API Developer's Guide

Request parameters

All parameter listed in the below table are optional. Exceptions are tagged as "Required"

Table 1. Request Parameters for Job Submission
Parameter Type Description
indelim Char Field delimiter in the input data.
mailto String

Email address where a job completion mail is sent to.

A mail notification is sent on completion of the Batch job. The mail address it not used for any other purposes.

outdelim Char, Required Field delimiter in the output data.
outcols Enumeration, Required List of columns to return in the output.
outputcombined Boolean, Required If true, the output of successful and unsuccessful (empty response) Geocoder queries are combined into a single result_YYYYMMDD-HH-MM__out.txt file. If false, they are returned in two separate files
  • result_YYYYMMDD-HH-MM__out.txt
  • result_YYYYMMDD-HH-MM__err.txt
action String Type of request, one of
  • run run a previously uploaded job
  • status inquire about job RequestID
  • cancel cancel job RequestID
header Boolean If true, a header row is included before the results in the output.
maxresults Integer Limits the number of items in the response. Default value is 10.
minresults Integer Ignore the specified radius until minResults results are found. Default is 0. Supported for Reverse Geocode mode=retrieveAreas and mode=retrieveAddresses.
allowUnknownInputColumns Boolean

Option to ignore unknown input columns. Column names that the Batch Geocoder API does not recognize will be ignored.

Note: This option disables spell checking. For example, if the input column "city" is misspelled as "citty" this column will be ignored. Without allowUnknownInputColumns parameter or with allowUnknownInputColumns=false, the Batch Geocoder API returns an invalid input data error.

If combined with includeInputFields all ignored fields are also included in the output.

Default value is false.

includeInputFields Boolean

Option to include all input fields in the output. In case of naming conflicts with other output columns, input fields are prefixed by "in:". Examples: searchText|in:city|in:postalCode|in:country.

Default value is false.

includeInvalidInput Boolean

Option to include invalid input lines in the output file. Invalid input lines are for example lines with a wrong number of fields. This option works for invalid lines in a similar way as outputcombined for Geocoder empty results. Together with outputcombined=true, for each input line one corresponding line in the output file exists.

Note: The Batch Geocoder API ignores this option if the input file contains a column recId. The output is then sorted by recId, but for invalid lines the Batch Geocoder API cannot be sure which of the fields the recId is.

Regardless of this option, invalid input lines are always reported in the error file result_YYYYMMDD-HH-MM__inv.txt.

Default value is false.

The following parameters can be used to define default parameters for each Geocoding request in the input.

Consult the Geocoder API Developer's Guide documentation for a detailed description.

Table 2. Request Parameters for Geocoding
Parameter Type Description
locationattributes Enumeration Query parameter to request special location attributes. For details, see Customizing the Response with Attribute Switches in the Geocoder API Developer's Guide.
addressattributes Enumeration Query parameter to request special address attributes. For details, see Customizing the Response with Attribute Switches in the Geocoder API Developer's Guide.
responseattributes Enumeration Query parameter to request special response attributes. For details, see Customizing the Response with Attribute Switches in the Geocoder API Developer's Guide.
mapview GeoBoundingBoxType Map view to be used for geocoding
countryfocus String Country focus to be used for geocoding
bbox GeoBoundingBoxType Bounding box filter to be used for geocoding
prox GeoProximityType Proximity filter to be used for geocoding
locationid String Location id of the requested object
gen Integer Generation parameter to be used for geocoding
additionaldata Enumeration List of KeyValuePairType elements as a generic container for attaching additional information to the request. See details in the Additional Data Parameter chapter in the Geocoder API Developer's Guide.
language Enumeration The preferred languages, in descending order, in which internationalized text attributes should be returned. RFC 4647 standard.
level String Target match level of the search result. One of [country, state, county, city, district, postalCode]. Only valid in combination with gen=2 or higher.
sortby String Sort results by distance (default), population count, or size (approximate area size). One of [distance, population, size]. Currently only supported for Reverse Geocode mode=retrieveAreas.
politicalview String

xs:string (3 bytes, ISO 3166-1-alpha-3)

Specify the political view. Available territories will be seen through the point of view of this country. If this parameter is not specified the neutral international view is made available, where territories may have unresolved claims.

For a complete list of supported views, see the appendix Political Views in the Geocoder API Developer's Guide.

Note: These parameters will be taken as default parameters for the geocoding query. Default values can be overridden by non-empty input cells in the input line. E.g. a request sent with language=en-US will add the language parameter with values en-US to each Geocoder request, unless the input data contains a column language with a non-empty string value. In this case the parameter's value is taken from the input line. Note that a value with one or more spaces is not an empty string value.
Table 3. Request Parameters for Result Retrieval
Parameter Type Description
outputcompressed Boolean If true (the default) the result files available at
  • jobs/{REQUEST_ID}/result
  • jobs/{REQUEST_ID}/errors
  • jobs/{REQUEST_ID}/no-matches
are compressed in a zip file.

If false the above endpoints will return uncompressed text files (HTTP Content-Type text/plain)