Integrating osmdroid into your Android app

The library osmdroid is a great replacement for your standard Google Maps. Now why’d you wanna go and replace Google Maps? Well, until recently Google didn’t support offline usage of their data. Most of the time this isn’t an issue, but if you want to take your (m)app abroad and avoid heavy roaming charges, you’re looking at offline maps. The good news is that osmdroid supports this. Even better is dat there’s a data type that can be used both by osmdroid and the iOS map-framework route-me: that format is called MBTiles. So if you’re building a cross-platform app, there are still some benefits in using the library over Google’s upcoming offline maps support. Also, one of the nice things about osmdroid is that it uses pretty much the same API as Google’s MapView, which, in theory, should make it a drop-in replacement. As with any library, however, there are always a few bumps in getting things to work. In the remainder of this post, I’ll detail the steps necessary for getting up and running in no time!

To source, or not to source …

Basically there are two ways of using the framework: you can choose to include the pre-built .jar which can be obtained from the downloads section) or you can choose to include the library from source.

Whichever route you choose, osmdroid depends on SLF4J (Simple Logging Facade for Java) which can be found here. As they state on their website: just add the file to the build path. The easiest way to accomplish this is by finding the “libs” directory in your Eclipse project (you are using Eclipse, right!?) and copying the file there. Refresh the directory contents and you should be good to go!

The same applies if you’re using the osmdroid jar: just copy it to the “libs” directory and refresh.

However, if you’re like me and like to be able to browse the sources while using the library, you’ll want to import osmdroid as a separate project and refer to it from your main project. Considering the fact that the documentation for this, otherwise excellent, library is quite terse, I highly recommend this option. This wiki page is the original source for how to install the sources under Eclipse, but you’ll probably find these steps a bit easier to follow:

Compiling osmdroid from source requires a few additional libraries. These are:

• android.jar (part of the Android SDK, we’ll get to this in a second)
• httpmime.jar (in debian this file is part of the package libhttpmime-java and located in /usr/share/java)
• slf4j-android-1.5.8.jar (you should have already downloaded this :-))

Ensure that you have found the above dependencies and proceed to download the sources via subversion:

http://osmdroid.googlecode.com/svn/trunk/ osmdroid

This will create a new directory osmdroid in your current directory. Switch to Eclipse and right-click in the package explorer and select “Import…” –> “Existing files into workspace”. Select the directory you just downloaded the sources to as “root directory” and make sure that you only tick the “osmdroid-android” project.

As you’ll probably have noticed, Eclipse has identified quite a number of unresolved dependencies. Let’s go fix that. First add the variable ANDROID_SDK_PLATFORM to your classpath by selecting:

Window --> preferences --> Java --> Build path --> Classpath variables

Once you’ve added a new variable, the result should look similar like the image below (the path should, obviously be changed to match your installation).

We’ve already taken the first step in resolving them, but there’s a few additional things to do. Right click the project in the package explorer and select

Build path --> Configure build path --> Libraries

Here add “httpmime.jar” and “slf4j-android-1.5.8.jar” via “Add External JARs” and “android.jar” via “Add Variable” (select ANDROID_SDK_PLATFORM which you defined earlier and click “Extend” to select the jar). Then finally add JUnit4 via the “Add library” button. The result should look similar to this:

If you’ve followed these steps, you should now be able to compile the library, but I suppose that doesn’t help you much. So go back to your Android project and right click it from the package explorer. Here too navigate to the “Java Build Path” but this time select the “Projects” tab. Here you can add osmdroid-android as a required project. Doing so will allow you to refer to the lib’s classes from your own code.

Still, if you don’t want your app to crash on load, there is one final click to be made: check the box in front of osmdroid-android in the “Order and Export” tab and you’re done!!