Libraries

  • The Maps JavaScript API loads quickly by using libraries that are imported as needed with google.maps.importLibrary().

  • You can include your API key and specify the API version in a bootstrap loader script to initially load the API.

  • Dynamic Library Import offers a modular approach, letting you load specific libraries like maps, places, marker, etc., on demand.

  • For backward compatibility, a legacy bootstrap script tag is also available, supporting libraries such as drawing, geometry, and places.

  • Both methods allow customization: Dynamic Import uses importLibrary() within an async function, while the legacy method uses the libraries parameter in the script tag's URL.

To load the JavaScript code for the Maps JavaScript API, you include a bootstrap loader script on your page, of the following form:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

The Maps JavaScript API is made up of libraries that are not loaded until you specifically request them. Breaking up components into libraries lets the API load and parse quickly, so you only incur the additional overhead of loading and parsing libraries as you need them. When using dynamic library import, the inline bootstrap loader does not load any libraries by default (not even core or maps); prior to calling google.maps.importLibrary(), no part of the Maps JavaScript API is loaded.

To load a library at runtime, use the await operator to call google.maps.importLibrary() from within an async function. Assume that only the requested library is loaded, and call google.maps.importLibrary() for each library your code uses. For example:

const { Map } = await google.maps.importLibrary("maps");

The following code example shows loading both the maps and marker libraries to access the Map and AdvancedMarkerElement classes:

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();

Available Libraries

The following libraries are available for use with dynamic library import and direct script loading tag:

The following bootstrap request illustrates how to add a request for the google.maps.geometry library of the Maps JavaScript API, to the direct script loading tag:

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

To request multiple libraries, separate them with a comma:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=geometry,places&callback=initMap">
</script>