nokia.places.search.manager

Namespace Summary

The namespace nokia.places.search.manager defines functions that allow you to use the Places search service to search for places and to obtain search suggestions.

Table 1. Method Summary
Methods

findPlaces (params)

This function searches for places on the basis of the parameters specified by the caller.

findPlacesByCategory (params)

This function searches for places by category.

findRecommendations (params)

This function retrieves recommendations for the location indicated by the caller.

geoCode (params)

This method runs a geocoding query based on the arguments provided by the caller.

reverseGeoCode (params)

This method runs a reverse geocoding query based on the coordinates provided by the caller.

suggestPlaces (params)

This function retrieves suggestions that can be used with nokia.places.search.manager#findPlaces().

Namespace Description

The namespace nokia.places.search.manager defines functions that allow you to use the Places search service to search for places and to obtain search suggestions. Searches for places can be viewed as a preliminary step to selecting a particular place for which to retrieve detailed information, using the functions defined on nokia.places.manager.

Method Details

findPlaces(params)

This function searches for places on the basis of the parameters specified by the caller.

Parameters:
 
params:
{Object}
 
An object containing a number of parameters that define a search request:
  • {String} searchTerm - search term, required
  • {Function} onComplete - a function to be called when the request has been completed, required; the function must accept as arguments responseData, which is an instance of nokia.places.objects.SearchResponseView containing data returned by the Places back-end, and status, which is a {String} constant with the value of 'OK' to indicate success or 'ERROR' to indicate request failure or time-out
  • {Object} searchCenter - an object containing the latitude and longitude of the starting point for the search ({latitude:'',longitude:''}); optional, if provided, useGeoLocation is ignored
  • {Object} boundingBox - instead of search center boundingBox can be passed as a parameter. Bounding box is an object containing to coordinates topLeft and bottomRight ({topLeft: {latitude: '', longitude:''}, bottomRight: {latitude:'', longitude''}})
  • {Boolean} useGeoLocation - if true and searchCenter is not provided, Places search tries to use the W3C Geolocation API to get the client location and use it as the search center; if this parameter is false and searchCenter is not provided, a global search is executed
  • {Number} limit - the maximum number of results to be returned, optional
Returns:
 
 
The return value is made available asynchronously as arguments passed to the onComplete handler; the responseData argument contains a response view (nokia.places.objects.SearchResponseView). Directly function also returns a number which is the request ID and can be used to cancel/abort the current request with nokia.places.comm.data.abortRequest

 

findPlacesByCategory(params)

This function searches for places by category.

Parameters:
 
params:
{Object}
 
An object containing a number of parameters that define a search request:
  • {String} category - required; a string constant containing the valid category id which must be set to one of the following values:
    • eat-drink
    • going-out
    • sights-museums
    • transport
    • accommodation
    • shopping
    • leisure-outdoor
    • administrative-areas-buildings
    • natural-geographical
  • {Function} onComplete - required; a function to be called when the request has been completed; the function must accept as arguments responseData, which is an instance of nokia.places.objects.SearchResponseView containing data returned by the Places back-end, and status, which is a {String} constant with the value of 'OK' to indicate success or 'ERROR' to indicate request failure or time-out
  • {Object} searchCenter - optional; an object containing the latitude and longitude of the starting point for the search ({latitude:'',longitude:''}); if this parameter is provided, useGeoLocation is ignored
  • {Object} boundingBox - instead of search center boundingBox can be passed is a parameter. Bounding box is an object containing to coordinates topLeft and bottomRight ({topLeft: {latitude: '', longitude:''}, bottomRight: {latitude:'', longitude''}})
  • {Boolean} useGeoLocation - if true and searchCenter is not provided, Places search tries to use the W3C Geolocation API to get the client location and use it as the search center; if this parameter is false and searchCenter is not provided, a global search is executed
  • {Number} limit - optional; the maximum number of results to be returned
Returns:
 
 
The return value is made available asynchronously as arguments passed to the onComplete handler; the responseData argument contains a response view nokia.places.objects.SearchResponseView. Directly function also returns a number which is the request ID and can be used to cancel/abort the current request with nokia.places.comm.data.abortRequest

 

findRecommendations(params)

This function retrieves recommendations for the location indicated by the caller.

Parameters:
 
params:
{Object}
 
An object containing request parameters:
  • {String} placeId - id of a place (from nokia.places.objects.Place)
  • {Number} limit - the maximum number of recommended places to be returned
  • {Function} onComplete - {Function}, a function to be called when the request has completed, required; the function must accept as arguments:
    • responseData - an instance of nokia.places.objects.SearchResponseView containing data returned by the Places back-end
    • status - {String}, a constant, with the value of 'OK' to indicate success or 'ERROR' to indicate request failure or time-out
Returns:
 
 
The return value is made available asynchronously as arguments passed to the onComplete handler; the responseData argument contains a response view, which is an instance of nokia.places.objects.SearchResponseView. Directly function also returns a number which is the request ID and can be used to cancel/abort the current request with nokia.places.comm.data.abortRequest

 

geoCode(params)

This method runs a geocoding query based on the arguments provided by the caller.

Parameters:
 
params:
{Object}
 
an object containing:
  • address - an object containing at least one of the elements of nokia.places.objects.Place.location.address; optional, if not provided the caller is expected to supply searchTerm described below
  • searchTerm - a {String} identifying the location to be geocoded, for example, it can contain the name of the place or the full address, etc.; optional, if not provided, the caller is expected to supply address described above
  • onComplete - {Function}, a function to be called when the request has completed, required; the function must accept as arguments:
    • responseData - an instance of nokia.places.objects.Place containing data returned by the Places back-end
    • status - {String}, a constant, with the value of 'OK' to indicate success or 'ERROR' to indicate request failure or time-out
Returns:
 
 
The return value is made available asynchronously as arguments passed to the onComplete handler; when status is 'OK', the argument responseData contains a place object, which is an instance of nokia.places.objects.Place. Directly function also returns a number which is the request ID and can be used to cancel/abort the current request with nokia.places.comm.data.abortRequest

 

reverseGeoCode(params)

This method runs a reverse geocoding query based on the coordinates provided by the caller. A default radius is applied.

Parameters:
 
params:
{Object}
 
an object containing the coordinates to be used in a reverse geocoding query:
  • latitude - {Number}, latitude in degrees in the range [-90 .. 90]; values outside this range result in failed queries
  • longitude - {Number}, longitude in degrees in the range [-180 .. 180]; values outside this range result in failed queries
  • onComplete - {Function}, a function to be called when the request has completed, required; the function must accept as arguments:
    • responseData - an instance of nokia.places.objects.Place containing data returned by the Places back-end
    • status - {String}, a constant, with the value of 'OK' to indicate success or 'ERROR' to indicate request failure or time-out
Returns:
 
 
The return value is made available asynchronously as arguments passed to the onComplete handler; when status is 'OK', the argument responseData contains a place object, which is an instance of nokia.places.objects.Place or an empty String if there is no address information available for selected coordinates. Directly function also returns a number which is the request ID and can be used to cancel/abort the current request with nokia.places.comm.data.abortRequest

 

suggestPlaces(params)

This function retrieves suggestions that can be used with nokia.places.search.manager#findPlaces().

Parameters:
 
params:
{Object}
 
An object containing parameters that define a request for suggestions:
  • {String} searchTerm - required; a suggestion query term
  • {Function} onComplete - required; a function to be called when the request has been completed; the function must accept as arguments responseData, which is an instance of nokia.places.objects.SearchResponseView containing data returned by the Places back-end, and status, which is a {String} constant with the value of 'OK' to indicate success or 'ERROR' to indicate request failure or time-out
  • {Object} searchCenter - optional; an object containing the latitude and longitude of the starting point for the search ({latitude:'',longitude:''}); if this parameter is provided, useGeoLocation is ignored
  • {Boolean} useGeoLocation - if true and searchCenter is not provided, Places search tries to use the W3C Geolocation API to get the client location and use it as the search center; if this parameter is false and searchCenter is not provided, a global search is executed
Returns:
 
 
The return value is made available asynchronously via the argument responseData passed to the handler function onComplete as a response view object (nokia.places.objects.SearchResponseView). Directly function also returns a number which is the request ID and can be used to cancel/abort the current request with nokia.places.comm.data.abortRequest