Maps API for JavaScript Developer's Guide

Refining Search Results

A search for places with the Maps API for JavaScript can produce a large response data set, particularly when the search area is not constrained. Typically, the response data for each place contains a link to detailed information.

Viewing Results by Page

When a search produces a large number of hits, you may wish to retrieve it page by page. The following example shows how to do this to allow your application to filter the results before handling them further.

The code below follows the general pattern, defining a parameter object that contains the category "eat-drink" and a location in Berlin, 52.5310,13.3848. The request object is H.places.Explore.

The callback handling the results (success) is a skeleton. It processes the received data and immediately requests the next page of results by calling the method fetchNext(). This produces a page update, which is handled by a separate callback onPageUpdate().

          // Instantiate the Platform class:
var platform = new H.service.Platform({
  app_id: '{YOUR_APP_ID}',
  app_code: '{YOUR_APP_CODE}'
  }),
// Define the search parameters:
  params = {
// Look for places matching the category "eat and drink":
  'cat': 'eat-drink',
//  Search around a location in Berlin:
  'at': '52.5310,13.3848'
  };

// Obtain an Explore object through which to submit search requests:
var explore = new H.places.Explore(platform.getPlacesService()), nextPage, error;

// Run a search request with parameters, headers (empty), and callback functions:
explore.request(params, {}, onResult, onError);

// Define a callback function to handle data on success:
function onResult(data) {
  // Process data;
  ...

  // Request the next page of results from the response (causes a page update):
  data.results.fetchNext(onPageUpdate, onError);
}

// Define a callback to handle page updates:
function onPageUpdate(data) {
  nextPage = data;
}

// Define a callback to handle errors:
function onError(data) {
  error = data;
}
        

Requesting Detailed Results

In the previous examples, each successful search produces a result set that contains basic information, with links to details. The example below shows how to request the details of a specific place in the initial set of search results.

The code follows the general implementation pattern, with the parameter object specifying the place category eat-drink and a location in Berlin, 52.5310,13.3848. The request object is H.places.Explore.

When the success handler executes, it invokes the method follow() to obtain the details about the first place in the results. The details are processed by a dedicated callback function named onFetchPlaceDetails().

          // Instantiate the Platform class:
var platform = new H.service.Platform({
  app_id: '{YOUR_APP_ID}',
  app_code: '{YOUR_APP_CODE}'
  }),

// Define search parameters:
  params = {
  // Look for places matching the category "eat and drink":
  'cat': 'eat-drink',
   //  Search around a location in Berlin:
  'at': '52.5310,13.3848'
  },
  // Define a headers object required by the request() method:
  headers = {};

// Obtain an Explore object through which to submit search requests:
var explore = new H.places.Explore(platform.getPlacesService());

// Define result and error holder
var placeDetails, error;

// Run a search request with parameters, headers (empty), and callback
// functions:
explore.request(params, headers, onResult, onError);

// Success handler - fetch the first set of detailed place data from
// the response:
function onResult(data) {
  // Get the details of the first item (place) from the results:
  data.results.items[0].follow(onFetchPlaceDetails, onError);
}

// Define a callback to process a successful response to the
// request for place details:
function onFetchPlaceDetails(data) {
  placeDetails = data;
}

// Define a callback to handle errors:
function onError(data) {
  error = data;
}