Using MBTiles on Android with OSMDroid

26 July 2012 by Jonathan Baker

Originally designed and implemented by MapBox, the MBTiles file format is increasingly becoming the standard for creating compact, portable packages of map tile imagery. Under the hood, MBTile files are simply SQLite database files that conform to a predefined schema and specification. These files can then be used as a datasource for generating an interactive map. Our flagship data collection product fulcrum allows users to upload MBTiles files to their account for future offline viewing on their mobile device. This can be handy in situations where the user may not have a reliable Internet connection while collecting records. On iOS, we currently use the open source route-me framework for displaying MBTiles in a native map view. It is no secret that we have been working on an Android version of fulcrum (if it was, it isn’t now) for a few months now. As such, we had to find a similar framework for Android that would allow us to have the same functionality.

Enter OSMDroid

A quick Google search for MBTiles, Android, and OSM doesn’t return much. Finally, we found a library called OSMDroid that called itself a drop in replacement for the official Google Map library. At first glance, it didn’t look very promising. Documentation was nonexistent, example code hadn’t been touched in years. However, it did seem to somewhat follow the same design patterns as its Google cousin. With a little love and reading using the actual source code as documentation, we managed to make it work. Below is a quick and dirty walkthrough of adding OSMDroid to your Android application.


Adding OSMDroid to Your Android Project

The OSMDroid project is hosted on Google Code here. From the downloads tab, download the latest _osmdroid-android-x.x.x.jar_ file. Open your android project in Eclipse and drag the downloaded JAR to the _libs_ directory, making sure to copy the file, not link it. Then, right click on the JAR in Eclipse and select _Add to Build Path_.

Using the Library

Your primary resource in the OSMDroid library is the _MapView_ class. This is the view that renders and shows tiles from a given tile source. Generally your instance of the MapView will also be the content view of your Activity. If all you want to do is show MapQuest OSM tiles, the following code will work.

However, if you want to use an MBTiles file, things get a little more convoluted. 

As you can see, there is a lot of boilerplate setup just to open an MBTiles file. It is definitely not streamlined or intuitive. There are also a few gotchas about the above code:

  1. The tile size, minimum and maximum zoom levels, and file name are hardcoded.
  2. In order to switch to another MBTiles file, you have to tear down and re-create the entire MapView object as the constructor appears to be the only place you can specify the MapTileProviderArray.

Unfortunately we have yet to find a better option in terms of a framework for Android. MapBox recently released an iOS SDK for this very purpose and here’s hoping that they do the same for Android. If they don’t, then perhaps we will.

Jonathan Baker

About the author

Jonathan is a mobile software developer, and works with our Android and iOS applications.