flutter_map_cache

A slim yet powerful caching plugin for flutter_map tile layers.

Motivation

Many tile providers require users in their tile usage policy to cache tile requests. This decreases the load on those servers and is important especially if they are donation based like the OpenStreetMap.
Commercial tile providers normally charge per tile request. By caching tiles you can reduce the amount of tile requests and lower your costs.
Caching map tiles provides a better user experience since the region the user visited loads nearby instantly. Most of the time a user visits the same regions often, e.g. because it is the region he lives in.
Especially raster tiles that are used by default on flutter_map, the data consumption can be high quite fast. Caching tiles lowers the amount of used mobile data and bandwidth.

Features

The package uses dio with the dio_cache_interceptor package and supports the storage backend that you like.

Supported storage backends are:

Storage backend	Description
In-Memory	- For testing purposes - `flutter_map` has memory caching itself
File System	- Easy to setup, no additional storage backend package required - potentially slower than using a database
Drift	- SQLite database - good platform support
Hive	- key-value database - easy to integrate
ObjectBox	- NoSQL, ACID compliant - Fast library - More complex integration
Isar	- NoSQL - Fast library - More complex integration

Other storage backends will be supported as soon as the underlying package dio_cache_interceptor supports them.

Getting started

Add the packages you want to use to your pubspec.yaml file. Only add the packages for the backend you want to use.

dependencies:
  flutter_map: ^6.0.0 # in case you don't have it yet 
  flutter_map_cache: ^1.3.0 # this package
  path_provider: ^2.1.2 # in case the storage backend requires a path

  # drift
  dio_cache_interceptor_db_store: ^5.1.0
  sqlite3_flutter_libs: ^0.5.15

  # file system
  dio_cache_interceptor_file_store: ^1.2.2

  # hive
  dio_cache_interceptor_hive_store: ^3.2.1

  # objectbox
  dio_cache_interceptor_objectbox_store: ^1.1.3
  objectbox_flutter_libs: ^1.4.1

  # isar
  isar: ^3.1.0+1
  isar_flutter_libs: ^3.1.0+1

⚠️ Some storage backends have their own required setups. Please check them out in their package documentations.

Usage

Using the cache is easy. Here are examples how to use some of the storage backends:

Hive

Click here to expand / hide.

First get the cache directory of the app (i.e. with the path_provider package).

import 'package:path_provider/path_provider.dart';

Future<String> getPath() async {
  final cacheDirectory = await getTemporaryDirectory();
  return cacheDirectory.path;
}

Then use the directory path to initialize the HiveCacheStore. You can wrap FlutterMap inside a FutureBuilder to use the getPath() method.

@override
Widget build(BuildContext context) {
  return FlutterMap(
    options: MapOptions(),
    children: [
      TileLayer(
        urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
        tileProvider: CachedTileProvider(
          // maxStale keeps the tile cached for the given Duration and 
          // tries to revalidate the next time it gets requested
          maxStale: const Duration(days: 30),
          store: HiveCacheStore(
            path,
            hiveBoxName: 'HiveCacheStore',
          ),
        ),
      ),
    ],
  );
}

In Memory (for testing)

Click here to expand / hide.

import 'package:dio_cache_interceptor/dio_cache_interceptor.dart';
import 'package:flutter/widgets.dart';
import 'package:flutter_map/flutter_map.dart';
import 'package:flutter_map_cache/flutter_map_cache.dart';

class MyMap extends StatelessWidget {
  MyMap({super.key});

  // create the cache store as a field variable
  final _cacheStore = MemCacheStore();

  @override
  Widget build(BuildContext context) {
    return FlutterMap(
      options: MapOptions(),
      children: [
        TileLayer(
          urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
          tileProvider: CachedTileProvider(
            // use the store for your CachedTileProvider instance
            store: _cacheStore,
          ),
        ),
      ],
    );
  }
}

File System

Click here to expand / hide.

import 'dart:io';

import 'package:dio_cache_interceptor/dio_cache_interceptor.dart';
import 'package:dio_cache_interceptor_file_store/dio_cache_interceptor_file_store.dart';
import 'package:flutter/material.dart';
import 'package:flutter_map/flutter_map.dart';
import 'package:flutter_map_cache/flutter_map_cache.dart';
import 'package:path_provider/path_provider.dart';

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

  @override
  State<MyMap> createState() => _MyMapState();
}

class _MyMapState extends State<MyMap> {
  // create the cache store as a field variable
  final Future<CacheStore> _cacheStoreFuture = _getCacheStore();

  /// Get the CacheStore as a Future. This method needs to be static so that it
  /// can be used to initialize a field variable.
  static Future<CacheStore> _getCacheStore() async {
    final dir = await getTemporaryDirectory();
    // Note, that Platform.pathSeparator from dart:io does not work on web,
    // import it from dart:html instead.
    return FileCacheStore('${dir.path}${Platform.pathSeparator}MapTiles');
  }

  @override
  Widget build(BuildContext context) {
    // show a loading screen when _cacheStore hasn't been set yet
    return FutureBuilder<CacheStore>(
      future: _cacheStoreFuture,
      builder: (context, snapshot) {
        if (snapshot.hasData) {
          final cacheStore = snapshot.data!;
          return FlutterMap(
            options: MapOptions(),
            children: [
              TileLayer(
                urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
                tileProvider: CachedTileProvider(
                  // use the store for your CachedTileProvider instance
                  store: cacheStore,
                ),
              ),
            ],
          );
        }
        if (snapshot.hasError) {
          return Center(child: Text(snapshot.error.toString()));
        }
        return const Center(child: CircularProgressIndicator());
      },
    );
  }
}

More examples

You can find additional example implementations for other storage backends in the example app on GitHub.

Common use cases & frequent questions

How about web?

Click here to expand / hide.

This package supports the web as long as you use a storage backend that supports web.

In Memory works out of the box
Hive uses for its web support IndexedDB under the hood to support web.
Drift (SqLite) requires additional setup steps for web

Does this package support cancellation of tile requests?

Click here to expand / hide.

Yes. This package includes the tile cancellation out of the box. There is no need for flutter_map_cancellable_tile_provider when using this package.

Remove the api key from the url before it gets used for caching

Click here to expand / hide.

Commercial tile providers often use an api key that is attached as a parameter to the url. While this shouldn't be a problem when the api key stays the same you might want to make it immune to api key changes anyway.

final _uuid = Uuid();

CachedTileProvider(
  keyBuilder: (request) {
    return _uuid.v5(
      Uuid.NAMESPACE_URL,
      request.uri.replace(queryParameters: {}).toString(),
    );
  },
),

Can I use this package for an offline map?

Click here to expand / hide.

This package does not provide support to download tiles automatically. Only tiles that were previously visited with an active internet connection show up on the map.

If you need to have the map completely offline, I recommend to check out the file formats MBTiles or PMTiles.

What if I want to use sqflite?

Click here to expand / hide.

Because dio_cache_interceptor already supports Drift as a SQLite solution it's unlikely that sqflite will be supported any day soon.

If you still are required to use only sqflite, I recommend to create your own tile provider by using the cached_network_image package.

Additional information

Pull requests are welcome. If you want to add support for another storage backend you can check out dio_cache_interceptor.

If you need help you can open an issue or join the flutter_map discord server.

flutter_map_cache

Motivation

Features

Getting started

Usage

Hive

In Memory (for testing)

File System

More examples

Common use cases & frequent questions

How about web?

Does this package support cancellation of tile requests?

Remove the api key from the url before it gets used for caching

Can I use this package for an offline map?

What if I want to use sqflite?

Additional information

Libraries

flutter_map_cache package