Google Maps Js 2d

Google Maps JavaScript API 2D

Use this repo-local skill when a task changes 2D Google Maps rendering, map loading, markers, overlays, controls, Places/geocoding widgets, or a Mapbox-to-Google Maps migration path in demos/aqi-map/ or demos/strava-explorer/.

Quick workflow

1. Identify the target app and runtime before editing:

• demos/aqi-map/ is a Vite app using Google Maps Platform Air Quality API heatmap tiles.
• demos/strava-explorer/ is a Vite app with centralized Google Maps Platform loading in demos/strava-explorer/src/gmp.js.

1. Read the app's package.json, README, relevant HTML, and map source files before changing map code.
2. Verify current Maps JavaScript API behavior against official docs when touching loader, library imports, Advanced Markers, data-driven styling, WebGL, deck.gl, Drawing/Heatmap replacements, or release channels.
3. Keep Maps JavaScript API loading centralized. Do not add duplicate script tags, duplicate Loader instances, or parallel loader mechanisms.
4. Prefer google.maps.importLibrary() after the Maps JavaScript API loader has resolved:

• maps for Map, InfoWindow, controls, and core camera.
• marker for AdvancedMarkerElement and PinElement.
• places for Places widgets and services.
• geocoding, geometry, or other libraries only when needed.

1. Validate latitude/longitude ranges before rendering, sending requests, or building tile URLs.
2. For visible map/UI changes, run a build plus browser/screenshot QA when the environment allows it.

Official references to check

• Maps JavaScript API overview: https://developers.google.com/maps/documentation/javascript/overview
• Loading/import libraries: https://developers.google.com/maps/documentation/javascript/load-maps-js-api
• Map IDs and cloud-based styling: https://developers.google.com/maps/documentation/javascript/map-ids/mapid-over
• Vector map features: https://developers.google.com/maps/documentation/javascript/vector-map
• Advanced Markers: https://developers.google.com/maps/documentation/javascript/advanced-markers/overview
• Data-driven styling: https://developers.google.com/maps/documentation/javascript/dds-boundaries/overview
• Data layer / GeoJSON: https://developers.google.com/maps/documentation/javascript/datalayer
• deck.gl GoogleMapsOverlay: https://developers.google.com/maps/documentation/javascript/deckgl-overlay-view
• WebGL Overlay View: https://developers.google.com/maps/documentation/javascript/webgl
• API security best practices: https://developers.google.com/maps/api-security-best-practices
• Deprecations: https://developers.google.com/maps/deprecations

2D implementation rules

• Prefer vector maps with a map ID for new Google Maps JS work so cloud styling, tilt/heading, Advanced Markers, and data-driven styling options remain available.
• Prefer AdvancedMarkerElement over legacy google.maps.Marker for new markers.
• Use semantic, accessible marker content for interactive markers. Include an accessible label/title and keyboard-operable details where practical. Keep custom marker DOM lightweight and verify console warnings after API changes.
• Use InfoWindow for simple details and a custom overlay, Advanced Marker content, or app-side panel for richer interactive UI.
• Prefer official Places widgets/services for search/autocomplete instead of hand-rolled geocoder UX.
• Avoid the Maps JavaScript API Heatmap Layer and Drawing Library for new work: Google deprecated Heatmap Layer in May 2025 and made it unavailable in May 2026; Drawing Library was deprecated in August 2025 and unavailable in May 2026. Prefer deck.gl heatmaps, custom WebGL/canvas overlays, or server-generated tiles for heatmaps; use custom drawing tools or Data layer/editing alternatives for drawing.
• Use deck.gl GoogleMapsOverlay for large point clouds, heatmaps, contours, or animated geospatial visualizations that exceed practical DOM marker counts.
• Use Data layer/GeoJSON for small-to-moderate feature collections and simple styling; use deck.gl or tiled/vector data for large or frequently changing datasets.
• Batch, debounce, or cache quota-sensitive service calls such as Geocoding, Places, Routes, Environment APIs, and Elevation.
• Keep map container CSS scoped. Avoid global CSS that affects Google-rendered controls or shadow DOM descendants unexpectedly.
• Respect prefers-reduced-motion for camera animations, auto-pan, flyovers, or continuous viewport changes.

Mapbox GL to Google Maps JS migration notes for demos/aqi-map/

When migrating demos/aqi-map/ from Mapbox GL to Google Maps JS:

1. Preserve the existing product behavior first: global AQI map, geocoder/search, clustered sensors, AQI color ramp, sensor popups, contours/isobands, mobile panel, and PurpleAir attribution.
2. Replace Mapbox token/style configuration with documented Google Maps Platform browser API-key configuration. Do not commit real keys.
3. Replace Mapbox Geocoder with Places Autocomplete or Place Autocomplete Element where appropriate.
4. Replace Mapbox clustering with one of:

• @googlemaps/markerclusterer plus Advanced Markers for marker-based clustering.
• deck.gl aggregation layers for dense AQI visualization.
• Server/precomputed vector tiles for very large datasets.

1. Replace Mapbox fill/circle/symbol layers with Google Maps Data layer, deck.gl layers, or custom overlays depending on feature count and styling needs.
2. Replace Mapbox globe/projection requirements with Google Maps vector map capabilities; confirm any 3D/globe requirement separately with the 3D skill.
3. Revisit all API keys/tokens and document required API restrictions, HTTP referrers, local development origins, and enabled APIs.

QA checklist

• Map loads exactly once and no duplicate billing/loading paths are introduced.
• Browser API key restrictions and enabled APIs are documented.
• Search/geocoding has accessible labels and clear loading/error states.
• Marker/detail content is keyboard-accessible where practical.
• Large datasets avoid thousands of DOM markers unless clustered/windowed.
• Tile, API, and service requests are bounded by viewport, zoom, cache, or debounce logic.
• Mobile controls do not cover essential map controls or trap gestures.
• Build command passes from the app directory.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ryanbaumann
• Source: ryanbaumann/portfolio
• License: MIT
• Homepage: https://www.ryanbaumann-portfolio.com

Install and usage instructions live in the source repository linked above.