Get Started

Follow these steps to add the Local Context Library to your project, initialize, and configure the Local Context map view.

Enabling the required APIs and SDKs

To use the Local Context Library, you must enable the Maps JavaScript API and the Places API. To do this, follow the instructions to Enable one or more APIs or SDKs. Note that both APIs must be enabled in the same project in the Google Cloud Console.

Loading the Local Context Library

To load the Local Context Library, load the Maps JavaScript API as you normally would, and include the following parameters:

  • libraries=localContext loads the Local Context Library.
  • v=beta is required to use this release.
  • key contains your API key.
  • callback executes the initMap() function.

The following example shows a script tag with all of the aforementioned options:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=localContext&v=beta&callback=initMap">
</script>

Creating a new Local Context map view

To add the Local Context Library to a web page, first create a LocalContextMapView instance, and set the desired properties:

  • element - The div element where the map should display (in this case it's named "map").
  • placeTypePreferences - types of places that the Local Context Library should return (up to 10).
  • maxPlaceCount - The maximum number of places to display (1 - 24).
  • locationRestriction (Optional) - Restricts the place search to a particular location. Defaults to the map viewport.

Once you have a LocalContextMapView instance, you can set Map Options on the inner Map instance. The Map contained by a LocalContextMapView supports all of the same map options as a standard Maps JavaScript API Map. The following example shows creating a new LocalContextMapView instance, and setting a few options on the inner Map:

TypeScript

let map: google.maps.Map;

function initMap() {
  const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.getElementById("map"),
    placeTypePreferences: [
      { type: "restaurant" },
      { type: "tourist_attraction" },
    ],
    maxPlaceCount: 12,
  });

  map = localContextMapView.map!;

  map.setOptions({
    center: { lat: 51.507307, lng: -0.08114 },
    zoom: 14,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

let map;

function initMap() {
  const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.getElementById("map"),
    placeTypePreferences: [
      { type: "restaurant" },
      { type: "tourist_attraction" },
    ],
    maxPlaceCount: 12,
  });

  map = localContextMapView.map;
  map.setOptions({
    center: { lat: 51.507307, lng: -0.08114 },
    zoom: 14,
  });
}

window.initMap = initMap;
index.js

Postpone loading Local Context data

You can postpone loading Local Context data at initialization time, by setting the LocalContextMapView maxPlaceCount option to 0. This is handy in situations where you want to wait until users are ready to see the data. When you're ready to load Local Context data, set maxPlaceCount to a value of 1 or more. The following example shows initializing the map without loading Local Context data, then setting maxPlaceCount to load the data:

// Initialize without Local Context data.
const localContextMapView = new google.maps.localContext.LocalContextMapView({
    element: document.querySelector('#map'),
    placeTypePreferences: ['restaurant'],
    maxPlaceCount: 0, // Avoids an automatic call to load places during initialization.
  });

//...

// Show places now.
localContextMapView.maxPlaceCount = 12;

Toggle displaying Local Context UI

You can toggle the Local Context user interface elements by setting the LocalContextMapView maxPlaceCount option to 0. To display the Local Context user interface again, set maxPlaceCount to a value of 1 or more.

Setting minimum map dimensions

The Local Context Library responsively changes the display based on the rendered size of the LocalContextMapView. The minimum supported dimensions for the LocalContextMapView are:

  • 300 pixels x 480 pixels (portrait)
  • 480 pixels x 380 pixels (landscape)

When the containing element for the LocalContextMapView drops below the minimum supported dimensions, Local Context Library elements, including the place chooser and points of interest, are not visible. Browser zoom level affects the minimum supported dimensions; for example if the browser window is zoomed to 200%, the minimum supported dimensions are then 600 x 960 (portrait) and 960 x 760 (landscape).

CSS recommendations

CSS classes in the Local Context Library DOM are not part of the public API, and styling, modifying, or selecting elements within the Local Context Library DOM is not supported. We strongly recommend the following guidelines to avoid DOM styling conflicts, and ensure that the Local Context Library map view displays properly:

  • Do not use Local Context Library CSS classes, as they may change without notice.
  • Do not style, modify, or select elements within the Local Context Library DOM.

If you use a CSS framework that makes such modifications, then you may be able to work around styling conflicts.

For example, if you want to change the overall page box-sizing to border-box:

  • Use box-sizing overrides that set the <html> element to border-box.
  • Use box-sizing: initial for the element that contains the Local Context Library map view.
  • Use box-sizing: inherit for all other elements.

This ensures that the Local Context Library DOM has box-sizing reset to the standard default with a low-specificity selector.

Here is what this looks like in code:

html {
  box-sizing: border-box;
}
*, *::before, *::after {
  box-sizing: inherit;
}

.container-for-google-maps {
  box-sizing: initial;
}