maps-javascript-api-javascript

name	maps-javascript-api-javascript
description	Use this skill to build highly performant, customizable, and interactive 2D and 3D map experiences for the web using JavaScript. Implement features like advanced markers, location search, routing/directions, geospatial data visualization, and real-time fleet tracking, adhering strictly to modern API standards like the Routes and Places (New) classes.
license	Apache-2.0
metadata	{"version":"1.0.44"}

[!IMPORTANT] Core Dependency: This skill requires active context from 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., <gmp-map>, <gmp-map-3d>, <gmp-place-autocomplete>, or Places UI Kit elements), the ID must be provided as an HTML attribute.

<!-- Applies to gmp-map, gmp-map-3d, gmp-place-details, etc. -->
<gmp-map 
    center="40.749933,-73.98633" 
    map-id="DEMO_MAP_ID" 
    internal-usage-attribution-ids="gmp_git_agentskills_v1">
</gmp-map>

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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When rendering data using the standard GeoJSON specification. Evidence Checkpoint: GeoJSON features (points, lines, polygons) are displayed on the map.

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

• Allows creation and management of reusable geospatial datasets accessible across the platform. Read references/create-reusable-cross-platform-geospatial-dataset.md. Trigger Condition: When defining a structured set of geospatial data intended for map display and interaction. Evidence Checkpoint: A unique dataset ID is successfully created and registered.
• Adds a previously created custom dataset as a visual layer on the map. Read references/add-custom-geospatial-dataset-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md", "create-reusable-cross-platform-geospatial-dataset.md"] Trigger Condition: When displaying custom, structured geospatial data defined through the platform. Evidence Checkpoint: Features from the custom dataset appear on the map.
• Applies custom visual styling to the geometric features contained within a custom dataset layer. Read references/change-the-style-custom-dataset-features-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md", "add-custom-geospatial-dataset-map.md"] Trigger Condition: When custom presentation rules are needed for features in the dataset (e.g., color coding based on attributes). Evidence Checkpoint: Dataset features render with the specified custom styling.
• Handles user events (clicks, hovers) specifically targeting features within a custom geospatial dataset. Read references/respond-user-interactions-with-custom-dataset-features-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md", "add-custom-geospatial-dataset-map.md"] Trigger Condition: When user interaction with dataset elements needs to trigger custom logic or UI changes. Evidence Checkpoint: The event listener successfully captures interaction with a custom dataset feature.

🗺️ Feature Module: Directions and Routing (Optional - Use-Case Dependent)

• Calculates detailed directions, returning them as a series of steps with maneuver descriptions (e.g., 'Turn left onto Main St'). Read references/return-directions-between-two-more-sets-latitude-longitude-coordinates-series-maneuver.md. Trigger Condition: When detailed, turn-by-turn routing instructions are required. Evidence Checkpoint: The response contains an array of steps, each describing a maneuver.
• Provides the distance covered in each individual step of a calculated route. Read references/return-the-distance-between-each-step-along-route-between-two.md. Dependencies: ["return-directions-between-two-more-sets-latitude-longitude-coordinates-series-maneuver.md"] Trigger Condition: When needing granular distance metrics for route segments. Evidence Checkpoint: Each step object in the route response includes distance values.
• Provides the estimated travel time for each individual step of a calculated route. Read references/return-the-travel-time-between-each-step-along-route-between.md. Dependencies: ["return-directions-between-two-more-sets-latitude-longitude-coordinates-series-maneuver.md"] Trigger Condition: When needing granular time estimates for route segments. Evidence Checkpoint: Each step object in the route response includes duration values.
• Returns a compressed polyline string representing the path taken in each step of the route. Read references/return-encoded-polyline-between-each-step-along-route-between-two.md. Dependencies: ["return-directions-between-two-more-sets-latitude-longitude-coordinates-series-maneuver.md"] Trigger Condition: When optimizing the visualization of step-by-step paths on a map. Evidence Checkpoint: The route response provides an encoded polyline string for each step leg.
• Calculates and returns the total distance of the entire route between origin and destination(s). Read references/return-the-distance-for-route-between-two-more-sets-latitude-longitude.md. Trigger Condition: When only the aggregate route distance is required. Evidence Checkpoint: The route response summary includes the total distance.
• Calculates and returns the total estimated travel time for the entire route. Read references/return-the-travel-time-for-route-between-two-more-sets.md. Trigger Condition: When only the aggregate travel time is required. Evidence Checkpoint: The route response summary includes the total duration.
• Returns a single compressed polyline string representing the entire route path. Read references/return-encoded-polyline-for-route-between-two-more-sets-latitude-longitude.md. Trigger Condition: When visualizing the complete route path efficiently on a map. Evidence Checkpoint: The route response provides a single encoded polyline string for the entire route.
• Allows selection of the preferred transportation method (driving, walking, transit, cycling, or motorcycling) for routing calculations. Read references/specify-the-travel-mode-drive-transit-walk-two-wheeled-for-route.md. Dependencies: ["return-the-distance-for-route-between-two-more-sets-latitude-longitude.md"] Trigger Condition: When optimizing the route calculation based on user vehicle or activity. Evidence Checkpoint: The route calculation uses the specified travel mode.
• Defines intermediate stops (waypoints) that the calculated route must include. Read references/specify-stop-pass-through-point-for-route-request.md. Dependencies: ["return-the-distance-for-route-between-two-more-sets-latitude-longitude.md"] Trigger Condition: When calculating multi-stop trips or optimized delivery routes. Evidence Checkpoint: The resulting route passes through all specified waypoints.
• Configures how real-time or historical traffic data influences travel time estimates and route selection. Read references/specify-how-traffic-data-used-route-request.md. Dependencies: ["return-the-travel-time-for-route-between-two-more-sets.md"] Trigger Condition: When realistic travel time estimates factoring in congestion are needed. Evidence Checkpoint: Route duration reflects current or predicted traffic conditions.
• Excludes specific route features (e.g., tolls, highways, ferries) from the calculated route. Read references/specify-features-avoid-such-highways-tolls-for-route-request.md. Dependencies: ["return-the-distance-for-route-between-two-more-sets-latitude-longitude.md"] Trigger Condition: When the user wishes to customize the route based on preferences or cost avoidance. Evidence Checkpoint: The resulting route avoids the specified features.
• Requests routes optimized for shorter distance or retrieves alternative viable routes. Read references/specify-shorter-distance-alternative-routing-for-routes-request.md. Dependencies: ["return-the-distance-for-route-between-two-more-sets-latitude-longitude.md"] Trigger Condition: When providing users with choices or prioritizing distance over time/maneuver complexity. Evidence Checkpoint: The response includes one or more alternative routes or the shortest possible route.
• Calculates the driving distance between a large matrix of origin-destination pairs. Read references/return-distances-for-matrix-routes-between-multiple-origins-and-destinations.md. Trigger Condition: When calculating logistics costs or determining reachability across many points. Evidence Checkpoint: The response is a matrix containing distances for all requested pairs.
• Calculates the estimated travel time between a large matrix of origin-destination pairs. Read references/return-travel-times-for-matrix-routes-between-multiple-origins-and.md. Trigger Condition: When optimizing resource allocation based on travel time across many points. Evidence Checkpoint: The response is a matrix containing durations for all requested pairs.
• Specifies the mode of transport (e.g., driving, walking) for Distance Matrix calculations. Read references/specify-the-travel-mode-drive-transit-walk-two-wheeled-for-route.md. Dependencies: ["return-distances-for-matrix-routes-between-multiple-origins-and-destinations.md", "return-travel-times-for-matrix-routes-between-multiple-origins-and.md"] Trigger Condition: When the matrix calculation must adhere to a specific travel method. Evidence Checkpoint: Matrix results reflect travel metrics based on the specified mode.

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

• Retrieves the ground elevation (in meters) for specified latitude/longitude coordinates. Read references/return-the-elevation-set-latitude-longitude-coordinates.md. Trigger Condition: When determining the altitude of specific points on the Earth's surface. Evidence Checkpoint: The response includes elevation values for the input coordinates.
• Samples elevation data along a defined path to determine elevation change (profile). Read references/return-the-difference-elevation-along-path-between-two-more-sets.md. Trigger Condition: When calculating gradient or visualizing terrain profile along a route. Evidence Checkpoint: The response includes a series of sampled elevation points along the path.

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

• Adds markers to the map representing the current real-time locations of Fleet Engine delivery vehicles and their associated tasks. Read references/add-the-real-time-location-fleet-engine-delivery-vehicles-and-tasks.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When visualizing live delivery logistics and vehicle tracking. Evidence Checkpoint: Delivery vehicle markers appear on the map and update based on real-time location data.
• Displays the calculated and predicted path the delivery vehicle will take to complete its route and tasks. Read references/add-the-predicted-routes-fleet-engine-delivery-vehicles-and-tasks.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md", "add-the-real-time-location-fleet-engine-delivery-vehicles-and-tasks.md"] Trigger Condition: When showing dispatchers or customers the expected route trajectory. Evidence Checkpoint: Polylines representing the predicted vehicle path are rendered on the map.
• Adds comprehensive visual annotations including vehicle position, planned stops, and task markers to a map. Read references/add-fleet-engine-delivery-vehicle-s-location-stops-tasks-and-waypoint.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md", "add-the-real-time-location-fleet-engine-delivery-vehicles-and-tasks.md"] Trigger Condition: When a complete overview of a vehicle's current status and itinerary is required. Evidence Checkpoint: All relevant logistics markers (vehicle, stops, tasks) are present on the map.
• Allows the application to react to state changes in the delivery process, such as trip completion or segment updates. Read references/respond-fleet-engine-delivery-vehicle-events-including-completed-trips-segments.md. Dependencies: ["add-the-real-time-location-fleet-engine-delivery-vehicles-and-tasks.md"] Trigger Condition: When workflow automation or UI updates are required based on vehicle progress events. Evidence Checkpoint: The application successfully receives and processes Fleet Engine event callbacks.
• Customizes the appearance of base map roads, polylines, and polygons specifically within a Fleet Tracking map instance. Read references/change-the-style-roads-polylines-and-polygons-fleet-engine-fleet.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When specialized base map styling is needed for fleet tracking visualizations. Evidence Checkpoint: Base map geometries inside the Fleet Engine view are custom-styled.
• Controls the visibility of standard map features (e.g., POIs, water) within a Fleet Tracking map. Read references/display-hide-map-features-fleet-engine-fleet-tracking-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When simplifying the map to focus solely on fleet logistics data. Evidence Checkpoint: Specified map features are hidden or displayed within the Fleet Engine map view.
• Customizes icons and text labels of map features used in the Fleet Engine visualization. Read references/change-the-style-icons-and-text-labels-fleet-engine-fleet.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When branding or visual consistency requires customizing feature labels in the tracking view. Evidence Checkpoint: Map labels and icons reflect the custom styling within the Fleet Engine map.
• Applies variable styling rules to the Fleet Tracking map depending on the current zoom level. Read references/apply-different-map-styles-different-zoom-levels-fleet-engine-fleet.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When optimizing map presentation dynamically for different scales of fleet monitoring. Evidence Checkpoint: Map styling changes when the user zooms in or out of the Fleet Engine map.
• Adjusts the number of points of interest displayed specifically on the Fleet Tracking map. Read references/change-the-density-places-fleet-engine-fleet-tracking-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When controlling visual clutter in the fleet tracking environment. Evidence Checkpoint: POI density changes according to configuration in the tracking map view.
• Customizes the visual appearance of buildings within the Fleet Tracking map instance. Read references/change-the-style-buildings-fleet-engine-fleet-tracking-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When prioritizing or de-emphasizing building geometry in the tracking view. Evidence Checkpoint: Building features render with the specified style in the Fleet Engine map.
• Customizes the visual appearance of prominent landmarks within the Fleet Tracking map. Read references/change-the-style-landmarks-fleet-engine-fleet-tracking-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When ensuring visibility or styling consistency for major landmarks in the tracking view. Evidence Checkpoint: Landmarks are displayed according to the configured custom style in the Fleet Engine map.
• Allows custom iconography, shape, and behavior for markers representing vehicles or tasks in the Fleet Engine view. Read references/customize-marker-fleet-engine-fleet-tracking-map.md. Dependencies: ["add-the-real-time-location-fleet-engine-delivery-vehicles-and-tasks.md"] Trigger Condition: When specific branding or state indicators are needed for fleet markers. Evidence Checkpoint: Vehicle and task markers use the custom defined icons/styles.
• Customizes the appearance (color, thickness) of the route polylines displayed for Fleet Engine vehicles. Read references/customize-the-route-polyline-fleet-engine-fleet-tracking-map.md. Dependencies: ["add-the-predicted-routes-fleet-engine-delivery-vehicles-and-tasks.md"] Trigger Condition: When differentiating route segments or applying branding to the path visualization. Evidence Checkpoint: The route polyline renders with the customized styling.

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

• Converts a human-readable address into precise latitude and longitude coordinates (Forward Geocoding). Read references/return-the-latitude-longitude-coordinates-address-geocoding.md. Trigger Condition: When finding the geographic position of a given street address. Evidence Checkpoint: The response includes a geocoded location object with valid lat/lng.
• Converts latitude and longitude coordinates back into a human-readable address (Reverse Geocoding). Read references/return-the-address-for-set-latitude-longitude-coordinates-reverse-geocoding.md. Trigger Condition: When identifying the physical location corresponding to a set of coordinates. Evidence Checkpoint: The response includes a formatted address string.

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

• Displays a floating content box (InfoWindow) anchored to a specific location or annotation on the map. Read references/add-info-window-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When showing detailed, contextual information upon user interaction with a map feature (e.g., clicking a marker). Evidence Checkpoint: An InfoWindow containing the specified content appears upon trigger.
• Adds geometric overlays (Polylines, Polygons, Circles, Rectangles) to the map. Read references/add-shape-line-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When highlighting areas, defining boundaries, or illustrating paths. Evidence Checkpoint: The specified shape or line feature is rendered on the map.
• Uses scalable vector graphics (SVG) to define custom icons for markers or annotations, ensuring high resolution. Read references/add-vector-based-icon-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When requiring resolution-independent, complex marker designs. Evidence Checkpoint: A marker using the SVG definition is displayed clearly at various zoom levels.
• Integrates high-performance, WebGL-powered deck.gl visualizations (e.g., heatmaps, 3D visualizations) as layers on the map. Read references/add-deck-gl-overlays-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When rendering large datasets or complex analytical visualizations efficiently. Evidence Checkpoint: The deck.gl visualization layer appears above the standard map tiles.
• Grounds an image overlay (GroundOverlay) to specific geographical coordinates on the map, distorting appropriately with projection. Read references/add-overlay-image-grounded-the-surface-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When displaying static, geographically registered images like floor plans or historical maps. Evidence Checkpoint: The image appears anchored to the specified bounds on the map.
• Defines and loads custom map tiles from an external source to overlay the base map. Read references/add-custom-tile-overlay-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When using proprietary or highly specialized map tile sets. Evidence Checkpoint: The map displays custom tiles seamlessly integrated with the base map.
• Places a standard default marker (pin) at a specified location on the map. Read references/add-marker-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When indicating a simple point of interest or location. Evidence Checkpoint: A visible marker icon is displayed at the specified coordinates.
• Customizes the icon, animation, opacity, and accessibility properties of a map marker. Read references/customize-marker-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md", "add-marker-map.md"] Trigger Condition: When standard markers need visual differentiation or specialized behavior. Evidence Checkpoint: The marker renders with the custom properties (e.g., custom image icon, specified size).
• Registers event handlers for user interactions such as clicks, drags, or mouseovers on map markers. Read references/respond-user-interactions-with-markers-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md", "add-marker-map.md"] Trigger Condition: When markers need to be interactive and trigger application logic. Evidence Checkpoint: The defined handler function executes when the user interacts with the marker.

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

• Creates a Map ID used to centrally manage and reference configuration and styling settings across map instances. Read references/create-reusable-map-identifier-store-map-configuration-and-styling-settings.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When applying consistent, cloud-managed styling and features to multiple maps. Evidence Checkpoint: A map object is initialized referencing the specified Map ID.
• Allows registration of listeners for events such as map clicks, camera movement, or idle state changes. Read references/respond-user-interactions-and-events-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When application state needs to react to overall map interaction. Evidence Checkpoint: The registered event listener fires upon the specified map event.
• Configures which default UI elements (zoom controls, scale, map type selector) are visible and their placement. Read references/customize-the-controls-that-appear-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When adapting the map UI to match application design constraints or user needs. Evidence Checkpoint: Only the specified map controls are rendered in the viewport.
• Programmatically sets the map's center, zoom level, tilt, and bearing. Read references/control-zoom-and-pan-map-camera.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When moving the map to display a specific area or animating the viewport. Evidence Checkpoint: The map view successfully transitions to the target coordinates and zoom level.
• Switches the base tile layer displayed (e.g., Roadmap, Satellite, Terrain, Hybrid). Read references/change-the-map-type.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When changing the visual representation of the underlying geography. Evidence Checkpoint: The map background tiles update to the requested type.
• Applies a predefined color palette or custom styling to the base map features. Read references/change-the-map-color-scheme.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When implementing light mode, dark mode, or specialized thematic styling. Evidence Checkpoint: Map colors adhere to the selected color scheme configuration.
• Configures the map to display feature names, region bias, and routing directions based on a specified language and region. Read references/localize-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When deploying the application internationally and requiring locale-specific map content. Evidence Checkpoint: Map labels are displayed in the requested language.
• Overlays real-time traffic conditions onto the map. Read references/add-traffic-layer-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When visualizing current congestion levels on roadways. Evidence Checkpoint: Road segments are colored according to real-time traffic speeds.
• Overlays public transportation routes, stops, and icons onto the map. Read references/add-transit-layer-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When providing navigation or context related to public transit systems. Evidence Checkpoint: Transit lines and station markers appear on the map.
• Overlays dedicated bicycling paths and routes onto the map. Read references/add-bicycling-layer-map.md. Dependencies: ["add-customizable-interactive-map-web-page-mobile-app.md"] Trigger Condition: When providing navigation or context related to cycling infrastructure. Evidence Checkpoint: Designated bike routes are highlighted on the map.

🗺️ Feature Module: Photorealistic 3D maps (Optional - Use-Case Dependent)

• Initializes and displays a high-fidelity, photorealistic 3D globe view capable of tilting and rotation. Read references/add-interactive-photorealistic-map-web-page.md. Trigger Condition: When immersive 3D visualization and navigation are required. Evidence Checkpoint: The 3D map engine loads and displays tilted, photorealistic terrain/buildings.
• Adds a standard marker pin to the 3D map environment. Read references/add-marker-photorealistic-map.md. Dependencies: ["add-interactive-photorealistic-map-web-page.md"] Trigger Condition: When marking locations within the photorealistic 3D view. Evidence Checkpoint: A marker appears anchored to the specified coordinates in 3D space.
• Customizes the visual properties of markers placed on the photorealistic 3D map. Read references/customize-marker-photorealistic-map.md. Dependencies: ["add-interactive-photorealistic-map-web-page.md", "add-marker-photorealistic-map.md"] Trigger Condition: When markers need custom icons or behavior in the 3D environment. Evidence Checkpoint: The 3D marker renders using the custom styling.
• Loads and displays a custom 3D model object anchored to a location on the photorealistic map. Read references/add-model-photorealistic-map.md. Dependencies: ["add-interactive-photorealistic-map-web-page.md"] Trigger Condition: When integrating proprietary 3D content (e.g., custom buildings, vehicles) into the view. Evidence Checkpoint: The custom 3D model is rendered in the correct position on the map.
• Adds general geometric or image overlays that interact correctly with the 3D terrain. Read references/add-overlay-photorealistic-map.md. Dependencies: ["add-interactive-photorealistic-map-web-page.md"] Trigger Condition: When adding non-marker visual context that adheres to the 3D projection. Evidence Checkpoint: The overlay appears correctly projected onto the 3D surface.
• Draws a line (Polyline) in 3D space, potentially draping along the terrain or suspended in the air. Read references/add-polyline-photorealistic-map.md. Dependencies: ["add-interactive-photorealistic-map-web-page.md"] Trigger Condition: When visualizing routes, paths, or linear data in the 3D environment. Evidence Checkpoint: A polyline segment is visible in the 3D map.
• Draws a closed shape (Polygon) in 3D space, used to define areas or regions. Read references/add-polygon-photorealistic-map.md. Dependencies: ["add-interactive-photorealistic-map-web-page.md"] Trigger Condition: When highlighting geographical areas in the 3D environment. Evidence Checkpoint: A polygon feature is rendered and appears on the 3D map surface.
• Handles user events specific to the 3D map view, such as clicks, camera movement, and animation finished events. Read references/respond-user-interactions-and-events-photorealistic-map.md. Dependencies: ["add-interactive-photorealistic-map-web-page.md"] Trigger Condition: When application logic needs to respond to user interaction within the 3D environment. Evidence Checkpoint: The event handler successfully fires upon a specified 3D map event.
• Configures the display and visibility of default controls (e.g., zoom, tilt) on the 3D map. Read references/customize-the-controls-that-appear-photorealistic-map.md. Dependencies: ["add-interactive-photorealistic-map-web-page.md"] Trigger Condition: When customizing the 3D map's user interface. Evidence Checkpoint: The 3D map renders only the configured control elements.
• Programmatically controls the camera's position, rotation, and animated fly-throughs in the 3D view. Read references/control-camera-path-and-animations-photorealistic-map.md. Dependencies: ["add-interactive-photorealistic-map-web-page.md"] Trigger Condition: When guiding the user through specific locations or creating cinematic sequences. Evidence Checkpoint: The camera executes the programmed animation path.
• Restricts the user's ability to move or rotate the camera beyond specified boundaries or limits in the 3D map. Read references/control-camera-restrictions-photorealistic-map.md. Dependencies: ["add-interactive-photorealistic-map-web-page.md"] Trigger Condition: When focusing user attention on a specific geographic region or preventing excessive tilt/zoom. Evidence Checkpoint: User attempts to move the camera outside the defined bounds are blocked.

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

• Performs a text search to find relevant places based on a user-provided string (e.g., 'pizza near me'). Read references/return-list-places-and-place-details-based-query-string.md. Trigger Condition: When the user explicitly searches for a location or business type using keywords. Evidence Checkpoint: The response returns a list of Places matching the query string.
• Finds a list of points of interest located within a specified radius of a given coordinate (Nearby Search). Read references/return-list-places-and-place-details-near-specific-location.md. Trigger Condition: When discovering relevant places close to a central location. Evidence Checkpoint: The response returns a list of Places falling within the defined geographical boundary.
• Provides predictive text results for places as the user types, improving search efficiency. Read references/return-autocomplete-results-about-places-based-query-string.md. Trigger Condition: When providing interactive, real-time suggestions during user input in a search field. Evidence Checkpoint: A list of place predictions appears dynamically below the input field.
• Retrieves comprehensive information (address, phone number, hours, reviews) for a single Place ID. Read references/return-detailed-information-about-specific-place.md. Trigger Condition: When a user selects a place prediction or marker and requires full details. Evidence Checkpoint: The response includes the Place Details object corresponding to the requested Place ID.
• Retrieves references and metadata for user-contributed photographs associated with a Place. Read references/return-photos-specific-place.md. Dependencies: ["return-detailed-information-about-specific-place.md"] Trigger Condition: When displaying visual context for a selected place. Evidence Checkpoint: The response includes an array of Photo objects/references.
• Requests photo images from the service, specifying required dimensions to optimize loading and bandwidth. Read references/resize-place-photos.md. Dependencies: ["return-photos-specific-place.md"] Trigger Condition: When displaying place photos in a specific layout size in the UI. Evidence Checkpoint: The returned photo image URL loads an image matching the specified height/width constraints.
• Retrieves user-generated ratings and written reviews for a specified place. Read references/return-ratings-and-reviews-for-specific-place.md. Dependencies: ["return-detailed-information-about-specific-place.md"] Trigger Condition: When showing community feedback and quality indicators for a business or location. Evidence Checkpoint: The response includes aggregated rating data and an array of individual review objects.
• Implements a pre-built UI widget that provides address and place prediction suggestions in a search bar. Read references/add-autocomplete-widget-web-page-app-that-returns-results-about.md. Trigger Condition: When quickly implementing interactive address or place search functionality. Evidence Checkpoint: The input field dynamically displays suggestions as the user types.
• Filters search and prediction results to include only specific categories of places (e.g., 'restaurant', 'store'). Read references/specify-the-place-types-include-place-information-responses.md. Dependencies: ["return-list-places-and-place-details-based-query-string.md", "return-autocomplete-results-about-places-based-query-string.md"] Trigger Condition: When limiting search results to relevant business or location types. Evidence Checkpoint: Search results exclusively contain places matching the specified type filter.

🗺️ Feature Module: Places UI Kit (Optional - Use-Case Dependent)

• Adds a reusable UI component that displays AI-generated summaries and synthesized reviews for a place. Read references/add-element-that-displays-ai-powered-summaries-and-reviews-about-specific.md. Trigger Condition: When presenting a concise, summarized overview of a place using advanced review analysis. Evidence Checkpoint: The AI summary UI component successfully loads and displays content for the selected place.
• Applies custom cascading style sheets (CSS) to Places UI Kit components for tailored visual integration. Read references/apply-css-styling-place-data-element.md. Dependencies: ["add-element-that-displays-information-about-specific-place-web-page.md"] Trigger Condition: When modifying the appearance, layout, or theme of Places UI Kit components. Evidence Checkpoint: The UI Kit element renders using the specified CSS styles.
• Utilizes a configuration tool to graphically customize the look and function of Places UI Kit elements. Read references/customize-place-data-element-styling-and-configurations-with-element-customization.md. Dependencies: ["add-element-that-displays-information-about-specific-place-web-page.md"] Trigger Condition: When simplifying styling customization without direct CSS manipulation. Evidence Checkpoint: The UI element incorporates changes defined via the customization tool.
• Adds a UI component displaying general details (address, hours, contact) for a single specified place. Read references/add-element-that-displays-information-about-specific-place-web-page.md. Trigger Condition: When presenting standard detailed information for a place selection. Evidence Checkpoint: The Place Details UI element loads and shows structured data.
• Adds a dynamically updating UI list displaying places matching a user's textual search query. Read references/add-element-that-displays-list-places-based-query-string-web.md. Trigger Condition: When integrating text search results directly into a structured list component. Evidence Checkpoint: The component successfully executes a text search and populates the list view.
• Adds a UI list component that shows places retrieved via a nearby search relative to a given location. Read references/add-element-that-displays-list-places-near-specific-location-web.md. Trigger Condition: When displaying nearby points of interest relevant to the map's center or user location. Evidence Checkpoint: The component populates with places detected near the reference coordinates.
• Adds a lightweight autocomplete input field that returns Google Place IDs and basic text predictions. Read references/add-basic-autocomplete-element-web-page-app-that-returns-google.md. Trigger Condition: When requiring a simple, fast input mechanism for place searching that returns only the ID. Evidence Checkpoint: Typing in the input box triggers suggestions, and selection returns a Place ID.

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

• Initializes and embeds an interactive Street View Panorama viewer focused on a specified location. Read references/add-configurable-interactive-google-street-view-web-page-mobile-app.md. Trigger Condition: When displaying 360-degree ground-level imagery. Evidence Checkpoint: A Street View panorama loads and is displayed in the viewport.
• Places markers or geometric overlays within the Street View panorama, projecting onto the 360-degree image. Read references/add-marker-overlay-google-street-view.md. Dependencies: ["add-configurable-interactive-google-street-view-web-page-mobile-app.md"] Trigger Condition: When annotating points of interest visible within the Street View environment. Evidence Checkpoint: The marker or overlay object appears projected correctly inside the panorama.
• Registers event listeners for interactions within the panorama (e.g., clicks, position changes, view direction changes). Read references/respond-user-interactions-and-events-google-street-view.md. Dependencies: ["add-configurable-interactive-google-street-view-web-page-mobile-app.md"] Trigger Condition: When application state needs to track user navigation within Street View. Evidence Checkpoint: The event handler fires upon specified Street View interaction.
• Configures the visibility of default UI controls (e.g., zoom, navigation arrows) within the Street View viewer. Read references/customize-the-controls-that-appear-google-street-view.md. Dependencies: ["add-configurable-interactive-google-street-view-web-page-mobile-app.md"] Trigger Condition: When simplifying the Street View UI or integrating custom navigation. Evidence Checkpoint: Only the configured controls are visible in the panorama overlay.
• Retrieves the nearest available Street View panorama metadata (ID, coordinates) for a given location. Read references/return-google-street-view-panorama-for-specific-location.md. Trigger Condition: When confirming Street View coverage or retrieving panorama metadata programmatically. Evidence Checkpoint: A Panorama object containing location and camera metadata is returned.

📦 Phase 3: Operational Constraints & Guardrails (Constraint)

• Step 3.1: Allows the user to explicitly define which fields (data categories) are requested in Place Details responses to minimize cost and latency. Read references/specify-the-data-fields-included-place-information-responses.md. Dependencies: ["return-detailed-information-about-specific-place.md"] Trigger Condition: When optimizing API usage costs or reducing response payload size. Evidence Checkpoint: The Place Details response payload contains only the fields explicitly requested.