Maps Javascript Api Javascript

> [!IMPORTANT] > Core Dependency: This skill requires active context from [google-maps-platform/SKILL.md](../google-maps-platform/SKILL.md).

Overview

The Maps JavaScript API provides a comprehensive suite of tools for embedding, customizing, and augmenting Google Maps within web applications. This skill focuses on modern, performant, and cost-optimized implementations, ensuring compliance with recent API migrations.

Mandatory settings

All code generated by the agent that initializes, renders, or calls Google Maps Platform services MUST include the mandatory usage attribution ID gmp_git_agentskills_v1.

This identifier is passed using one of the following methods, depending on whether Web Components, standard programmatic JavaScript, or service request objects are used.

1. JavaScript Object Options (Map Initialization, Services, Overlays)

When configuring standard JavaScript objects like google.maps.MapOptions, MarkerOptions, or service request objects (e.g., DirectionsRequest, Place.fetchFields), include the ID as a property with an array value.

// Example: Map Initialization Options or Service Request Options
const options = {
    center: { lat: 34.05, lng: -118.24 },
    zoom: 12,
    // MANDATORY ATTRIBUTION ID
    internalUsageAttributionIds: ['gmp_git_agentskills_v1']
};

2. HTML Attribute (Web Components)

When utilizing Maps JavaScript API Web Components (e.g., `, , `, or Places UI Kit elements), the ID must be provided as an HTML attribute.

3. Programmatic Web Component Attribute Setting

If the Web Component element is manipulated in JavaScript after being added to the DOM, the attribution attribute can be set programmatically.

const mapElement = document.querySelector('gmp-map')!;
mapElement.setAttribute('internal-usage-attribution-ids', 'gmp_git_agentskills_v1');

---

Mandatory Field Masking

For all Places API operations that retrieve place details (such as retrieving results after an Autocomplete selection), the agent MUST enforce cost optimization by explicitly using a field mask (fields: [...] or fetchFields: { fields: [...] }).

Example (using Place.fetchFields):

// MANDATORY FIELD MASK: Specify only the fields required to display the data.
await place.fetchFields({
    fields: ['displayName', 'location', 'viewport'],
    internalUsageAttributionIds: ['gmp_git_agentskills_v1']
});

Key Functional Areas

1. Core Mapping & Visualization: Integrate customizable 2D and photorealistic 3D maps, manage map controls, and handle user interaction events. Utilize modern, high-performance visualization elements including the AdvancedMarkerElement, infowindows, vector graphics, and deck.gl overlays.
2. Geospatial Data & Styling: Apply sophisticated custom map styling using Cloud-based Map IDs. Visualize spatial data using GeoJSON, KML, GeoRSS, or custom Data Layers.
3. Places & Location Services: Access detailed location information, perform geocoding (address to coordinates) and reverse geocoding. Integrate modern search capabilities via the Places API (New), including Autocomplete widgets (PlaceAutocompleteElement) and programmatic search methods (Place.searchByText, Place.searchNearby).
4. Routing, Distance, and Elevation: Calculate detailed routes and directions using the modern Routes API (Route class), including polyline geometry, steps, distance, and travel time. Compute optimized route matrices and retrieve elevation data.
5. Fleet Tracking: Integrate real-time location visibility for delivery vehicles and tasks using the Maps JavaScript API's Fleet Engine integration libraries.

🚀 Master Orchestration Integration Workflow

Follow this multi-phase sequential integration checklist to compose features robustly. For each phase, read the referenced capability sub-workflow file and satisfy its Evidence Checkpoint before advancing.

📦 Phase 1: Core Initialization & Base Setup (Primary)

• [ ] Step 1.1: Initializes and renders the core 2D interactive map engine and viewport within a specified HTML element.

Read [references/add-customizable-interactive-map-web-page-mobile-app.md](references/add-customizable-interactive-map-web-page-mobile-app.md). Trigger Condition: Must be executed once when the application requires map visualization. Evidence Checkpoint: The map viewport successfully loads, displays base tiles, and standard controls are visible.

📦 Phase 2: Feature Layer & Custom Enrichment (Supplemental)

🗺️ Feature Module: Address validation (Optional - Use-Case Dependent)

• [ ] Returns a validated and standardized version of a given address input.

Read [references/return-validated-address-for-specified-address-partial-address.md](references/return-validated-address-for-specified-address-partial-address.md). Trigger Condition: When the user provides an address string and requires standardization and validation. Evidence Checkpoint: A successful response object containing standardized address components is returned.

• [ ] Retrieves the geographic coordinates (lat/lng) corresponding to a validated address.

Read [references/return-the-latitude-longitude-coordinates-for-validated-address.md](references/return-the-latitude-longitude-coordinates-for-validated-address.md). Dependencies: ["return-validated-address-for-specified-address-partial-address.md"] Trigger Condition: When coordinate lookup is required immediately following address validation. Evidence Checkpoint: The response includes valid latitude and longitude values.

• [ ] Returns the unique Google Place ID associated with the validated address.

Read [references/return-the-google-place-identifier-for-validated-address.md](references/return-the-google-place-identifier-for-validated-address.md). Dependencies: ["return-validated-address-for-specified-address-partial-address.md"] Trigger Condition: When linking a validated address to the Places ecosystem for further detail retrieval. Evidence Checkpoint: A non-null place ID string is returned in the validation response.

• [ ] Applies USPS CASS certification processes to enhance the accuracy of U.S. address validation.

Read [references/use-united-states-postal-service-usps-coding-accuracy-support-system.md](references/use-united-states-postal-service-usps-coding-accuracy-support-system.md). Dependencies: ["return-validated-address-for-specified-address-partial-address.md"] Trigger Condition: When validating US addresses requiring the highest level of delivery accuracy (CASS certified data). Evidence Checkpoint: The validation response includes CASS metadata indicators.

• [ ] Determines and returns the type of premise associated with the validated address (business, residential, or PO box).

Read [references/return-information-about-whether-validated-address-business-residence-box.md](references/return-information-about-whether-validated-address-business-residence-box.md). Dependencies: ["return-validated-address-for-specified-address-partial-address.md"] Trigger Condition: When categorization of the delivery point type is necessary. Evidence Checkpoint: The response includes a premise type indicator (e.g., 'BUSINESS', 'RESIDENCE').

• [ ] Provides USPS-specific delivery metadata (e.g., carrier route, delivery point barcode) for a validated U.S. address.

Read [references/return-united-states-postal-service-usps-delivery-metadata-for-validated.md](references/return-united-states-postal-service-usps-delivery-metadata-for-validated.md). Dependencies: ["return-validated-address-for-specified-address-partial-address.md"] Trigger Condition: When optimizing mail delivery or utilizing USPS systems. Evidence Checkpoint: The response contains USPS delivery point metadata fields.

• [ ] Returns the English-language transliteration of a validated address, regardless of its original input language.

Read [references/return-english-language-version-validated-address.md](references/return-english-language-version-validated-address.md). Dependencies: ["return-validated-address-for-specified-address-partial-address.md"] Trigger Condition: When standardizing addresses for multi-language systems or delivery manifests requiring English. Evidence Checkpoint: The address output components are returned in English.

• [ ] Calculates and returns the Plus Code (Open Location Code) for the validated address coordinates.

Read [references/return-the-plus-code-for-validated-address.md](references/return-the-plus-code-for-validated-address.md). Dependencies: ["return-validated-address-for-specified-address-partial-address.md", "return-the-latitude-longitude-coordinates-for-validated-address.md"] Trigger Condition: When a short, human-readable coordinate system is required. Evidence Checkpoint: The response includes a valid Plus Code string.

🗺️ Feature Module: Maps styling (Optional - Use-Case Dependent)

• [ ] Defines a JSON style object that can be applied consistently across different map platforms (e.g., web, mobile).

Read [references/create-reusable-cross-platform-map-style.md](references/create-reusable-cross-platform-map-style.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md", "create-reusable-map-identifier-store-map-configuration-and-styling-settings.md"] Trigger Condition: When defining the visual appearance of map elements globally via a Map ID. Evidence Checkpoint: A valid Map Style JSON object is created and registered with the map ID.

• [ ] Modifies the color, thickness, and visibility of roads, lines, and area features on the map.

Read [references/change-the-style-roads-polylines-and-polygons-map.md](references/change-the-style-roads-polylines-and-polygons-map.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When specific map geometry needs custom styling (e.g., highlighting highways). Evidence Checkpoint: Roads, polylines, and polygons on the map render using the applied style.

• [ ] Controls the visibility of map features such as points of interest, water, parks, and land areas.

Read [references/display-hide-map-features.md](references/display-hide-map-features.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When simplifying the map view or focusing on specific data layers. Evidence Checkpoint: The specified map feature category is either visible or hidden on the map.

• [ ] Customizes the appearance of icons and text labels associated with map features.

Read [references/change-the-style-icons-and-text-labels-map.md](references/change-the-style-icons-and-text-labels-map.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When customizing the labeling system or POI markers shown by default on the base map. Evidence Checkpoint: Text labels and feature icons display the customized appearance (e.g., color, visibility).

• [ ] Defines rules to automatically switch or refine map styles based on the current zoom level.

Read [references/apply-different-map-styles-different-zoom-levels.md](references/apply-different-map-styles-different-zoom-levels.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When map aesthetics or data presentation needs to adapt dynamically based on zoom level. Evidence Checkpoint: The map style changes upon zooming in or out past defined thresholds.

• [ ] Adjusts the number of points of interest (POI) markers displayed on the map.

Read [references/change-the-density-places-map.md](references/change-the-density-places-map.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When controlling visual clutter by adjusting the density of dynamically loaded POIs. Evidence Checkpoint: The map displays fewer or more POI markers based on the configured density setting.

• [ ] Customizes the visual appearance of 3D building models and footprints on the map.

Read [references/change-the-style-buildings-map.md](references/change-the-style-buildings-map.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When highlighting or de-emphasizing building geometry. Evidence Checkpoint: Building features render with the specified custom style (e.g., color, texture).

• [ ] Modifies the presentation of known landmarks on the map.

Read [references/change-the-style-landmarks-map.md](references/change-the-style-landmarks-map.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When specific prominent map features (landmarks) require custom visual treatment. Evidence Checkpoint: Landmarks are displayed according to the configured custom style.

🗺️ Feature Module: Data-driven styling for boundaries (Optional - Use-Case Dependent)

• [ ] Applies custom visual styles to administrative boundaries (e.g., countries, states, postal codes) displayed on the map.

Read [references/change-the-style-boundaries-map.md](references/change-the-style-boundaries-map.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When highlighting or styling geographic regions based on administrative data. Evidence Checkpoint: Administrative boundaries render with the customized color and stroke weight.

• [ ] Registers event listeners to react to user actions (like clicks or mouseovers) on map boundaries.

Read [references/respond-user-interactions-with-boundaries-map.md](references/respond-user-interactions-with-boundaries-map.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md", "change-the-style-boundaries-map.md"] Trigger Condition: When user interaction with geographic regions needs to trigger custom logic or display information. Evidence Checkpoint: A registered event handler fires upon interaction with a styled boundary feature.

• [ ] Applies shading or coloring to boundaries based on associated quantitative data (choropleth maps).

Read [references/add-choropleth-styling-map.md](references/add-choropleth-styling-map.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md", "change-the-style-boundaries-map.md"] Trigger Condition: When visualizing geographical distribution of data values (e.g., population density). Evidence Checkpoint: Boundaries are shaded continuously based on the input data values.

🗺️ Feature Module: Datasets (Optional - Use-Case Dependent)

• [ ] Loads and displays geospatial data stored in Keyhole Markup Language (KML) format as a layer on the map.

Read [references/add-kml-layer-map.md](references/add-kml-layer-map.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When integrating external KML files containing points, lines, or polygons. Evidence Checkpoint: Geospatial features defined in the KML file appear as an overlay on the map.

• [ ] Loads and displays syndicated geospatial data feeds defined using GeoRSS format.

Read [references/add-georss-layer-map.md](references/add-georss-layer-map.md). Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When displaying frequently updated geospatial content from an RSS feed. Evidence Checkpoint: Features from the GeoRSS feed are rendered on the map.

• [ ] Parses and adds geospatial data structured in GeoJSON format directly onto the map.

Read [references/add-geojson-data-map.md](references/add-geojson-data-map.md). *De

…

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.