Maps API for JavaScript Developer's Guide

Places

Searching for and exploring places in a location-aware manner are common features of location-based applications. With the Maps API for JavaScript, you can search for places using plain text or pre-defined categories and a location. The search results may include information such as place names, addresses, contact details, location maps, ratings, reviews, and related premium content. Search requests can specify that only results within specific areas be included in responses.

To support searching for and exploring places, load the Places module (mapsjs-places.js).

When you combine this module with Maps API for JavaScript maps and markers, you can create powerful applications that help users find places of interest to them. The examples below cover the following basic scenarios:
  • searching for a place in a specific location based on associations with a plain text word
  • searching for places matching a category in a specific location, with information on how to limit the search to a specific area
  • paginating the information in the response to make the information more usable in the application
  • getting additional details about a specific place
  • restricting the search results included in the response to the map area displayed on the user screen
  • using the user location to search for places matching a category
  • listing the categories available for a given location

Searching for and Exploring – General Implementation Pattern

To implementn requests for places-related information:

  1. Load the Places module (mapsjs-places.js).
  2. Create a Platform object for authentication (if you have not done so earlier) – note that the examples below use a demonstration credentials and access the customer integration testing (CIT) environment, rather than the production environment.
  3. Create the appropriate Places object through which you can submit requests.
  4. Create an object that defines the search parameters – the names of the parameters match the names of the parameters used in the HERE Places API
  5. Submit a search request – requests are asynchronous, therefore callbacks are needed to act on both success and error responses.
  6. Handle the response data – define callback functions that receive and process both the data received on success and when an error occurs.

Discovering Places

Maps API for JavaScript Places-related searches require:

  • a search term (a plain text word or phrase) or a category identifier (see also Categories)
  • a location or search geometry

The sections below demonstrate both types of searches.

Plain Text Searches

The following example searches for hotels in the Chinatown district in San Francisco.

The search follows the general pattern with the parameter object containing the plain text word "hotel" and the location given as a pair of geographic coordinates, 37.7942,-122.4070. To request is submitted, using the object H.places.Search. The code also shows rudimentary callback functions which.


// Instantiate a platform object for authentication
var platform = new H.service.Platform({
  useCIT: true,
  app_id: '{YOUR_APP_ID}',
  app_code: '{YOUR_APP_CODE}'
});

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

// Define search parameters:
var params = {
  // Plain text search for places with the word "hotel"
  // associated with them:
  'q': 'hotel',
  //  Search in the Chinatown district in San Francisco:
  'at': '37.7942,-122.4070'
};

// Define a callback function to handle data on success:
function onResult(data) {
  searchResult = data;
}

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

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

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({
  useCIT: true,
  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({
  useCIT: true,
  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;
}

Using Location Contexts

The example in Category Searches shows how to confine the search area by specifying a radius. Another way to reduce the number of results from Maps API for JavaScript searches for places is to add context information to a request.

Listing Categories for a Location

You can use Maps API for JavaScript searches to request lists of categories available at specified locations to allow users to select what they want to search for.

The example below follows the general implementation pattern, with the parameter object containing the location 52.5310,13.3848. The request object is H.places.Categories.

The code submits a request, which is then processed asynchronously.

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

// Obtain a Categories object through which to submit search requests:
var categories = new H.places.Categories(platform.getPlacesService()),
  categoriesResponse, error;

// Define search parameters:
var params = {
//  Location context that indicates the search is in Berlin
  'at': '52.521,13.3807'
  },
//  Headers object required by the request() method (empty):
  headers = {};

// Run a request for categories, using the parameters, headers, and
// callback functions:
categories.request(params, headers, onResult, onError);

// Success handler - fetch the first set of detailed place data from
// the response:
function onResult(data) {
  categoriesResponse = data;
}

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

Integration with the Map

You can easily integrate Maps API for JavaScript with the map to display the results of a request. To demonstrate this, we reuse the example that searches for places matching the word "hotel" in the Chinatown district in San Francisco, showing the search results as markers on the map.

The first step is to create an HTML page and to add the <script> tags to the <head> element to load the map API, including the Places module:


<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="initial-scale=1.0, 
      width=device-width" />
    <script src="http://js.api.here.com/v3/3.0/mapsjs-core.js" 
      type="text/javascript" charset="utf-8"></script>
    <script src="http://js.api.here.com/v3/3.0/mapsjs-service.js" 
      type="text/javascript" charset="utf-8"></script>
    <script src="http://js.api.here.com/v3/3.0/mapsjs-ui.js" 
      type="text/javascript" charset="utf-8"></script>
    <script type="text/javascript" charset="UTF-8"
      src="http://js.api.here.com/v3/3.0/mapsjs-places.js"></script>
    <link rel="stylesheet" type="text/css" 
      href="http://js.api.here.com/v3/3.0/mapsjs-ui.css" />
  </head>

The next step is to create the <body> element and in it the map container (a <div>) in which to display the map. Finally, we need another <script> section with the application logic.


<body>
  <div id="map" style="width: 640px; height: 480px"/>
  <script type="text/javascript" charset="utf-8">
    // Instantiate the Platform class with authentication and
    // authorization credentials:
    var platform = new H.service.Platform({
      useCIT: true,
      app_id: '{YOUR_APP_ID}',
      app_code: '{YOUR_APP_CODE}'
    });

    // Instantiate a map inside the DOM element with id map. The
    // map center is in San Francisco, the zoom level is 10:
    var map = new H.Map(document.getElementById('map'),
      platform.createDefaultLayers().normal.map, {
      center: {lat: 37.7942, lng: -122.4070},
      zoom: 15
      });

    // Create a group object to hold map markers:
    var group = new H.map.Group();

    // Create the default UI components:
    var ui = H.ui.UI.createDefault(map, platform.createDefaultLayers());

    // Add the group object to the map:
    map.addObject(group);

    // Obtain a Search object through which to submit search
    // requests:
    var search = new H.places.Search(platform.getPlacesService()),
      searchResult, error;

    // Define search parameters:
    var params = {
    // Plain text search for places with the word "hotel"
    // associated with them:
      'q': 'hotel',
    //  Search in the Chinatown district in San Francisco:
      'at': '37.7942,-122.4070'
    };

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

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

    // This function adds markers to the map, indicating each of
    // the located places:
    function addPlacesToMap(result) {
      group.addObjects(result.items.map(function (place) {
      var marker = new H.map.Marker({lat: place.position[0],
        lng: place.position[1]})
      return marker;
      }));
    }

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

  </script>
</body>

As in the previous examples, the code follows the general implementation pattern, with the parameter object containing the plain text "hotel" and the location 37.7942,-122.4070. The request object is H.places.Search.

The code submits a request, which is processed asynchronously.

The callback invoked on successful response calls a function named addPlacesToMap() to add a markers to the map, indicating the located places. addPlacesToMap() takes advantage of the fact that, for each of the places, the results contain a position object with the geographic coordinates.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.