Maps API for JavaScript Developer's Guide

H.service.PlacesService

Class Summary

Extends: H.service.AbstractRestService

This service implements a low-level Places REST API access. Please refer to Restful API documentation for providing parameters and handling response objects.

[ For full details, see the Class Details ]

Method Summary

Table 1. Methods
Methods

request (entryPoint, entryPointParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method implements a generic means of querying the Places REST API.

search (searchParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'search' entry point. Please refer to documentation for parameter specification and response handling.

suggest (suggestParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'suggestions' entry point. Please refer to documentation for parameter specification and response handling.

explore (exploreParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'explore' entry point. Please refer to documentation for parameter specification and response handling.

around (aroundParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'around' entry point. Please refer to documentation for parameter specification and response handling.

here (hereParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'here' entry point. Please refer to documentation for parameter specification and response handling.

categories (categoriesParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'categories' entry point. Please refer to documentation for parameter specification and response handling.

follow (hyperlink, onResult, onError, opt_additionalParameters) : {H.service.JsonpRequestHandle}

This method should be used to follow hyperlinks in the results returned by discovery queries.

configure (appId, appCode, useHTTPS, useCIT, opt_baseUrl) : {H.service.IConfigurable}

This method receives configuration parameters from the platform, that can be used by the object implementing the interface. The method must not be invoked directly.

Class Description

This service implements a low-level Places REST API access. Please refer to Restful API documentation for providing parameters and handling response objects.

Entry point parameters are specified as key:value pairs which are transformed into URL parameters. Request headers can be specified along with entry point parameters.

Example

// Assumption: platform is instantiated
var places = platform.getPlacesService();
places.search({
 'at': '52.5044,13.3909',
 'q': 'pizza',
 'Accept-Language': 'de'
}, function(resp) {
 //handle response
 console.log(resp);
}, function(resp) {
 //handle network error
 console.log('ERROR: '+resp);
});

Constructor Details

H.service.PlacesService(opt_options)

Parameters:
 
opt_options:
{H.service.PlacesService.Options=} [optional]
 
An object containing the configuration options

Method Details

request (entryPoint, entryPointParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method implements a generic means of querying the Places REST API.

Example

// Assumption: the platform is instantiated
var places = platform.getPlacesService(),
  entryPoint = H.service.PlacesService.EntryPoint;
places.request(entryPoint.SEARCH, { 'at': '52.5044,13.3909', 'q': 'pizza'}, function(resp) {
 console.log(resp);
}, function(resp) {
 console.log('ERROR: '+resp);
});
Parameters:
 
entryPoint:
{string}
 
An identifier indicating one of the available entry points (H.service.PlacesService.EntryPoint), for example, H.service.PlacesService.EntryPoint.SEARCH
entryPointParams:
{Object}
 
An object containing map key value pairs to be transformed into the URL parameters. For entry point parameters description, please refer to Places RESTful API documentation documentation for available parameters for chose entry point
onResult:
{function(H.service.ServiceResult)}
 
A callback which is called when result is available
onError:
{function(Error)}
 
A callback which is called when an error occurs (for example request timeout)
Returns:
 
{H.service.JsonpRequestHandle}
A JSON-P request handle

This method triggers the Places API 'search' entry point. Please refer to documentation for parameter specification and response handling.

Parameters:
 
searchParams:
{H.service.ServiceParameters}
 
An object containing Places API search entry point parameters, please refer to Places API documentation
onResult:
{function(H.service.ServiceResult)}
 
A callback which is called when result is available
onError:
{function(Error)}
 
A callback which is called when an error occurs
Returns:
 
{H.service.JsonpRequestHandle}
A JSON-P request handle

suggest (suggestParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'suggestions' entry point. Please refer to documentation for parameter specification and response handling.

Parameters:
 
suggestParams:
{H.service.ServiceParameters}
 
An object containing Places API 'suggest' entry point parameters, please refer to Places API documentation
onResult:
{function(H.service.ServiceResult)}
 
A callback which is called when result is available
onError:
{function(Error)}
 
A callback which is called when an error occurs
Returns:
 
{H.service.JsonpRequestHandle}
A JSON-P request handle

explore (exploreParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'explore' entry point. Please refer to documentation for parameter specification and response handling.

Parameters:
 
exploreParams:
{H.service.ServiceParameters}
 
An object containing Places API 'explore' entry point parameters, please refer to Places API documentation
onResult:
{function(H.service.ServiceResult)}
 
A callback which is called when result is available
onError:
{function(Error)}
 
A callback which is called when an error occurs
Returns:
 
{H.service.JsonpRequestHandle}
A JSON-P request handle

around (aroundParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'around' entry point. Please refer to documentation for parameter specification and response handling.

Parameters:
 
aroundParams:
{H.service.ServiceParameters}
 
An object containing Places API 'around' entry point parameters, please refer to Places API documentation
onResult:
{function(H.service.ServiceResult)}
 
A callback which is called when result is available
onError:
{function(Error)}
 
A callback which is called when an error occurs
Returns:
 
{H.service.JsonpRequestHandle}
A JSON-P request handle

here (hereParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'here' entry point. Please refer to documentation for parameter specification and response handling.

Parameters:
 
hereParams:
{H.service.ServiceParameters}
 
An object containing Places API 'here' entry point parameters, please refer to Places API documentation
onResult:
{function(H.service.ServiceResult)}
 
A callback which is called when result is available
onError:
{function(Error)}
 
A callback which is called when an error occurs
Returns:
 
{H.service.JsonpRequestHandle}
A JSON-P request handle

categories (categoriesParams, onResult, onError) : {H.service.JsonpRequestHandle}

This method triggers the Places API 'categories' entry point. Please refer to documentation for parameter specification and response handling.

Parameters:
 
categoriesParams:
{H.service.ServiceParameters}
 
An object containing Places API 'categories' entry point parameters, please refer to Places API documentation
onResult:
{function(H.service.ServiceResult)}
 
A callback which is called when result is available
onError:
{function(Error)}
 
A callback which is called when an error occurs
Returns:
 
{H.service.JsonpRequestHandle}
A JSON-P request handle

follow (hyperlink, onResult, onError, opt_additionalParameters) : {H.service.JsonpRequestHandle}

This method should be used to follow hyperlinks in the results returned by discovery queries.

Example

// Assumption: the platform is instantiated
var places = platform.getPlacesService(),
  entryPoint = H.service.PlacesService.EntryPoint;
places.request(entryPoint.SEARCH, { 'at': '52.5044,13.3909', 'q': 'pizza'}, function(response) {
   var items = response.results.items;
   places.follow(items[0].href, function(resp) {
   console.log(resp);
   },
   function(resp) {
   console.log('ERROR: '+resp);
   });
}, function(resp) {
 console.log('ERROR: '+resp);
});
Parameters:
 
hyperlink:
{string}
 
A string containing a hyperlink to follow
onResult:
{function(H.service.ServiceResult)}
 
A callback which is called when result is available
onError:
{function(Error)}
 
A callback which is called when an error occurs
opt_additionalParameters:
{Object=} [optional]
 
An object containing additional parameters to send with the request
Returns:
 
{H.service.JsonpRequestHandle}
A JSON-P resquest handle

configure (appId, appCode, useHTTPS, useCIT, opt_baseUrl) : {H.service.IConfigurable}

This method receives configuration parameters from the platform, that can be used by the object implementing the interface. The method must not be invoked directly.

Example

// assuming that the configurable object exists and the variable name is "configurable"
var platform = new H.service.Platform({
  'app_id': [your app_id],
  'app_code': [your app_code],
})
platform.configure(configurable);
Parameters:
 
appId:
{string}
 
The application ID to identify the client against the platform (mandatory)
appCode:
{string}
 
The application code to identify the client against the platform (mandatory)
useHTTPS:
{boolean}
 
The indicator whether secure communication is used (true), the default is false
useCIT:
{boolean}
 
A value indicating whether Customer Integration Testing ("CIT") is used (true), the default is false
opt_baseUrl:
{H.service.Url=} [optional]
 
The base URL of the platform, the default is http://api.here.com. Note that if the useHTTPS flag is set to true, the URL scheme specified in the opt_baseUrl is overridden to use HTTPS.
Returns:
 
{H.service.IConfigurable}
An instance of IConfigurable reflecting the new configuration