maimaps_flutter 0.1.0

Official Maimaps SDK for Flutter — place search, routing, reverse geocoding, point details, Loccode resolution, and a MapLibre-powered map widget.

maimaps_flutter

Official Maimaps SDK for Flutter — place search, routing, reverse geocoding, point details, Loccode resolution, and a MapLibre-powered map widget.

Install

dependencies:
  maimaps_flutter: ^0.1.0

Quickstart

import 'package:maimaps_flutter/maimaps_flutter.dart';

void main() {
  // Get an API key (mk_live_… / mk_test_…) from the Maiaddy Developers portal.
  Maimaps.initialize(MaimapsOptions(apiKey: 'mk_test_your_key'));
  runApp(const MyApp());
}

MaimapsEnvironment.staging (the default) uses baked-in staging hosts. Production hostnames are not finalized yet, so environment: production requires explicit apiBaseUrl and mapBaseUrl.

REST clients

final maimaps = Maimaps.instance;

// Search
final results = await maimaps.search.search(
  'garki market',
  latitude: 9.0579,
  longitude: 7.4951,
);

// Routing (A → B)
final route = await maimaps.routing.getRoute(
  origin: const LatLng(9.0579, 7.4951),
  destination: const LatLng(9.0765, 7.3986),
  mode: 'drive',
);
print('${route.distanceKm} km, ${route.durationMin} min');

// Routing with waypoints / Loccodes (POST)
final multi = await maimaps.routing.getRouteWithWaypoints(
  originLoccode: 'FC2F 3KN',
  destLat: 9.0765,
  destLng: 7.3986,
  waypoints: const [LatLng(9.06, 7.45)],
);

// Reverse geocode
final address = await maimaps.reverseGeocode.reverseGeocode(
  latitude: 9.0579,
  longitude: 7.4951,
);

// Point details (tapped-point resolution)
final details = await maimaps.pointDetails.getPointDetails(
  latitude: 9.0579,
  longitude: 7.4951,
  osmId: '12345678',
  osmType: 'w',
);

// Loccode
final loccode = await maimaps.loccode.resolve('FC2F 3KN');
final nearest = await maimaps.loccode.findNearest(
  latitude: 9.0579,
  longitude: 7.4951,
);

// Categories
final categories = await maimaps.placeCategories.listCategories();

Map widget

MaimapsMap renders the Maimaps published style on MapLibre GL. The style mode follows the ambient Theme brightness unless mode is set.

MaimapsMap(
  initialCenter: LatLng(9.0579, 7.4951),
  initialZoom: 14,
  mode: 'dark', // optional: 'light' | 'dark'
  onMapCreated: (controller) {
    // MapLibre MapController passthrough
  },
)

User location

myLocationEnabled: true shows the user-location puck (dot with accuracy circle and bearing indicator), requesting runtime location permission when needed; followUserLocation: true additionally makes the camera track the user, turning with the GPS course. Both can be toggled at runtime. If the user declines permission, the map renders without the puck. Android and iOS only — ignored on web.

MaimapsMap(
  myLocationEnabled: true,
  followUserLocation: true,
)

The app must declare the platform permission itself:

• Android — in android/app/src/main/AndroidManifest.xml: <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
• iOS — in ios/Runner/Info.plist: NSLocationWhenInUseUsageDescription with a usage string.

Error handling

All SDK errors derive from MaimapsException:

Exception	When
InvalidApiKeyException	401 invalid_api_key
RateLimitException	429 rate_limited — exposes retryAfter
QuotaExceededException	429 quota_exceeded
MaimapsServerException	5xx (incl. 503 auth_unavailable) and other API errors
MaimapsNetworkException	timeouts, connection failures, cancellation

try {
  await maimaps.search.search('lagos');
} on RateLimitException catch (e) {
  await Future.delayed(e.retryAfter ?? const Duration(seconds: 1));
} on InvalidApiKeyException {
  // re-check the key in the Developers portal
}