Getting Started with mobile map rendering on Android

This article describes how to use mapsforge-map rendering on your Android device.

If you have any questions or problems, don't hesitate to ask our public mapsforge-dev mailing list for help. You can also report bugs and improvement requests via our issue tracker.

Download the free map application

The easiest way to try out or map rendering is to install the free "AdvancedMapViewer" application, which runs on all Android devices with version 1.6 or higher. The APK file can be found in our download section together with a few binary map files for different regions in the world. You need at least one map file on your Android device to use the application in offline rendering mode. The demo application has an integrated file picker to select and change the map file, therefore map files can be stored in any folder.

The AdvancedMapViewer also comes with an integrated tile download mode, in which all map pictures will be downloaded from the OpenStreetMap server at runtime. Of course, an active Internet connection is needed for this. You can change between offline rendering mode and tile download mode at any time via the integrated preferences menu.

Developers can browse our repository at /trunk/Applications/Android/AdvancedMapViewer to check out the latest version of the program. Like everything else in the mapsforge project, the program is distributed under the LGPL3 license.

Use the map library in your application

The following HelloMapView example demonstrates, how to write a simple map application for Android. It only requires the mapsforge-map library, which is distributed under the GPL3 license and can be downloaded in our download section. When executed, the program will render a map on the display, that can be moved and zoomed via touchscreen, zoom buttons and multi-touch gestures.

import android.os.Bundle;
import java.io.File;
import org.mapsforge.android.maps.MapActivity;
import org.mapsforge.android.maps.MapView;

public class HelloMapView extends MapActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        MapView mapView = new MapView(this);
        mapView.setClickable(true);
        mapView.setBuiltInZoomControls(true);
        mapView.setMapFile(new File("/sdcard/path/to/mapfile.map"));
        setContentView(mapView);
    }
}

For those developers, who have already worked with the Google APIs Add-On, here are the differences to Google's Hello MapView example:

1. The import paths change from com.google.android.maps to org.mapsforge.android.maps.
2. No "<uses-library ..." reference is required in the AndroidManifest.xml file.
3. As no registration is needed for the mapsforge-map library, the MapView doesn't have a parameter for an API key.
4. No abstract isRouteDisplayed method needs to be overridden.
5. If the MapView should operate in offline rendering mode, it needs a local file that contains the map data. Therefore the setMapFile(File) method is called, that tells the MapView to read all map data from the specified file.

If you want to use the MapView in offline rendering mode like in the example above, the internet permission is not needed. The map library requires only one permission for writing cached images to the external storage (typically the phones SD card). Add the following line to your applications AndroidManifest.xml file:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

If the minSdkVersion attribute of your project is set to 3 (which refers to Android 1.5), the Android system will automatically scale up the window of the application on devices with a higher pixel resolution. To fix this issue, either set the minSdkVersion to a higher value or add an android:targetSdkVersion attribute with a value of 4 or higher. More information about these attributes can be found in the official documentation.

The mapsforge-map library has a simple but powerful API, which aims to be compatible with the Google APIs Add-On. You can find the link to the latest Javadoc reference at the homepage of our project. New features will be added in the future, the performance will be improved and bugs will be eliminated, so be sure to always use the latest version of the library.

Sample applications for developers

To provide developers with various code examples, we have created an Eclipse project which contains several example programs. Each example shows a certain feature or special use case with only a few lines of code, which should be easy to understand.

You can check out the latest version of this demo project from our repository at /trunk/Applications/Android/Samples. As new features are being implemented in the mapsforge-map library, more example applications will be added to this project in the future. Like everything else in the mapsforge project, these programs are distributed under the LGPL3 license.