top of page
  • Writer's picture28East

More Control Loading the Maps JavaScript API

Today we're sharing three big improvements to how the Maps JavaScript API is loaded: an API for flexible library loading, the new inline bootstrap loader, and a set of performance improvements.

Flexible library loading

The Maps JavaScript API is made up of libraries which developers specify for inclusion when loading the API. These libraries go beyond just showing a map on a website. For example, to access the Places API, developers can load the Places Library. However, loading these libraries was inflexible and slowed initial loading times because until now they could only be specified on initial load of the Maps JavaScript API (e.g. via the libraries=places URL parameter).

Google Maps Platform now provides an API for dynamically importing libraries. For example,

await google.maps.importLibrary("places");

will load the Places Library when you decide it is needed, which can be after a user action necessitates information about places. Even better, it’s now possible to avoid using long namespaces like google.maps.places.Place via

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

(though the google.maps.places namespace will continue being populated).

Multiple libraries can now also be imported in parallel:

const [placesLibrary, geocodingLibrary] = await Promise.all([




We've also made it so that all classes of the Maps JavaScript API are available via google.maps.importLibrary() as listed in documentation. For example, you can access the StreetViewPanorama class via

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

Now you can control exactly when your Maps JavaScript API dependencies are loaded.

The new inline bootstrap loader

Another common issue is that using the Maps JavaScript API <script> loader requires defining a callback parameter to a globally defined function. Google Maps Platform now recommends developers use our new inline bootstrap loader which allows developers to use google.maps.importLibrary() immediately, without needing to wait for the API to load. This also means that you can avoid that pesky global callback and use Promises or async/await to track when the Maps JavaScript API is ready.

Instead of specifying a <script> tag with a URL, you can include the new inline bootstrap loader; a small bit of inline JavaScript. This code takes your configuration parameters, will construct the bootstrap URL for you, and defines google.maps.importLibrary() so that you can immediately begin using it. No part of the Maps JavaScript API is loaded until google.maps.importLibrary() is first called. This new inline bootstrap loader is also safe to use multiple times per page, though only the first configuration will be used. And when using the new loader, the google.maps.importLibrary() Promise will correctly reject when there is an issue loading the Maps JavaScript API (something the older callback mechanism didn't support).

Performance improvements

This year, Google Maps Platform also made several changes to the Maps JavaScript API to automatically improve loading times for end users. They have enabled Brotli compression for their static JavaScript files, and introduced automatic lazy loading for maps that are offscreen. Later this year they will also be upgrading their JavaScript to have more modern code output, reducing file size by taking advantage of more browser built-in features.

Why the Maps JavaScript API uses a <script> loader

A number of developers have asked Google Maps Platform why they don’t distribute via npm. They regularly evaluate options for accessing the API, and they very much recognise that a <script> tag might seem archaic in a world where most JS packages are distributed via npm.

One important insight they’ve gained is that many websites—both large and small—that adopt the Maps JavaScript API are not actively maintained, and they want to make sure that they are doing what they can to keep those websites working. The code that makes up our UI render is rather complex, and it utilises a large number of backend services under the hood. Over the years innumerable changes in browsers and those backend services have required updates to the inner workings of the Maps JavaScript API in order to continue working correctly. There have also been important accessibility, privacy, and security updates. And since websites load the API directly from Google, they have been able to automatically get all of those updates. Even for actively maintained websites, part of the value of using the Maps JavaScript API is avoiding many of the surprise breakages caused by these kinds of changes (and the resulting high-stress scramble to find and deploy fixes). This means that you get to spend more time focused on your own objectives, instead of dealing with dependency management.

For those developers looking for something that bridges the gap between <script> loading and npm, Google Maps Platform offers the @googlemaps/js-api-loader package. The new google.maps.importLibrary() can also be used with js-api-loader via Loader.importLibrary().

Want to learn more about Google Maps Platform? Get in touch with us today! We would love to grab a coffee with you to discuss how this platform can benefit your business.

27 views0 comments


bottom of page