Searching and Geocoding Addresses using Free-form Input
The PTV xLocate service enables you to search for and geocode addresses using complete or partial address information in a free-form way. Using the 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. (Representational State Transfer 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.) or 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. APIs, it is very simple to integrate this functionality.
Benefits
The PTV xLocate service enables you to use one single input field in your application to form your geocoding requests. Using a single input field for geocoding has the following benefits:
- Address information can be entered in a seamless way. An incremental search implemented on top can provide direct feedback.
- Input can be specified in an unstructered way, free of any form. Postal addresses may be specified partially or in full.
- There is no need to use specific input formats depending on
- regions (e.g. street or house number position may vary across different countries)
- specific types of input (e.g. street first, full address).
Prerequisites
Check if the following prerequisites are fulfilled before you start with the use case:
- Installed and licensed PTV xLocate service
- Installed PTV map data
Programming Guide
The following code sample uses the locations REST endpoint, which is accessed via the URL pattern
http://hostname:50000/services/rest/XLocate/locations/{address}
where address contains the free-form input.
Similar functionality is provided by web service searchLocations operation via SOAP SOAP (Simple Object Access Protocol) is a protocol specification for exchanging structured information in the context of Web services. XML is used for definition of the message format, and it is based on other application layer protocols, like Hypertext Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP). or JSON JSON (JavaScript Object Notation) is an open standard format for which human-readable text is used to transmit information consisting of attribute–value pairs. It is the first-address data format used for asynchronous browser/server communication (AJAX)..
Examples
The following sample illustrates the basic steps that are necessary to geocode addresses via the web service API:
// Define the location we are searching. var addressLine = "19 Rue Beaumont Luxemburg"; // Search for the address. xlocate.searchLocations({ "$type": "SearchByTextRequest", "text": addressLine}, searchCompleted); // Process the results. function searchCompleted(response, exception) { if (response.results instanceof Array) { print('Geocoding succeeded and yielded ' + response.results.length + ' result(s).'); } else { print('Geocoding did not succeed.'); } }Using the REST API the same functionality looks like this:
// Define the location we are searching. var input = "19 Rue Beaumont Luxemburg"; // Set up the URL for searching the above input. Input string requires URI encoding. var searchUrl = xServerUrl + '/services/rest/XLocate/locations/' + encodeURIComponent(input); // Display initial status. print('Please wait while PTV xLocate Server is searching for "' + input + '" ...'); // We use jQuery to send the request. Be sure to reference jQuery for this to work. $.ajax(searchUrl).always(function(response) { // The request is expected to return a response of type LocationsResponse with response.results containing the result records. if (response.results instanceof Array) { print('Geocoding succeeded and yielded ' + response.results.length + ' result(s).'); } else { print('Geocoding did not succeed.'); } });The next sample enhances the sample above by additionally displaying the geocoding results on a map. Each result address is represented by a marker on the map. By clicking a marker the corresponding address is shown as a tool tip.
The PTV xLocate service returns results through LocationsResponse, which holds an Array of SearchLocationsResult elements. Each SearchLocationsResult element has a location field, which in turn contains the actual address and its coordinates. For additional convenience, the location element provides a textual representation of the address in a single string though its formattedAddress field. Through its matchQuality field, the SearchLocationsResult also provides a totalScore field indicating the degree to which the input was matched as a percentage (currently only part of the experimental API). formattedAddress and totalScore are used to build the display string in the sample below.
Related Topics
- The Basic Geocoding Showcase provides an extended code sample for geocoding address input and displaying results on a map. Also based on Leaflet, this shopwcase uses additional UI elements and implements an incremental search.
- For more details on interactive maps, please refer to Displaying a Basic Interactive Map.