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.32/locations/{address}
since 2.0
Searches for locations matching a given address, specified as a free-form text input.
| 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. |
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. |
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.
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. |
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. |
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. |
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. |
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. |
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. |
Search for locations using structured address input.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| address | Address | yes | - | 2.5 | The address to search. |
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. |
Search for addresses using structured coordinate input.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| coordinate | Coordinate | yes | - | 2.12 | The input coordinate to search. |
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. |
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. |
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. |
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.
Specifies the representation of the country in a request or response.
Distinguishes different types of Locations.