Migrate from Google Maps to MapMetrics in Flutter

This guide helps you switch your existing Flutter app from google_maps_flutter to MapMetrics. The APIs are very similar, so migration is straightforward.

Step 1: Update Dependencies

Replace the Google Maps dependency in your pubspec.yaml:

# Before (Google Maps)
dependencies:
  google_maps_flutter: ^2.5.0

# After (MapMetrics)
dependencies:
  mapmetrics: ^0.1.0

Then run:

flutter pub get

Step 2: Update Imports

// Before (Google Maps)
import 'package:google_maps_flutter/google_maps_flutter.dart';

// After (MapMetrics)
import 'package:mapmetrics/mapmetrics.dart';

Step 3: Update the Map Widget

The widget names and properties are very similar:

// Before (Google Maps)
GoogleMap(
  onMapCreated: (GoogleMapController controller) {
    _controller = controller;
  },
  initialCameraPosition: CameraPosition(
    target: LatLng(48.8566, 2.3522),
    zoom: 13.0,
  ),
  markers: _markers,
  polylines: _polylines,
  polygons: _polygons,
  circles: _circles,
  myLocationEnabled: true,
  myLocationButtonEnabled: true,
)

// After (MapMetrics)
MapMetrics(
  styleUrl: 'https://gateway.mapmetrics.org/styles/YOUR_STYLE_ID?token=YOUR_API_KEY',
  onMapCreated: (MapMetricsController controller) {
    _controller = controller;
  },
  initialCameraPosition: CameraPosition(
    target: LatLng(48.8566, 2.3522),
    zoom: 13.0,
  ),
  markers: _markers,
  polylines: _polylines,
  polygons: _polygons,
  circles: _circles,
  myLocationEnabled: true,
)

Key differences:

• GoogleMap → MapMetrics
• GoogleMapController → MapMetricsController
• You must provide a styleUrl (get it from MapMetrics Portal)

Step 4: Get MapMetrics Credentials

1. Go to portal.mapmetrics.org and create an account
2. Create an API Key under the "Keys" section
3. Create a Map Style under the "Styles" section
4. Copy your style URL (format: https://gateway.mapmetrics.org/styles/YOUR_STYLE_ID?token=YOUR_API_KEY)

API Comparison Table

Feature	Google Maps	MapMetrics
Widget	GoogleMap	MapMetrics
Controller	GoogleMapController	MapMetricsController
Style/Theme	mapType: MapType.normal	styleUrl: '...'
Camera Position	CameraPosition	CameraPosition (same)
LatLng	LatLng(lat, lng)	LatLng(lat, lng) (same)
Markers	Set<Marker>	Set<Marker> (same)
Polylines	Set<Polyline>	Set<Polyline> (same)
Polygons	Set<Polygon>	Set<Polygon> (same)
Circles	Set<Circle>	Set<Circle> (same)
Animate camera	animateCamera()	animateCamera() (same)
Move camera	moveCamera()	moveCamera() (same)
User location	myLocationEnabled	myLocationEnabled (same)
Zoom gestures	zoomGesturesEnabled	zoomGesturesEnabled (same)
API Key	In AndroidManifest / AppDelegate	In style URL

What Stays the Same

Most of your existing code can be reused directly:

• CameraPosition, LatLng, LatLngBounds — identical
• Marker, MarkerId, InfoWindow — identical
• Polyline, PolylineId — identical
• Polygon, PolygonId — identical
• Circle, CircleId — identical
• CameraUpdate methods — identical
• BitmapDescriptor — identical
• Gesture properties — identical

What Changes

Change	Details
No Google API key	Replace with MapMetrics style URL
Custom styles	Use MapMetrics Portal instead of Google Cloud Console
Map types	Use different style URLs instead of MapType enum
No Android API key in manifest	Remove com.google.android.geo.API_KEY from AndroidManifest
No iOS API key in AppDelegate	Remove GMSServices.provideAPIKey from AppDelegate
Community data	MapMetrics uses community-contributed map data

Remove Google Maps Config

Android

Remove from android/app/src/main/AndroidManifest.xml:

<!-- Remove this -->
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_GOOGLE_API_KEY"/>

iOS

Remove from ios/Runner/AppDelegate.swift:

// Remove this
GMSServices.provideAPIKey("YOUR_GOOGLE_API_KEY")

Complete Migration Example

// Before: Google Maps
import 'package:google_maps_flutter/google_maps_flutter.dart';

class MyMapScreen extends StatefulWidget {
  @override
  _MyMapScreenState createState() => _MyMapScreenState();
}

class _MyMapScreenState extends State<MyMapScreen> {
  GoogleMapController? _controller;

  @override
  Widget build(BuildContext context) {
    return GoogleMap(
      onMapCreated: (controller) => _controller = controller,
      initialCameraPosition: CameraPosition(
        target: LatLng(48.8566, 2.3522),
        zoom: 13,
      ),
      markers: {
        Marker(
          markerId: MarkerId('paris'),
          position: LatLng(48.8566, 2.3522),
          infoWindow: InfoWindow(title: 'Paris'),
        ),
      },
    );
  }
}

// After: MapMetrics (minimal changes!)
import 'package:mapmetrics/mapmetrics.dart';

class MyMapScreen extends StatefulWidget {
  @override
  _MyMapScreenState createState() => _MyMapScreenState();
}

class _MyMapScreenState extends State<MyMapScreen> {
  MapMetricsController? _controller;

  @override
  Widget build(BuildContext context) {
    return MapMetrics(
      styleUrl: 'https://gateway.mapmetrics.org/styles/YOUR_STYLE_ID?token=YOUR_API_KEY',
      onMapCreated: (controller) => _controller = controller,
      initialCameraPosition: CameraPosition(
        target: LatLng(48.8566, 2.3522),
        zoom: 13,
      ),
      markers: {
        Marker(
          markerId: MarkerId('paris'),
          position: LatLng(48.8566, 2.3522),
          infoWindow: InfoWindow(title: 'Paris'),
        ),
      },
    );
  }
}

Why Switch to MapMetrics?

• No usage fees — No per-load or per-request charges
• Custom styles — Full control over map appearance via the Portal
• Community data — Maps updated with community contributions
• No vendor lock-in — Open-source based solution
• Simple setup — No platform-specific API key configuration

Next Steps

• Flutter Setup Guide — Full setup walkthrough
• Basic Map — Get your first map running
• Custom Styling — Create custom map styles

---

Tip: The migration is mostly a find-and-replace operation. The biggest change is adding the styleUrl parameter and removing Google-specific API key configuration.