Readme

flutter_map_cache

A slim yet powerful caching plugin for flutter_map tile layers.

Pub Version likes Pub Points Pub Downloads

GitHub last commit stars GitHub issues codecov

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.

flutter_map introduced a caching mechanism in version 8.2.0 that solves these topics. This package is for users that need advanced use cases that are not covered by the default caching mechanism of flutter_map and legacy support for flutter_map versions < 8.2.0.

Features

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

Supported storage backends are:

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

Getting started

1. 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: ^8.1.1 # in case you don't have it yet 
  flutter_map_cache: ^2.0.0 # this package
  path_provider: ^2.1.2 # in case the storage backend requires a path

  # drift
  http_cache_drift_store: ^7.0.0
  sqlite3_flutter_libs: ^0.5.15

  # file system
  http_cache_file_store: ^2.0.0

  # hive
  http_cache_hive_store: ^5.0.0

  # objectbox
  http_cache_objectbox_store: ^2.0.0
  objectbox_flutter_libs: ^1.4.1

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

  # sembast
  http_cache_sembast_store: ^1.0.0
  sembast: ^3.8.4+1
  sembast_web: ^2.4.1

2. ⚠️ 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

1. 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;
}

2. 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)

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

import 'dart:io';

import 'package:dio_cache_interceptor/dio_cache_interceptor.dart';
import 'package:http_cache_file_store/http_cache_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?

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?

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

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?

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?

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.