Introducing the Geocoder Library for Android

Following the announcement earlier this week of a new directions library, today we are introducing a geocoder library for Android.

This library lets you convert location text into geographic coordinates, as well as lat/lon coordinates into a meaningful place name (reverse geocoding). It’s also a full drop-in replacement for the default Android Geocoder, and it helps you build an autocomplete widget for places and addresses like this one:

Installation

Like the Mapbox SDK and our directions library, the geocoder library is available to your app via Maven Central. Copy and paste these lines into your build.gradle file to enable the library in your project:

repositories {
    mavenCentral()
}

dependencies {
    compile ('com.mapbox.mapboxsdk:mapbox-android-geocoder:1.0.0@aar'){
        transitive=true
    }
}

Usage

Once you have installed the library, the MapboxGeocoder object is at your disposal to do forward and reverse geocoding. For example, to get the coordinates of The White House you could do the following:

MapboxGeocoder client = new MapboxGeocoder.Builder()
    .setAccessToken(MAPBOX_ACCESS_TOKEN)
    .setLocation("The White House")
    .build();

You can get place names near a specific location in a very similar way. In the following example we’re restricting the results to places of interest only, but you can also filter by country, region, postcode, place, neighborhood, and address:

MapboxGeocoder client = new MapboxGeocoder.Builder()
    .setAccessToken(MAPBOX_ACCESS_TOKEN)
    .setCoordinates(longitude, latitude)
    .setType(GeocoderCriteria.TYPE_POI)
    .build();

Android Geocoder drop-in replacement

If your app is currently using the standard Android Geocoder, you can switch to Mapbox swapping android.location.Geocoder with com.mapbox.geocoder.android.AndroidGeocoder. You only need to remember to set your access token.

For example, the reference sample for the Android Geocoder han an IntentService that does the following:

import android.location.Geocoder;

...

Geocoder geocoder = new Geocoder(context, Locale.getDefault());
addresses = geocoder.getFromLocation(
    location.getLatitude(),
    location.getLongitude(),
    1);

The equivalent code, using Mapbox’s implementation is:

import com.mapbox.geocoder.android.AndroidGeocoder;

...

AndroidGeocoder geocoder = new AndroidGeocoder(context, Locale.getDefault());
geocoder.setAccessToken(MAPBOX_ACCESS_TOKEN);
addresses = geocoder.getFromLocation(
    location.getLatitude(),
    location.getLongitude(),
    1);

Autocomplete widget

If you want to implement an autocomplete widget like the one pictured above, check the code in the Geocoder Samples folder. The MainActivity shows how to implement a GeocoderAdapter that you could pass to a standard Android AutoCompleteTextView to create a geocoder autocomplete widget.

On iOS, too

We also have a Mapbox Geocoder library developed in Swift. Import MapboxGeocoder.framework into your project, then use MBGeocoder as a drop-in replacement for Apple’s CLGeocoder. This library includes example applications written in both Swift and Objective-C.

Open Source

For full code access and more information on how to use this library visit our repository on GitHub.

Happy hacking.