Registry / http-networking / load-google-maps-api

load-google-maps-api

library2.0.2jsnpmunverified

The `load-google-maps-api` package (current stable version 2.0.2) provides a lightweight, promise-returning utility for dynamically loading the Google Maps JavaScript API. It modernizes the traditional API loading process by abstracting away the requirement for a global callback function, which can be cumbersome and less compatible with contemporary JavaScript bundlers like Webpack or Browserify. Instead, this module returns a Promise that resolves with the `google.maps` object upon successful API load, or rejects if a configurable timeout is exceeded. Developers can pass an options object to configure various aspects of the API, including the API key, desired language, region, specific API version, and supplemental libraries, offering a cleaner and more modular approach to integrating Google Maps into client-side web applications. Its release cadence is generally stable, with updates typically addressing Google Maps API changes or minor enhancements.

http-networking web-framework observability

npm install load-google-maps-api

github ↗package ↗

INSTALL

IMPORT

SIG · LOAD-GOOGLE-MAPS-A

load-google-maps-api

http-networkingjavascriptv2.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

loadGoogleMapsApi

✓ import loadGoogleMapsApi from 'load-google-maps-api';

✗ const loadGoogleMapsApi = require('load-google-maps-api');

While CommonJS `require` is shown in the README, modern browser-side development typically uses ES Module `import` syntax. Both are supported.

google.maps

✓ loadGoogleMapsApi().then(googleMaps => { /* use googleMaps */ });

✗ import { Map } from 'load-google-maps-api'; // Map is not directly exported

The `google.maps` object is passed as the fulfillment value of the Promise returned by `loadGoogleMapsApi`, not directly exported by the package.

loadGoogleMapsApi (with options)

✓ import loadGoogleMapsApi from 'load-google-maps-api'; loadGoogleMapsApi({ key: 'YOUR_API_KEY', libraries: ['places'] });

✗ loadGoogleMapsApi('YOUR_API_KEY'); // Options must be an object

Configuration options such as API key, language, or libraries must be passed as a single object literal to the `loadGoogleMapsApi` function.

This code demonstrates how to load the Google Maps API using a Promise and initialize a basic map with an API key and additional libraries. It also includes basic error handling.

import loadGoogleMapsApi from 'load-google-maps-api'; const GOOGLE_MAPS_API_KEY = process.env.GOOGLE_MAPS_API_KEY ?? ''; // Always use environment variables for keys if (!document.getElementById('map-container')) { const mapDiv = document.createElement('div'); mapDiv.id = 'map-container'; mapDiv.style.width = '100%'; mapDiv.style.height = '400px'; document.body.appendChild(mapDiv); } loadGoogleMapsApi({ key: GOOGLE_MAPS_API_KEY, v: 'weekly', // Use 'weekly' for latest features, 'release' for stable language: 'en', region: 'US', libraries: ['geometry', 'places'] // Example of loading additional libraries }) .then(function (googleMaps) { const map = new googleMaps.Map(document.getElementById('map-container'), { center: { lat: 40.7484405, lng: -73.9944191 }, zoom: 12, mapId: 'YOUR_MAP_ID' // Recommended for customized cloud-based maps }); console.log('Google Maps API loaded successfully and map initialized.', map); // You can now interact with the 'map' object or 'googleMaps' global object }) .catch(function (error) { console.error('Failed to load Google Maps API:', error); // Handle errors, e.g., display a fallback message });

Debug

Known issues

gotchaThis module, like the Google Maps JavaScript API itself, is designed exclusively for client-side (browser) environments. It will not function in Node.js or other server-side contexts.

fix

Ensure `load-google-maps-api` is only executed within a browser environment. For server-side rendering, consider dynamic imports or conditional loading.

affects: >=1.0.0

gotchaUsing the Google Maps API without an API key can lead to quota limits, restricted functionality, or error messages (e.g., 'ApiNotActivatedMapError'). While some basic features might work initially, a key is essential for production and full functionality.

fix

Obtain a Google Maps JavaScript API key from the Google Cloud Console, enable the necessary APIs for your project, and pass it via the `key` option: `loadGoogleMapsApi({ key: 'YOUR_API_KEY' })`.

affects: >=1.0.0

gotchaThe Promise returned by `loadGoogleMapsApi` will reject if the API fails to load within the specified `timeout` period (default 10 seconds). Unhandled promise rejections can lead to uncaught errors.

fix

Always include a `.catch()` block when using `loadGoogleMapsApi` to handle potential loading errors, including timeouts. You can also adjust the `timeout` option for slower networks: `loadGoogleMapsApi({ timeout: 20000 })`.

affects: >=1.0.0

deprecatedThe `v: '3'` option for the API version is now deprecated. Google recommends using `v: 'weekly'` for the latest updates or `v: 'beta'` for testing upcoming features. For a stable version, `v: 'release'` is also an option.

fix

Update your API version configuration from `v: '3'` to `v: 'weekly'`, `v: 'release'`, or `v: 'beta'` as appropriate for your project's stability requirements: `loadGoogleMapsApi({ v: 'weekly' })`.

affects: >=2.0.0

Errors

Common errors & fixes

Failed to load Google Maps API: Error: Timeout

The Google Maps API script took too long to load, exceeding the default 10-second timeout or a custom timeout setting.

fix

Check your network connection, ensure the `apiUrl` is correct, and consider increasing the `timeout` option in `loadGoogleMapsApi({ timeout: 20000 })` for slower environments or large API bundles.

Uncaught TypeError: googleMaps.Map is not a constructor

The `googleMaps` object was either not loaded correctly, or the Map class was not available when you tried to instantiate it, usually because the promise rejected or an error occurred during script execution.

fix

Verify that `loadGoogleMapsApi` resolved successfully. Ensure you are calling `new googleMaps.Map(...)` within the `.then()` callback and that the `key` and other options are correctly configured and not leading to API loading errors.

Google Maps JavaScript API error: ApiNotActivatedMapError

The Google Maps JavaScript API is not enabled in the Google Cloud Project associated with your API key.

fix

Go to the Google Cloud Console, navigate to 'APIs & Services' -> 'Library', search for 'Maps JavaScript API', and click 'ENABLE' for your project. Also, ensure your API key has the necessary permissions.

Google Maps JavaScript API error: RefererNotAllowedMapError

Your API key is restricted by HTTP referer (website) and the current domain is not whitelisted.

fix

In the Google Cloud Console, edit your API key restrictions under 'APIs & Services' -> 'Credentials'. Add your website's domain(s) to the 'HTTP referrers (web sites)' list. For development, you might add `*` or `localhost:*`.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/yuanqing/load-google-maps-api ↗

packagehttps://www.npmjs.com/package/load-google-maps-api ↗