Geocoder API Developer's Guide

Multi Reverse Geocode Resource

This section contains a list of all Multi Reverse Geocode request parameters. Multi Reverse Geocode requests are POST requests.

.../6.2/multi-reversegeocode.{format}?<parameter>=<value>...
Table 1. Request Parameters
Parameter Element
additionaldata

Key-value pairs that provide additional input to requests. See Additional Data Parameter for a full list. Key and value are separated using a ,. Multiple key-value pairs are separated using a ;:

additionaldata=<Key1>,<Value1>;<Key2>,<Value2>;...

Example:

additionaldata=PreserveUnitDesignators,true;
  IncludeZipAddon,true
addressattributes

A comma-separated list whose elements are present in the response data.

Enumeration [country, state, county, city, district, subdistrict, street, houseNumber, postalCode, addressLines, additionalData]

Abbreviated forms: [ctr, sta, cty, cit, dis, sdi, str, hnr, pst, aln, add]

Default in response: All except addressLines.

Note: The value names are case-sensitive.

app_id

xs:string

A 20 byte Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_id and app_code with every request.  To get an app_id assigned to you, please see Acquiring Credentials.

app_code

xs:string

A 20 byte Base64 URL-safe encoded string used for the authentication of the client application.

You must include an app_id and app_code with every request.  To get an app_id assigned to you, please see Acquiring Credentials.

gen

xs:int

The gen parameter enables or disables backward incompatible behavior in the API. Please see details and the generation history in chapter Different Generations of the Same API. The latest generation is always recommended. This is currently gen=9.

jsonattributes

xs:int

If set to 1, the first character of each JSON response attribute name is set to lower case. Default value is 0.

jsoncallback

xs:string

Specifies the name of a user-defined function used to wrap the JSON response.

language

LanguageCodeType

The preferred language of address elements in the result. Without a preferred language, the Geocoder will return results in an official country language or in a regional primary language so that local people will understand. Language code must be provided according to RFC 4647 standard. Note that the plural form of the parameter (languages) is supported as well. But only the last specified language in the list is used. All preceding language preferences are ignored at this time.

level

xs: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.
locationattributes

A comma-separated list whose elements are present in the response data.

Enumeration [address, mapReference, mapView, addressDetails, streetDetails, additionalData, adminIds, linkInfo, adminInfo, timeZone, addressNamesBilingual, related.nearByAddress]

Abbreviated forms: [ar, mr, mv, dt, sd, ad, ai, li, in, tz, nb, rn]

The adminIds switch is available with forward geocoding only.

In reverse geocoding results, adminIds are always present unless turned off through locationattributes=none. locationattributes=-adminIds has no effect on reverse geocoding results.

The related.nearByAddress switch is available with the trackPosition mode of reverse geocoding only.

Default in reverse geocoding response: address, mapView, additionalData, mapReference, adminIds.

Default in forward geocoding response: address, mapView, additionalData.

With mapReference link PVID, side of street, and admin area PVIDs are present in the response data. With adminIds, only admin area PVIDs are present.

Note: The value names are case-sensitive.

maxresults

xs:int

Defines the maximum number of items in the response structure, limiting the number of results included in each response page. When more results than the defined maximum are available, then these are returned on additional, separate pages. Each response structure (page) contains a handle to the next page. For example, maxresults=5 produces a maximum of 5 results per response page. If there are eight results in total, the first page contains five results and indicates that there is a second page with further results.

"metaInfo: {
  timestamp: 2012-05-10T15:10:06.227+0000
  nextPageInformation: 2
}"
minresults

xs:int

Indicates that the service is to ignore the specified radius until minResults results are found. The default is 0. Currently only supported for Reverse Geocode mode=retrieveAreas.

mode
One of five values:
  • retrieveAddresses - Search for the closest street address or addresses
  • retrieveAreas - Retrieve the administrative area information for the position provided in the request
  • retrieveLandmarks - Search for landmarks like parks and lakes in the proximity provided in the request
  • retrieveAll - Search for streets, administrative areas and landmarks. This mode aggregates the results of the three different modes in one call
  • trackPosition - Retrieve street and address information based on a position and bearing
pageinformation

xs:string

A key which identifies the page to be returned when the response is separated into multiple pages. Only relevant, if maxresults has been specified in a the original request and the request response indicates that there is a further page, for example:

"metaInfo: {
  timestamp: 2012-05-10T15:10:06.227+0000
  nextPageInformation: 2
}"
politicalview

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 please see the appendix Political View.

For any political view that is unsupported the Geocoder, falls back to the default view. For example, politicalview=USA or politicalview=FRA does not impact a response in any way.

responseattributes

A comma-separated list whose elements are present in the response data.

Enumeration [performedSearch, matchQuality, matchType, matchCode, parsedRequest]

Abbreviated forms: [ps, mq, mt, mc, pr]

Default in response: matchQuality, matchType

Note: The value names are case-sensitive.

sortby

xs: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. If population count is not available for an entity the service falls back to sort by area size.

strictlanguagemode

xs:boolean

  • True - if the value is available in the first language specified in the language parameter the attribute value is set directly in Address, Place, Location, and Category elements. Values in alternative languages are returned in the AlternativeValues element.
  • False - the best available attribute value based on the language priorities given in language parameter is returned directly in Address, Place, Location, and Category elements. No alternatives are returned.
token

xs:string

An URL-encoded Base64 string of typically (but not guaranteed to be) 24 bytes. The token is generated based on the user's app_id and received after the registration process of the application.

Parameter token is deprecated, use app_code instead.

Request Body

The HTTP Body in the POST request is used to specify the multiple reverse geocode request items. Each line in the HTTP body represents one reverse geocode request. The parameters passed in the query string serve as default values for any of those requests and can be overridden in the HTTP body. The format for every line follows the same syntax as the URL query string:
name1=value1&name2=value2

Request Header

You have to specify the content type for the HTTP request as plain/text or application/xml.

Example header when using wget
--header "Content-Type:application/xml; charset=utf8"