SME page one heading
SME page one intro
Security notice: We have become aware of a security issue that may be affecting websites using specific third-party libraries (including polyfill.io). This issue can sometimes redirect visitors away from the intended website without website owner knowledge or permission. Many of our JavaScript samples previously included apolyfill.io script
declaration. We have removed this from our samples. If you have used our JavaScript samples that contain this declaration, we recommend removing the
declaration.This guide shows you how to load the Maps JavaScript API. There are three ways to do this:
- Use dynamic library import
- Use the direct script loading tag
- Use the NPM js-api-loader package
Use Dynamic Library Import
Dynamic library import provides the capability to load libraries at runtime. This lets you request needed libraries at the point when you need them, rather than all at once at load time. It also protects your page from loading the Maps JavaScript API multiple times.
Load the Maps JavaScript API by adding the inline bootstrap loader to your application code, as shown in the following snippet:
You can also add the bootstrap loader code directly to your JavaScript code.
To load libraries at runtime, use the await operator
to call importLibrary() from
within an async function,
as shown in the following code example:
Learn how to migrate to the Dynamic Library Loading API.
Required parameters
-
key: Your API key. The Maps JavaScript API won't load unless a valid API key is specified.
Optional parameters
-
v: The version of the Maps JavaScript API to load. -
libraries: A comma-separated list of additional Maps JavaScript API libraries to load. Specifying a fixed set of libraries is not generally recommended, but is available for developers who want to finely tune the caching behavior on their website. -
language: The language to use. This affects the names of controls, copyright notices, driving directions, and control labels, and the responses to service requests. See the list of supported languages. -
region: The region code to use. This alters the map's behavior based on a given country or territory. -
authReferrerPolicy: Maps JS customers can configure HTTP Referrer Restrictions in the Cloud Console to limit which URLs are allowed to use a particular API Key. By default, these restrictions can be configured to allow only certain paths to use an API Key. If any URL on the same domain or origin may use the API Key, you can setauthReferrerPolicy: "origin"to limit the amount of data sent when authorizing requests from the Maps JavaScript API. When this parameter is specified and HTTP Referrer Restrictions are enabled on Cloud Console, Maps JavaScript API will only be able to load if there is an HTTP Referrer Restriction that matches the current website's domain without a path specified. -
mapIds: An array of map Ids. Causes the configuration for the specified map Ids to be preloaded. -
channel: See Usage tracking per channel. -
solutionChannel: Google Maps Platform provides many types of sample code to help you get up and running quickly. To track adoption of our more complex code samples and improve solution quality, Google includes thesolutionChannelquery parameter in API calls in our sample code.
Use the direct script loading tag
This section shows how to use the direct script loading tag. Because the direct script loads libraries when the map loads, it can simplify maps created
using a gmp-map element
by removing the need to explicitly request libraries at runtime. Do be careful to only include it once per page load though.
Add a script tag
To load the Maps JavaScript API inline in an HTML file, add a script tag
as shown below.
Direct script loading URL Parameters
This section discusses all of the parameters you can specify in the query string of the script loading URL when loading the Maps JavaScript API. Certain
parameters are required while others are optional. As is standard in URLs, all parameters are separated using the ampersand (&)
character.
The following example URL has placeholders for all possible parameters:
Required parameters (direct)
The following parameters are required when loading the Maps JavaScript API.
-
key: Your API key. The Maps JavaScript API will not load unless a valid API key is specified.
Optional parameters (direct)
Use these parameters to request a specific version of the Maps JavaScript API, load additional libraries, localize your map or specify the HTTP referrer check policy
-
loading: The code loading strategy that the Maps JavaScript API can use. Set toasyncto indicate that the Maps JavaScript API has not been loaded synchronously and that no JavaScript code is triggered by the script'sloadevent. It is highly recommended to set this toasyncwhenever possible, for improved performance. (Use thecallbackparameter instead to perform actions when the Maps JavaScript API is available.) Available starting with version 3.55. -
callback: The name of a global function to be called once the Maps JavaScript API loads completely. -
v: The version of the Maps JavaScript API to use. -
libraries: A comma-separated list of additional Maps JavaScript API libraries to load. -
language: The language to use. This affects the names of controls, copyright notices, driving directions, and control labels, as well as the responses to service requests. See the list of supported languages. -
region: The region code to use. This alters the map's behavior based on a given country or territory. -
auth_referrer_policy: Customers can configure HTTP Referrer Restrictions in the Cloud Console to limit which URLs are allowed to use a particular API Key. By default, these restrictions can be configured to allow only certain paths to use an API Key. If any URL on the same domain or origin may use the API Key, you can setauth_referrer_policy=originto limit the amount of data sent when authorizing requests from the Maps JavaScript API. This is available starting in version 3.46. When this parameter is specified and HTTP Referrer Restrictions are enabled on Cloud Console, Maps JavaScript API will only be able to load if there is an HTTP Referrer Restriction that matches the current website's domain without a path specified. -
mapIds: A comma-separated list of map Ids. Causes the configuration for the specified map Ids to be preloaded. -
channel: See Usage tracking per channel. -
solution_channel: Google Maps Platform provides many types of sample code to help you get up and running quickly. To track adoption of our more complex code samples and improve solution quality, Google includes thesolution_channelquery parameter in API calls in our sample code.
Use the NPM js-api-loader package
The @googlemaps/js-api-loader package is available, for loading via NPM package manager. Install it using the following command:
