Navvo
Guides

Flutter SDK

Install and use the official navvo_maps_flutter package — an embeddable NavvoMap widget plus a pure-Dart NavvoServices client for search, geocoding, places, routing, traffic and more.

Flutter SDK

The official navvo_maps_flutter package gives you two things:

  • NavvoMap — an embeddable, interactive Navvo basemap widget (camera, markers, style switching, GeoJSON layers), pointed at Navvo's GET /tiles/style entry point.
  • NavvoServices — a pure-Dart, map-free client for the Navvo Web Service (search, geocode, places, routing, traffic, matrix, isochrone, weather, EV, transit…). Because it has no Flutter UI dependency, it also runs in isolates, background tasks, and server-side Dart.

Everything is Navvo-branded and only ever calls https://navvo.io/api/v1. Coordinates are uniformly LatLng(lat, lng) across the whole API — the SDK converts to whatever each endpoint expects internally.

Requires: Flutter ≥ 3.19 (Dart ≥ 3.3) · Android 5.0+ (minSdk 21) · iOS 13+ · Base URL: https://navvo.io/api/v1

Install

flutter pub add navvo_maps_flutter
pubspec.yaml
dependencies:
  navvo_maps_flutter: ^0.1.0

Initialize

Set your API key once at startup — both the map and the services read it:

import 'package:navvo_maps_flutter/navvo_maps_flutter.dart';

void main() {
  NavvoMaps.initialize(apiKey: 'nvvo_YOUR_KEY');
  runApp(const MyApp());
}
Provide your API key. Without a key the basemap renders with a "Navvo Map Developer (Provide Your API Key)" watermark on every tile. Set apiKey in NavvoMaps.initialize for a clean map. Basemap attribution is © Navvo.

Display a map

NavvoMap(
  initialCameraPosition: const CameraPosition(
    target: LatLng(31.9539, 35.9106), // Amman
    zoom: 12,
  ),
  style: NavvoMapStyle.standard, // standard · light · dark · satellite · terrain · threeD
  markers: {
    NavvoMarker(markerId: const MarkerId('a'), position: const LatLng(31.9539, 35.9106)),
  },
  onMapCreated: (controller) => _controller = controller,
  onTap: (LatLng pos) => debugPrint('tapped $pos'),
);

The NavvoMapController from onMapCreated drives the map imperatively:

await _controller.animateCamera(CameraUpdate.newLatLngZoom(const LatLng(31.95, 35.91), 15));
await _controller.setStyle(NavvoMapStyle.dark);

Use the services (no map required)

final svc = NavvoServices.instance; // uses the key from NavvoMaps.initialize

// Search (natural language + autocomplete)
final result = await svc.search('coffee in Abdoun', near: const LatLng(31.95, 35.91), limit: 8);
for (final p in result.places) {
  print('${p.name} @ ${p.location}');
}

// Geocode
final hits = await svc.geocode('Rainbow Street, Amman');

// Directions — returns the routing trip (geometry + maneuvers + summary)
final plan = await svc.plan(const RoutePlanRequest(
  locations: [
    PlanStop(LatLng(31.95, 35.91), name: 'Start'),
    PlanStop(LatLng(31.99, 35.95), name: 'End'),
  ],
  costing: RouteCosting.auto,
));
print('${plan.distanceKm} km · ${plan.durationMin} min');

Need a different key, or a client inside an isolate? Construct one explicitly:

final svc = NavvoServices(apiKey: 'nvvo_...', baseUrl: 'https://navvo.io/api/v1');

Errors

Every call throws a typed subclass of NavvoException:

ExceptionHTTPMeaning
NavvoAuthError401missing / unknown key
NavvoScopeError403revoked key, missing scope, or quota exceeded
NavvoNotFoundError404resource not found
NavvoValidationError400 / 422bad request
NavvoRateLimitError429quota — honours Retry-After
NavvoServerError5xxupstream error
NavvoTimeoutError / NavvoNetworkError—transport

place() is a soft-null getter — it returns null (rather than throwing) when a slug doesn't exist:

final PlaceDetails? place = await svc.place('some-slug'); // null if not found

Platform setup

  • Android — minSdkVersion 21; add the INTERNET permission (and location permissions only if you enable the location puck).
  • iOS — platform :ios, '13.0' in the Podfile; add NSLocationWhenInUseUsageDescription only if you use the location puck.
  • Web — a WebGL2-capable browser.
The NavvoMap widget renders via an embedded open-source map engine under the hood — you only ever interact with Navvo classes and Navvo endpoints. To render a map on the web without Flutter, use the Navvo Maps JS SDK.

Java SDK

Install and use the official io.navvo:navvo-java client for server-side geocoding, routing, places, traffic, EV, transit, and more.

Android SDK

Install and use io.navvo:maps-android — a NavvoMapView for Kotlin apps plus a full NavvoServices client for search, geocoding, places, routing, traffic and more.

Copyright © 2026