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). 

We now provide 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([
    google.maps.importLibrary("places"),
    google.maps.importLibrary("geocoding")
]);

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. We now recommend 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, we also made several changes to the Maps JavaScript API to automatically improve loading times for end users. We have enabled Brotli compression for our static JavaScript files, and introduced automatic lazy loading for maps that are offscreen. Later this year we will also be upgrading our 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 us why we don’t distribute via npm. We regularly evaluate options for accessing the API, and we very much recognize that a <script> tag might seem archaic in a world where most JS packages are distributed via npm. 

One important insight we’ve gained is that many websites—both large and small—that adopt the Maps JavaScript API are not actively maintained, and we want to make sure that we are doing what we can to keep those websites working. The code that makes up our UI render is rather complex, and it utilizes 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, we offer the @googlemaps/js-api-loader package. The new google.maps.importLibrary() can also be used with js-api-loader via Loader.importLibrary().

And for those developers looking for more control over when they adopt new releases of the Maps JavaScript API, take a look at the options available. Each version of the Maps JavaScript API is now available for an entire year.

For more information on Google Maps Platform, visit our website.