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 RESTClosed 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 TransferClosed 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 serviceClosed 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.


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).


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


where address contains the free-form input.

Similar functionality is provided by web service searchLocations operation via SOAPClosed 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 JSONClosed 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)..


The following sample illustrates the basic steps that are necessary to geocode addresses via the web service API:

Using the REST API the same functionality looks like this:

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.