Home / GIS and Open Map Data for Beginners

How to Use OpenStreetMap in Flutter: flutter_map, Tiles, Markers, and Search

Person using both a smartphone and laptop, multitasking at a modern desk with office plants

Photo: cottonbro studio / Pexels

A Flutter app that needs a free, open map has one standard answer: flutter_map, a community maintained package that renders map tiles in a Flutter widget, with OpenStreetMap as its reference data source. It is not an official OSM product, and understanding that relationship is the key to using it well: flutter_map is the viewer, OSM supplies the tiles, and the tile usage policy is part of your app's obligations. This guide builds the map, adds the interactions every real app needs, and ends with the production scaling note that separates a demo from a shipped app. The data itself is introduced in openstreetmap osm; the web version of the same stack is how to use openstreetmap in website.

Interactive tool

flutter_map Setup: The Tile Policy Check

Check off each step as you finish it. Your progress stays on this page.

0 of 7 complete

0% done

The Minimal Map: Package, Widget, TileLayer

Add the package (flutter pub add flutter_map, plus latlong2 for its LatLng type) and the core of the app is one widget tree:

```

FlutterMap(

options: MapOptions(

initialCenter: LatLng(51.509364, -0.128928),

initialZoom: 9.2,

),

children: [

TileLayer(

urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',

userAgentPackageName: 'com.example.myapp',

),

],

)

```

TileLayer does the heavy lifting: it computes which tiles the viewport needs, fetches them over HTTP, and stitches them into the pannable, zoomable surface. The urlTemplate uses the standard slippy map placeholders, {z} for zoom and {x} and {y} for tile coordinates, the same scheme every OSM based viewer speaks. Everything else in flutter_map is layers added to that children list, which is the mental model to keep: a map is a stack of layers, tiles at the bottom, your data above.

userAgentPackageName: The Line That Is Not Optional

The userAgentPackageName parameter exists because of the OSM tile usage policy: the public tile servers are a donated community resource, and they require applications to identify themselves with a real, unique user agent rather than a library default, so abusive traffic can be told apart from a million honest apps. Set it to your app's actual package name. Skip it, or leave a placeholder, and a successful app can find its tile requests blocked, which presents as the worst kind of bug: a map that worked in development and grays out after launch. The same policy forbids bulk tile downloading for offline use from these servers; apps needing offline maps should use dedicated tile packages or a commercial host, a distinction the policy draws clearly and this guide repeats because tutorials so often omit it. Attribution to OpenStreetMap contributors, displayed in the app, is likewise a license condition, and flutter_map apps conventionally add a small attribution widget in a corner.

Markers, Lines, and Taps: Your Data on the Map

Real apps draw their own content over the tiles, and flutter_map models each kind as a layer. MarkerLayer takes Marker widgets anchored at LatLng points: build them with any Flutter widget, from the stock pin look to a custom photo avatar, each with its point, size, and alignment. PolylineLayer draws routes and tracks as connected points with width and color, the way to show a recorded path or a computed route. PolygonLayer and CircleLayer cover areas and radius displays. Interaction comes from MapOptions callbacks: onTap hands you the tapped LatLng, which is the whole mechanism behind "drop a pin where the user taps" and behind reading coordinates off a map in your own app, the same gesture our how to find coordinates on a map guide teaches in the abstract. A MapController lets your code move the map programmatically, fly to a search result, follow the user, rotate, and the current camera position is always readable for saving state.

Close-up of a person working on a smartphone while using a laptop at a wooden desk
Close-up of a person working on a smartphone while using a laptop at a wooden desk

Search and the User's Own Position

flutter_map deliberately ships no search and no location logic; both are services you add. For place search, call Nominatim over HTTP with the query and your app identified, parse the JSON results into LatLngs, and move the MapController to the chosen one; respect Nominatim's usage policy (one request per second, real identification, cache results) exactly as how to use openstreetmap in python details for the same service. For the user's position, pair flutter_map with a location plugin (geolocator or location), request permission through the plugin's flow, and draw the result as a marker or circle layer, recentering with the controller. Routing, turn by turn directions, is likewise an external service (OSRM or Valhalla are the open standards) whose returned geometry you draw as a polyline. Knowing what the package does not include is what keeps a flutter_map project plan honest: map yes, everything else is a service you choose.

Production: The Tile Server Warning

The demo stack points at tile.openstreetmap.org, and for development and modest apps that is sanctioned and fine. The policy line is scale and behavior: heavy, commercial, or runaway traffic must not lean on the donated servers. Production options, in ascending order of effort: a commercial tile host serving OSM data (several compete on price, and switching is one urlTemplate line plus an API key where required), self hosted tiles rendered or served from your own infrastructure using downloaded OSM extracts, or packaged offline tiles for bounded regions from a provider that licenses them for that use. All three keep flutter_map untouched, which is the architectural payoff of the layer model: the viewer never changes, only the tile supply matures. Plan the switch before launch if success would embarrass the demo setup, and cache tiles on device within the policy of whichever source you use, because a map that respects its data source is also, not coincidentally, a fast one. The offline question in the OSM ecosystem generally is covered by how to use openstreetmap offline.

Performance and Polish Notes From Real Builds

Three implementation details separate a flutter_map demo from an app that feels finished. Tile caching: flutter_map fetches tiles as needed and keeps a memory cache; for apps where users revisit the same areas, adding a cached tile provider package turns repeat views instant and cuts tile requests dramatically, which your tile source's policy will thank you for. Retina tiles: on high density phone screens the standard 256 pixel tiles can look soft; some tile hosts serve 512 pixel tiles (often requested with a @2x suffix in the URL template), and switching templates is the whole upgrade where the host supports it. Gestures and rotation: MapOptions exposes the interaction flags, so decide deliberately whether rotate and pinch are enabled; a delivery app wants a north up locked map, a hiking app wants rotation by compass, and leaving every gesture on by default is a decision too, usually the wrong one. None of these change the architecture from the earlier sections: layers over tiles, services beside the package, and the tile supply as the one part that must mature before scale.

Testing on Real Streets: The Pre Launch Walk

Before shipping, take the app outside, literally. Emulators report a location that is either perfect or a default in the middle of nowhere, and neither teaches you anything about the real stack: permission prompts on a fresh install, the first fix's delay while the phone finds satellites, tile loading over a moving cellular connection, and the map's behavior when the user walks into a tunnel of dead coverage mid route. Walk one known route with the app in hand and a checklist in the other: does the position marker track smoothly or teleport, do tiles keep up at your fastest zoom, does the app recover gracefully when the connection drops and returns, and does the attribution stay visible on every screen the map appears on. The failures this walk finds are the ones your first hundred users would have found for you, in reviews. It is also the moment to verify the production decision from the previous section with real numbers: watch the tile traffic one walk generates, multiply by your hoped for user count, and let that arithmetic, not optimism, decide when the tile host graduation happens.

Related Guides

This guide does not stand alone. The GIS and open map data guides below take up the questions it leads into:

Frequently Asked Questions

Is flutter_map an official OpenStreetMap package?

No. flutter_map is a community maintained Flutter package; OpenStreetMap is the data project whose tiles it displays by default. The distinction matters for obligations: the package is MIT style permissive open source, while the tiles carry the OSM tile usage policy and the data carries the ODbL attribution requirement.

Why does my flutter_map show gray tiles in production?

Most often the tile policy: requests without a real userAgentPackageName, or traffic heavy enough to be throttled, get refused by the public tile servers. Set userAgentPackageName to your app's package name, and if the app is genuinely popular, move the TileLayer URL to a tile host or your own server.

How do I add a marker at a location in flutter_map?

Add a MarkerLayer to the FlutterMap children with a Marker whose point is the LatLng, and whose child is any widget you like as the pin. For a pin where the user taps, capture the LatLng from the MapOptions onTap callback and rebuild the marker layer with that point.

Can a flutter_map app work offline?

Not from the public tile servers: the tile policy forbids bulk downloading tiles for offline use. Offline requires a different tile supply, packaged tile archives for your region from a provider that licenses them, or self hosted tiles, displayed through the same flutter_map layers.

How do I add search to a flutter_map app?

Call the Nominatim API over HTTP with the user's query and your app properly identified, show the results in a list, and on selection move the MapController to the result's coordinates and drop a marker. Respect the one request per second policy and cache results; for heavy search volume, use a hosted geocoder.

Photo credits: cottonbro studio (Pexels); RDNE Stock project (Pexels). Photos are served from this site; follow the credit to the library page for the original.