Capacitor Google Maps Plugin

The @capacitor-community/google-maps plugin provides Capacitor developers with access to the native Google Maps SDK for Android and iOS.

Key Benefits

• Performance: Uses native SDKs which offer significantly better performance than the JavaScript-based equivalent.
• Offline Support: Enables support for offline caching via the native SDKs.
• Cost Efficiency: Uses 'Dynamic Maps' via the native SDK, which is free to use (as of February 2022), unlike the Google Maps JavaScript SDK which follows a different pricing model.

Important Limitations

• Fixed Positioning: The rendered Map view cannot currently scroll along with the page; it remains at a fixed position.
• Platform Support: This plugin only supports native iOS and Android SDKs. It does not include a web implementation (JavaScript SDK). If you require web support, you must implement the JavaScript SDK separately.

To display a map, you must first initialize the SDK with your API key and then create a map instance by providing the bounding rectangle of a 'foster element' in your HTML.

Steps:

1. Initialize the SDK: Call CapacitorGoogleMaps.initialize() with your API key and the current window.devicePixelRatio.
2. Identify the Foster Element: Select the HTML element where the map should appear.
3. Calculate Boundaries: Use getBoundingClientRect() to get the element's position and size.
4. Create the Map: Call CapacitorGoogleMaps.createMap() using the calculated boundaries.
5. Prepare the UI:
   • Remove the background color of the foster element so the native map is visible through the WebView.
   • Set the data-maps-id attribute on the foster element using the mapId from the result to allow the plugin to delegate touch events correctly.

import { CapacitorGoogleMaps } from "@capacitor-community/google-maps";

const initializeMap = async () => {
  // 1. Initialize the Maps SDK
  await CapacitorGoogleMaps.initialize({
    key: "YOUR_IOS_MAPS_API_KEY",
    devicePixelRatio: window.devicePixelRatio, // This line is critical
  });

  // 2. Get the foster element
  const element = document.getElementById("container");

  // 3. Get boundaries
  const boundingRect = element.getBoundingClientRect();

  try {
    // 4. Create the map
    const result = await CapacitorGoogleMaps.createMap({
      boundingRect: {
        width: Math.round(boundingRect.width),
        height: Math.round(boundingRect.height),
        x: Math.round(boundingRect.x),
        y: Math.round(boundingRect.y),
      },
    });

    // 5. Prepare the UI
    // Remove background so map can be seen
    element.style.background = "";

    // Set data-maps-id for touch event delegation
    element.setAttribute("data-maps-id", result.googleMap.mapId);

    alert("Map loaded successfully");
  } catch (e) {
    alert("Map failed to load");
  }
};

initializeMap();

Deciding whether to use the @capacitor-community/google-maps plugin depends on your app's core functionality, performance requirements, and budget. This plugin uses the native Maps SDK for Android and iOS, which offers better performance and offline caching support compared to the JavaScript SDK.

Use this plugin if:

• Map-centric apps: Your app's primary purpose revolves around maps (e.g., ride-sharing or scooter-sharing apps).
• Performance needs: You need to render many markers or require high-performance map interactions.
• Cost optimization: You want to leverage the native 'Dynamic Maps' pricing, which may be more cost-effective than the JavaScript SDK depending on your usage.

Avoid this plugin if:

• Static displays: You only need to show a single location (e.g., a restaurant address). In this case, using a free Google Maps iframe embed is simpler and more cost-effective.
• Existing JS SDK success: You are already using the Google Maps JavaScript SDK and are not experiencing performance issues or exceeding free tier limits. The overhead of implementing the native plugin may not be justified.

Geocoding (converting addresses to coordinates) and Reverse Geocoding (converting coordinates to addresses) are not implemented in this plugin. You can implement these features using the official Google Maps Geocoding API via direct HTTP requests or the official JavaScript SDK.

Geocoding (Address to Coordinates)

Direct API URL: https://maps.googleapis.com/maps/api/geocode/json?address=ADDRESS&key=YOUR_API_KEY

Using JavaScript SDK:

geocoder
  .geocode({ address: "Some address" })
  .then((response) => {
    if (response.results[0]) {
      console.log(response.results);
    } else {
      console.log("No results found");
    }
  })
  .catch((e) => console.error(e));

Reverse Geocoding (Coordinates to Address)

Direct API URL: https://maps.googleapis.com/maps/api/geocode/json?latlng=LAT,LNG&key=YOUR_API_KEY

Using JavaScript SDK:

geocoder
  .geocode({ location: { lat: 40.731, lng: -73.997 } })
  .then((response) => {
    if (response.results[0]) {
      console.log(response.results);
    } else {
      console.log("No results found");
    }
  })
  .catch((e) => console.error(e));