Maps API for JavaScript Developer's Guide

H.service.PlacesService

Class Summary

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 ]

Property Summary

Table 1. Properties
Properties

static CONFIG_KEY : {string}

The property name to use when specifying options for this service within the H.service.Platform.Options#servicesConfig.

Method Summary

Table 2. 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 is used to follow hyperlinks in the results returned by discovery queries.

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.

It's not allowed to call the constructor directly (an IllegalOperationError is thrown). Instead an instance of this Service can be retrieved by calling the factory method H.service.Platform#getPlacesService on a platform instance.

Example

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

Constructor Details

H.service.PlacesService(opt_options)

Parameters:
 
opt_options:
{H.service.PlacesService.Options=} [optional]
 
Configuration options for places service

Property Details

static CONFIG_KEY: {string}

The property name to use when specifying options for this service within the H.service.Platform.Options#servicesConfig.

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}
 
Contains map key value pairs to be transformed into the URL parameters. For entry point parameters description, please refer to Places RESTful 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 (for example request timeout)
Returns:
 
{H.service.JsonpRequestHandle}
A 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}
 
Contains 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 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}
 
Contains 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 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}
 
Contains 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 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}
 
Contains 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 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}
 
Contains 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 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}
 
Contains 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 request handle

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

This method is 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]
 
Contains additional parameters to send with the request
Returns:
 
{H.service.JsonpRequestHandle}
A request handle