Flutter — Getting Started

This walks through everything needed to render a MapMetrics Atlas map in a Flutter app, from the pubspec entry to a runnable main.dart.

Coordinate order

mapmetrics takes coordinates as Position(longitude, latitude) — longitude first, GeoJSON order. This is the opposite order from the LatLng(latitude, longitude) pattern used by google_maps_flutter and older MapMetrics docs. See MapOptions reference for the full warning.

1. Add the dependency

dependencies:
  mapmetrics: ^1.0.6

flutter pub get

The package re-exports package:geotypes/geotypes.dart (for Position), so you don't need to add geotypes yourself.

2. Platform setup

Android

mapmetrics's own android/build.gradle sets minSdk = 21 — your app module needs at least that:

// android/app/build.gradle
android {
    defaultConfig {
        minSdk = 21
    }
}

If you plan to use user location (MapController.enableLocation()/trackLocation()/PermissionManager), declare the location permissions in android/app/src/main/AndroidManifest.xml — this is what the SDK's own example app declares:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

No other manifest entries are required for the base map.

iOS

The package's CocoaPods spec (ios/mapmetrics.podspec) pins s.platform = :ios, '12.0' — set your deployment target to iOS 12.0 or higher (check ios/Podfile and the Xcode project's IPHONEOS_DEPLOYMENT_TARGET; the example app's Podfile has no override, so it inherits Flutter's default, which must be >= 12.0 for this package to build).

If you plan to use user location, add the usage-description keys to ios/Runner/Info.plist — again, straight from the SDK's own example app:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs your location to display your location on the map.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app requires access to your location.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app requires access to your location.</string>

Skip these three keys if your app never calls enableLocation()/trackLocation() — iOS will reject the build-time permission prompt wiring if the keys are missing but the location APIs are called at runtime, so only add what you use.

Could not verify

The exact minimum Xcode/Swift toolchain version isn't pinned anywhere in the repo beyond the podspec's s.swift_version = '5.0' and MapLibre iOS dependency ~> 6.11. If you hit a build error referencing Swift language version, check ios/mapmetrics.podspec in the installed package for the current constraint.

3. Get a style URL and API key

Create a style and an API key in the MapMetrics portal, then build a style URL of this shape:

https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY

Both the fileName and token query parameters are required — the gateway will reject a bare ?token= URL without a fileName.

4. A full runnable main.dart

import 'package:flutter/material.dart';
import 'package:mapmetrics/mapmetrics.dart';

const String _styleUrl =
    'https://gateway.mapmetrics-atlas.net/styles/?fileName=YOUR_STYLE_ID/YOUR_STYLE.json&token=YOUR_API_KEY';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'MapMetrics Demo',
      theme: ThemeData(colorSchemeSeed: Colors.blue),
      home: const MapPage(),
    );
  }
}

class MapPage extends StatefulWidget {
  const MapPage({super.key});

  @override
  State<MapPage> createState() => _MapPageState();
}

class _MapPageState extends State<MapPage> {
  MapController? _controller;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('MapMetrics')),
      body: MapMetricsView(
        options: MapOptions(
          initStyle: _styleUrl,
          // Position(longitude, latitude) — Amsterdam is lng 4.8952, lat 52.3702.
          initCenter: Position(4.8952, 52.3702),
          initZoom: 12,
        ),
        onMapCreated: (controller) {
          _controller = controller;
        },
        onStyleLoaded: (style) {
          // The style has finished loading; safe to add sources/layers here.
        },
      ),
    );
  }
}

Run it with flutter run.

Next steps

• MapOptions reference — every constructor field, defaults, and the coordinate-order trap
• MapController reference — camera control, projection, feature querying, style switching
• Location & Permissions — showing and tracking the user's own position
• Offline maps — downloading a region for offline use