Skip to content

feat(pydeck): add mapId support for Google Maps#10084

Open
n0531m wants to merge 2 commits intovisgl:masterfrom
n0531m:feat/google-maps-mapid
Open

feat(pydeck): add mapId support for Google Maps#10084
n0531m wants to merge 2 commits intovisgl:masterfrom
n0531m:feat/google-maps-mapid

Conversation

@n0531m
Copy link
Copy Markdown

@n0531m n0531m commented Mar 11, 2026

This PR adds support for the mapId parameter when using Google Maps as a basemap provider in pydeck.

Specifying a mapId is required to enable Google Maps Vector Maps, which unlocks modern features such as:

  • 3D Perspective: Enables synchronized 3D tilt and rotation between the base map and deck.gl layers.
  • Vector Rendering: Provides smoother zooming and better performance for large datasets.
  • Custom Styling: Allows users to use Cloud-based Map Styling via the Google Maps Platform console.

This change includes updates to both the Python bindings (pydeck) and the JavaScript component (@deck.gl/jupyter-widget) to ensure seamless
synchronization in Jupyter environments, standalone HTML exports, and Google Colab.

Changes

Python (pydeck)

  • pydeck.Deck: Added google_maps_map_id support to the constructor (via api_keys dict) and automatic environment variable detection for
    GOOGLE_MAPS_MAP_ID.
  • pydeck.widget.DeckGLWidget: Added the google_maps_map_id traitlet to enable state synchronization between Python and the Jupyter frontend.
  • HTML Templates: Updated the Jinja2 template to propagate the Map ID to the createDeck initialization call.
  • Documentation: Updated docstrings for Deck and DeckGLWidget to include information on using Map IDs.

JavaScript (@deck.gl/jupyter-widget)

  • Model: Added google_maps_map_id to the Jupyter widget model defaults.
  • Map Initialization: Updated the Google Maps initialization utility to pass mapId to the google.maps.Map constructor.
  • Robustness: Ensured mapId is a truly optional parameter; it is only added to the map options if a valid ID is provided.

Example Usage

   import pydeck
   import os

   # Set environment variables or pass via api_keys
   os.environ["GOOGLE_MAPS_API_KEY"] = "YOUR_KEY"
   os.environ["GOOGLE_MAPS_MAP_ID"] = "YOUR_VECTOR_MAP_ID"

   view_state = pydeck.ViewState(
       latitude=37.7749, 
       longitude=-122.4194, 
       zoom=12, 
       pitch=45  # Now tilts the base map too!
   )

   deck = pydeck.Deck(
       map_provider="google_maps",
       initial_view_state=view_state
   )
   deck.show()

Testing Performed

  • Logic Verification: Confirmed Deck object correctly captures IDs from both constructor and environment variables.
  • Serialization Verification: Verified that google_maps_map_id is correctly excluded from the layer JSON to keep the configuration at the
    provider level.
  • HTML Export Verification: Confirmed that to_html() correctly generates the googleMapsMapId property in the frontend createDeck call.
  • Widget Verification: Confirmed traits are correctly synchronized between Python and the frontend model.

Related Issues
Enables official support for Google Maps Vector Maps, resolving gaps highlighted in several community issues (e.g., #9856, #8476) where users previously had to use manual workarounds to synchronize mapId.

@n0531m n0531m marked this pull request as draft March 13, 2026 09:16
@n0531m n0531m marked this pull request as ready for review March 13, 2026 09:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant