The location resolution service is used to resolve a name or substring of a name to a list of possible locations. This service has been designed to be called every time the end-user types a letter (e.g. using ajax), to get an updated list of likely possibilities which can then be presented to the user, as they type.
Request
<ResolveLocationRequest>
<text>Lon</text>
<maxOptions>10</maxOptions>
<language>EN</language> <!-- e.g. English -->
<showSubLocations>true</showSubLocations> <!-- showSubLocations is an optional parameter, assumed false if not provided. If true, then the response will contain sub locations that relate to any locations that match the text supplied. For example, if the text matches a city name, all of the related airports will also be returned in the response. Sub location will have an extra attribute 'parentId' which identifies which location it is a sub location of -->
</ResolveLocationRequest>
Response
<ResolveLocationResponse>
<!-- Returns a list of all the possible locations, in order of relevance -->
<locations>
<location id=”43” type=”city” code=”LON” country=”GB” countryName="United Kingdom" cityName="London"/>London, United Kingdom</location>
<location id=”44” type=”airport” code=”LHR” country=”GB” countryName="United Kingdom" cityName="London" airportName=”Heathrow”/>London Heathrow Airport (LHR)</location>
<location id=”45” type=”place” country=”GB” countryName="United Kingdom"/>Uxbridge, London, United Kingdom</location>
<location id="46" type="island" country="GB" countryName="United Kingdom">Londonium island</location>
<location id="47" type="country" country="LO" countryName="Republic of Londonium">The Republic of Londonium</location>
<location id="48" type="poi" country="GB" countryName="United Kingdom">Big Ben, United Kingdom</location>
.......
</locations>
</ResolveLocationResponse>
Note that new location types may be added at any time without notice. Your application should handle this appropriately.
A 'poi' is a point of interest.
If ‘type’ is city or airport, a 'code' will always be supplied. A ‘place’ will never have a code.
For the simplest implementation, the attributes of the locations can be ignored and the contents of the location elements can be displayed directly to the user. In this example the dropdown presented to the user would contain:
London, United Kingdom
London Heathrow Airport (LHR)
Uxbridge, London, United Kingdom
The locations will be listed in an appropriate order, considering not only their size, but also their type (e.g. cities first).
[Note, each of the location items in the response will also contain latitude and longitude attributes: latitude="51.47115" longitude="-0.45649". These are not considered to be useful and are only supplied temporarily to facilitate the submission of Fast API locations to the exisiting API for searches. A nearest city attribute has also been temporarily added for this reason nearestCityCode="LON" ]