xlocate

XLocate Operations

SOAP/JSON

Synchronous API

since 2.0
Operation Name Request Type Response Type Since Description
searchLocations SearchLocationsRequest LocationsResponse 2.0 Searches for locations matching a given address
searchLocationsInBulk SearchLocationsBulkRequest LocationsBulkResponse 2.5 For each element of a list of addresses, searches for locations matching that address.
SOAP/JSON

Asynchronous API

since 2.5
Operation Name Request Type Response Type Since Description
startSearchLocationsInBulk SearchLocationsBulkRequest Job 2.5

This is the asynchronous version of searchLocationsInBulk.

Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchLocationsBulkResponse. If the job ended with status FAILED, fetchLocationsBulkResponse throws the exception that occurred during calculation.

fetchLocationsBulkResponse JobRequest LocationsBulkResponse 2.5

Fetches results of type LocationsBulkResponse for the given job. If the calculation ended with an exception, fetchLocationsBulkResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown.

watchJob WatchRequest Job 2.5

Returns the status of the given job.

This operation behaves exactly like the watchJob operation of the xRuntime service.

stopJob JobRequest Job 2.5

Attempts to stop a running job. If the status of the job changes to SUCCEEDED, preliminary results can be fetched, if available.

This operation behaves exactly like the stopJob operation of the xRuntime service.

deleteJob JobRequest Job 2.5

Attempts to delete a running job. If successful, the returned job will have state DELETED.

This operation behaves exactly like the deleteJob operation of the xRuntime service.

REST

locations

URL format: /services/rest/XLocate/2.33/locations/{address}
since 2.0

Searches for locations matching a given address, specified as a free-form text input.

Path Parameter Name Type Since Description
address String 2.0 The input address.
Query Parameter Name Type Default Since Description
mapLanguage String - 2.10 The language used for geographic names that are part of the map. The default x-ptv-DFT means that names are given in the language spoken in that country or region.
Response Type Description
LocationsResponse Response object.
XServerException Default exception for all xServer operations. See subtypes of XServerFault for details.

Types

Represents the address of a geographical object. Where a string, such as a city or street name, is available in multiple languages, it is returned in the default language specified by the object's location, i.e. in which country it is located. Because addressing schemes vary strongly between countries, most fields are optional.

Field Name Type Required Default Since Description
country String no - 2.5 The country. In a response, it is represented by its full name (not abbreviated or encoded) unless a different representation is requested via SearchOptions.outputCountryType.
state String no - 2.5 The name of the principal country subdivision which the address belongs to (for example, a state in the USA, or a canton in Switzerland).
province String no - 2.17 The name of the second-level country subdivision which the address belongs to (for example, a county in the UK, or a province in Italy).
postalCode String no - 2.0 The postal code of the address.
city String no - 2.0 The city of the address, i.e. the highest entity at the communal level which the address belongs to.
district String no - 2.8 The district of the address, i.e. the entity below city.
subdistrict String no - 2.8 The subdistrict of the address, i.e. the entity below district.
street String no - 2.0 The street of the address.
houseNumber String no - 2.0 The house number of the address.

AddressScores

used by MatchQuality
since 2.7

The scores for the fields of the result Address. Only present for fields that were given in the input Address.

Field Name Type Required Default Since Description
country Percent (Double) no - 2.7 The score for the returned country.
state Percent (Double) no - 2.7 The score for the returned state.
province Percent (Double) no - 2.17 The score for the returned province.
postalCode Percent (Double) no - 2.7 The score for the returned postal code.
city Percent (Double) no - 2.7 The score for the returned city.
district Percent (Double) no - 2.8 The score for the returned district.
subdistrict Percent (Double) no - 2.8 The score for the returned subdistrict.
street Percent (Double) no - 2.7 The score for the returned street name.
houseNumber Percent (Double) no - 2.7 The score for the returned house number.

CountryFallbackLimitation

extends ResultLimitation
since 2.22

This result limitation indicates that allowedCountries contains a country subdivision code that cannot be used like this due to the available data, and that instead the enclosing country code was used. In such cases, results are constrained to the country, rather than only the subdivision.

Field Name Type Required Default Since Description
requestedSubdivisionCode String yes - 2.22 The country subdivision code that was requested in allowedCountries, but cannot be used for filtering.
fallbackCountryCode String yes - 2.22 The enclosing country that is used as a fallback instead.

Location

used by SearchLocationsResult
since 2.0

Represents a geographical object in terms of its position and its address.

Field Name Type Required Default Since Description
referenceCoordinate Coordinate yes - 2.0

The actual position of the object itself, such as the rooftop of a building, the center of a street, or the reference point of a city.

In rare cases (when missing in the map data) this may not be available for a building address. In such a case, there will be a roadAccessCoordinate.

Please refer to the documentation of waypoints for more information on how best to use this position in a route calculation.

roadAccessCoordinate Coordinate no - 2.0

A position on or very close to a road network segment that marks the entry to the object. Available only for objects which represent buildings with a complete address and only if present in the data.

The road from which the object can be accessed is not necessarily the road which is closest to the object. When using the location as the input to a route calculation, pass the roadAccessCoordinate to the RouteLocation for best results.

Please refer to the documentation of waypoints for more information on how to use this position best in a route calculation.

address Address yes - 2.0 The address of the object.
formattedAddress String no - 2.1 A single string representing the address, typically consisting of the street, house number, postal code, city, and country. The precise format may differ based on what is appropriate for the address.

LocationsBulkResponse

extends ResponseBase
used by XLocate
since 2.5

Response type for bulk geocoding requests.

Field Name Type Required Default Since Description
responseItems LocationsBulkResponseItem[] 0..* - 2.5 List of search results corresponding to the list of input addresses to search.

LocationsBulkResponseItem

used by LocationsBulkResponse
since 2.5

The result of one element of a bulk search: either a list of SearchLocationsResults, or an exception if one was thrown.

Field Name Type Required Default Since Description
results SearchLocationsResult[] 0..* - 2.5 The individual results corresponding to one input object, ordered by relevance. May be empty if the input could not be matched with the available map data.
searchException SuppressedXServerException no - 2.17 Exception that occurred while searching, if any.

LocationsResponse

extends ResponseBase
used by XLocate
since 2.0

Response type for geocoding requests.

Field Name Type Required Default Since Description
results SearchLocationsResult[] 0..* - 2.0 The individual results for the request, ordered by relevance. May be empty if the request could not be matched with the available map data.

MatchQuality

used by SearchLocationsResult
since 2.5

Indicates how well a result matches the search request.

Field Name Type Required Default Since Description
totalScore Percent (Double) no - 2.7 Indicates the overall match quality for a geocoding request. 100 (percent) represents a perfect match between the input and the result.
addressScores AddressScores no - 2.7 The respective match qualities for each field of the result Address.
distance Distance (Double) no - 2.12 The spatial distance between the result and the input coordinate of a reverse geocoding request.

SearchByAddressBulkRequest

extends SearchLocationsBulkRequest
since 2.5

Search for locations using a list of structured address inputs.

Field Name Type Required Default Since Description
addresses Address[] 1..* - 2.5 The list of addresses to search.

SearchByAddressRequest

extends SearchLocationsRequest
since 2.5

Search for locations using structured address input.

Field Name Type Required Default Since Description
address Address yes - 2.5 The address to search.

SearchByPositionBulkRequest

extends SearchLocationsBulkRequest
since 2.12

Search for locations using a list of coordinate inputs.

Field Name Type Required Default Since Description
coordinates Coordinate[] 1..* - 2.12 The list of coordinates to search.

SearchByPositionRequest

extends SearchLocationsRequest
since 2.12

Search for addresses using structured coordinate input.

Field Name Type Required Default Since Description
coordinate Coordinate yes - 2.12 The input coordinate to search.

SearchByTextBulkRequest

extends SearchLocationsBulkRequest
since 2.5

Search for locations using a list of free-form text inputs.

Field Name Type Required Default Since Description
texts String[] 1..* - 2.5 The list of addresses to search.

SearchByTextRequest

extends SearchLocationsRequest
since 2.1

Search for locations using a free-form text input.

Field Name Type Required Default Since Description
text String yes - 2.1 The input address.

SearchLocationsBulkRequest (abstract)

extends RequestBase
extended by SearchByAddressBulkRequest, SearchByPositionBulkRequest, SearchByTextBulkRequest
used by XLocate
since 2.5

Abstract base type to search for locations using a list of input objects.

Field Name Type Required Default Since Description
searchOptions SearchOptions no - 2.12 Options for this request.

SearchLocationsRequest (abstract)

extends RequestBase
extended by SearchByAddressRequest, SearchByPositionRequest, SearchByTextRequest
used by XLocate
since 2.0

Abstract base type to search for locations using different input objects.

Field Name Type Required Default Since Description
searchOptions SearchOptions no - 2.12 Options for this request.

SearchLocationsResult

used by LocationsBulkResponseItem, LocationsResponse
since 2.0

Represents one of possibly several results of a geocoding request.

Field Name Type Required Default Since Description
location Location yes - 2.0 The location that was found.
matchQuality MatchQuality no - 2.5 The quality of the result relative to the search request.
type LocationType no - 2.5 The type of the result, sometimes also referred to as its detail level.

SearchOptions

used by SearchLocationsBulkRequest, SearchLocationsRequest
since 2.12

Options for a search request.

Field Name Type Required Default Since Description
outputCountryType CountryType no CountryType.NAME 2.12 Specifies the desired representation of the country in the response.
allowedCountries CountryCode[] (String[]) 0..* - 2.17 Specifies a list of country codes according to ISO 3166-1 alpha-2 or ISO 3166-2 if referring to a subdivision. The search will be restricted to these countries or subdivisions. When not specified or empty, all countries contained in the geocoding data will be included in the search. If a given subdivision code is not supported, only the respective country is considered in the search and a CountryFallbackLimitation is returned in the response.

TooManyInputWordsLimitation

extends ResultLimitation
since 2.28

This result limitation indicates that some input fields were too long, so the geocoder engine decided to drop some of the input words in order to return an answer in a timely manner.

Field Name Type Required Default Since Description
field String yes - 2.28 The field that had too many input words.
actualInputWords String yes - 2.28 Actual number of input words found.
maximumInputWords String yes - 2.28 Maximum number of input words allowed.
Enumeration

CountryType

used by SearchOptions
since 2.12

Specifies the representation of the country in a request or response.

Enumeration Value Since Description
ISO_3166_1_ALPHA_2 2.12 The country will be represented as ISO 3166-1 alpha-2, e.g. DE for Germany.
ISO_3166_1_ALPHA_3 2.12 The country will be represented as ISO 3166-1 alpha-3, e.g. DEU for Germany.
LICENSE_PLATE 2.12 The country will be represented by its license plate code, e.g. D for Germany.
NAME 2.12 The country will be represented by its name, not abbreviated nor encoded, in the requested language.
Enumeration

LocationType

used by SearchLocationsResult
since 2.5

Distinguishes different types of Locations.

Enumeration Value Since Description
LOCALITY 2.5 Represents a locality (town, city, or place).
POSTAL_CODE 2.5 Represents a postal code area.
STREET 2.5 Represents a street, or a section of a street.
EXACT_ADDRESS 2.5 An address that is contained exactly in the geocoding data.
INTERPOLATED_ADDRESS 2.5 An address that was interpolated from an address range.
UNSPECIFIED 2.5 Fallback value to be substituted for enumeration values which were added in an API version that is newer than the request version. When using the current API, this value will never be returned.

Diagrams

Operations Overview

Requests

Responses