flutter_map Docs
Project Links💝 Support Us
v8
v8
  • flutter_map
  • Why & How
    • 🌟Showcase & Case Studies
    • ❔How Does It Work?
      • Raster vs Vector Tiles
    • 👀Demo & Examples
  • Getting Started
    • 🚀What's New In v8?
    • Installation
  • Usage
    • Base Widget
      • Unbounded Horizontal Scrolling
    • Options
      • Interaction Options
      • Custom CRSs
    • Layers
    • Programmatic Interaction
      • Controllers & Cameras
      • External Custom Controllers
      • Listen To Events
    • Full API Reference
  • Layers
    • Tile Layer
      • Tile Providers
      • Built-In Caching
    • Marker Layer
    • Polygon Layer
    • Polyline Layer
    • Circle Layer
    • Overlay Image Layer
    • Attribution Layer
    • Layer Interactivity
      • Hit Testing Behaviour
  • Tile Servers
    • Using OpenStreetMap (direct)
    • Using Mapbox
    • Using Google Maps
    • Using Tracestrack
    • Using Thunderforest
    • Using Stadia Maps
    • Using Lima Labs
    • Using Bing Maps
    • Offline Mapping
    • Other Options
  • Plugins
    • Plugins List
    • Creating Plugins
      • Tile Providers
      • Layers
      • Caching Providers
  • Thanks
    • 💝Supporters
    • ✏️Credits & Contributing
Powered by GitBook

© flutter_map Authors & Maintainers

On this page
  • What is flutter_map doing?
  • Why is flutter_map doing this?
  • What should I do?
  • I have more questions

Was this helpful?

Edit on GitHub
Export as PDF
  1. Tile Servers

Using OpenStreetMap (direct)

PreviousHit Testing BehaviourNextUsing Mapbox

Last updated 22 days ago

Was this helpful?

This does not apply to users using OpenStreetMap data through other tile servers, only to users using the public OpenStreetMap tile servers directly.

flutter_map wants to help keep map data available for everyone. One of the largest sources of this data is OpenStreetMap. OpenStreetMap data powers the majority of non-proprietary maps - from actual map tiles/images to navigation data - in existence today. The data itself is free for everyone under the .

The OpenStreetMap Foundation run OpenStreetMap as a not-for-profit. They also provide a public tile server at , which is run on donations and volunteering time. This server is used throughout this documentation for code examples, and in our demo app.

The OpenStreetMap public tile server is NOT free to use by everyone

flutter_map can be setup to conform to these requirements - but it may not conform by default.

The OpenStreetMap public tile server is without cost (for users), but, "without cost" ≠ "without restriction" ≠ "open".

What is flutter_map doing?

From v8.2.0 onwards, warnings will appear in console when a TileLayer is loaded using one of the OpenStreetMap tile servers.

Additionally from v8.2.0, flutter_map will provide automatically enabled Built-In Caching. This aims to reduce the number of tile requests.

We will continue to monitor the strain that flutter_map places on the OSM servers. If these measures do not reduce the request rates, we may impose stricter policies - such as blocking all OSM tiles in release mode builds by default.

We will also continue to look into other ways to improve compliance automatically.

Why is flutter_map doing this?

The OpenStreetMap tile server is NOT free to use by everyone.

The top 10 user-agents are shown below, in order.

User-Agent
Tiles/second

Mozilla/5.0 QGIS/*

1958.78

flutter_map (*) This represents the of FM users on non-web platforms. * represents the TileLayer.userAgentPackageName.

1414.97413

Mozilla/5.0 ...

375.2936227

Mozilla/5.0 ...

302.7196412

Dart/* (dart:io) This represents FM users on older versions & other Flutter mapping libraries not using FM.

209.9140856

Mozilla/5.0 ...

203.3502431

Mozilla/5.0 ...

175.8431366

Mozilla/5.0 ...

162.7784028

Mozilla/5.0 ...

126.3630556

com.facebook.katana

99.72585648

We are extremely proud to see flutter_map being used so much! At the same time, we are aware that there are many users placing a potential strain on OpenStreetMap, which we want to minimize:

  • We do not want to discourage legitimate use-cases from using the OpenStreetMap tile servers

  • We want to help users who may be accidentally or unknowingly breaking the OpenStreetMap usage policies adjust their project so they can continue to benefit from cost-free tiles

  • However, we do wish to discourage illegitimate use-cases or users who are intentionally breaking the OpenStreetMap usage policies

Therefore, we are introducing measures to force users to read the OpenStreetMap Tile Usage Policy before allowing them to use the servers in release builds:

  • This is easy for legitimate users who have already read the policy and follow it

  • It helps users accidentally breaking the policies to see why it's so important to follow them, and what they can do to fix any issues

  • It adds friction for users intentionally breaking the policies

Ultimately however, it is your own responsibility to comply with any appropriate restrictions and requirements set by your chosen tile server/provider. Always read their Terms of Service. Failure to do so may lead to any punishment, at the tile server's discretion.

This policy is completely unrelated to the OpenStreetMap Foundation, and was the sole collective decision of the maintainers.

What should I do?

1

Consider switching tile servers

Our docs list multiple alternatives, many of which have free tiers suitable for hobbyists, affordable pricing for commercial usage, and one which is extremely flexible.

Most of these are built off the same data, so the actual information contained within the map won't change (although a change in style may not show some data).

If you're a commercial user and want the best balance of flexibility and affordability, consider setting up your own private tile server! In any case, the OpenStreetMap tile server doesn't offer uptime guarantees, which may be important to your business.

2

Read the OpenStreetMap Tile Usage Policy

If you still want to use OpenStreetMap, you must read the policy and comply with its restrictions and requirements. It also contains some background info as to why this is important.

To note:

Should any users or patterns of usage nevertheless cause problems to the service, access may still be blocked without prior notice.

If your project uses a very large number of tiles, even if it would otherwise meet the requirements, consider switching to a different server.

Also note all the other requirements, which may require you to make adjustments to your project...

3

Make all necessary adjustments

Check the OSM policy for all the adjustments you might need to make. Here's some common ones:

  • Enable conforming caching

    v8.2.0 introduces automatically-enabled Built-In Caching! This is designed to meet the caching requirements of the usage policy. Check the link for more info.

  • Add sufficient attribution

    The RichAttributionWidget or SimpleAttributionWidget can both be used to setup attribution which looks great, is unintrusive, and is conforming - provided you add the necessary sources. See Attribution Layer for more info and a simple code snippet you can add to meet the attribution requirement.

    You can also add attribution in any other way that meets the requirements.

  • Set a more specific user-agent to identify your client

4

Disable the console warnings

If you're eligible to use the servers, you can re-enable them in release mode and disable the console warnings in debug mode.

To do this, set the flutter.flutter_map.unblockOSM environment variable when building/running/compiling. Use the dart-define flag to do this.

To evidence that you've read and understood the tile policy, you should set it to the exact string (excluding any leading or trailing whitespace, including all other punctuation) following the phrase from the policy:

OpenStreetMap data is free for everyone to use. _____

For example, to run the project:

flutter run --dart-define=flutter.flutter_map.unblockOSM="_____"

You can also add this to your IDE's configuration to automatically pass this argument when running from your IDE.

I have more questions

If you've got a question or comment regarding this new policy, or if you think we've missed something, please reach out to us.

The best way to do this is on the dedicated GitHub issue, or on the Discord server.

on 2025/04/08 shows flutter_map as the second largest 'whole' user-agent in terms of the average number of tile requests made per second over the day. Whilst it is true that there are multiple user agents smaller who make up an overall much larger portion of total usage - for example, leaflet.js's usage is split across the browsers' user-agents, as is flutter_map usage on the web - the usage of flutter_map cannot be ignored.

There's also other options to implement to meet the requirements, and go beyond the capabilities of the built-in caching.

flutter_map provides its own user-agent on native platforms, but this isn't enough to meet the requirements. You should set TileLayer.userAgentPackageName: see the for the TileLayer.

Data collected by OSM
ODbL
https://tile.openstreetmap.org
Tile Usage Policy
OpenStreetMap public tile server usage policy
Tile Usage Policy
OpenStreetMap public tile server usage policy
Caching
Recommended Setup
Logo
Logo