Characteristic
Short description
Geocoding is the process of turning address related information, e.g. given as a single search string, into known locations and coordinates.
Use
The coordinates obtained from the geocoding result entries can be used as waypoint
A waypoint is a geographic location used to specify start, destination and possible stopovers for a route. in a route A route corresponds to a path of a vehicle through the underlying transport network. The main attributes of a route are the distance and the time that the vehicle travels along the path. calculation.
Detailed Consideration
Geocoding with a Single Input Field
When input data is not separated into individual fields for postal code, city or street, all input data of an address can be combined into one single field. This is especially useful for interactive searches. Geocoding with a single input field can be done with the xLocate service endpoints
- searchLocations (Web Service A web service represents a communication technology applied in computer networks. It provides an interface described in a machine-processable format, for example WSDL. API)
in combination with the corresponding request type
SearchByTextRequest
and
- locations (REST REST (Representational State Transfer) represents a World Wide Web paradigm, consisting of constraints to the design of components which results in a better performance and maintainability. API)
Geocoding with a Structured Address Input
When using structured input fields, each field is associated a dedicated meaning, resulting in a more efficient search for geographical objects with a better quality. Geocoding with a structured input can be done with the xLocate service endpoint
- searchLocations (Web Service API) in combination with the request type SearchByAddressRequest
Result List
If the request succeeds, the response consists of a list of records, each containing the actual address and its coordinates.
- The list is omitted if no matching record is found, and the list size is limited to keep the server responsive even with bad input data.
- In order to return a short list, the search algorithm will prefer more general record types over more detailed ones if they match the same input words (e.g. return a locality instead of listing all its postal codes).
- The records have fields such as the postal code, city or street name, and a special type field to indicate the flavor or type of the record.
Record Fields
Each returned record can have one or more coordinates and address fields, e.g.:
| coordinates | address fields |
|---|---|
|
|
The availability and content of these fields depend on the record type and the API version used. Please check the API documentation to see which fields are supported in the API version you are using.
Record Types
Record types are returned in the field type.
Common record types are
- locality (e.g. Boston)
- postal code (e.g. 10557 Berlin)
- street section (e.g. Avenue des Champs-Élysées, 75008 Paris)
- address (e.g. 10 Downing St, London SW1A 2AA) .
Exceptions
The single-field search is limited by an internal timeout: if a request takes very long to process, it will be aborted. This may typically happen if the request contains many words with spelling errors or contradictions between them. In such an event, a ProcessingTimedOutFault will be thrown.
Good to know
Showcase
In the showcase, colors are used to indicate record types as explained by the map legend in the top right corner of the map window.
Depending on the record type, some of the record fields may be populated or not, e.g. the house number field makes no sense for results of type locality.
Languages
If the data contains names in different Languages (e.g. Roma, Rome, Rom) you can use any of those strings to find it.
The returned result, however, will always be returned in the language spoken in that country/region.
If you give a language in the request profile The request profile is a partial profile provided in object form for a specific request. Any parameter which is not set in the request profile will be taken from the stored profile.'s
mapLanguage
property, then the names will be returned in that language, if available in the data.
Note that the mapLanguage in the stored profile A stored profile is a (partial) profile persisted as an XML file. is currently ignored by the xLocate service.
Related Topics
| Showcase | Search addresses |
| Integration Sample | Searching free-form address input |
| Integration Sample | Searching structured address input |