Android SDK

The what3words Android SDK gives you programmatic access to what3words technology in your own Android app. The Android SDK allows the conversion of 3 word addresses to coordinates (forward geocoding), the conversion of coordinates to 3 word addresses (reverse geocoding) and to obtain suggestions based on a full or partial 3 word address (AutoSuggest).

SDK Version

This page describes version 2 of the what3words Android SDK; this is the latest version.

Get Started

To get a feel for geocoding with what3words, we recommend that you start with our RESTful API; this has all the main functional elements of our offline capable Android SDK and you can be up and running in minutes. When you're ready to integrate what3words offline into your own Android app, just get in touch with us at support@what3words.com and we'll get the ball rolling for you.

Supported Java Versions

The what3words Android SDK supports Java 7 and above. To develop applications using the Android SDK, you will need a Java 7 or higher Java Development Kit (JDK). To run applications developed using the SDK, you will need a Java 7 or higher Java Runtime Environment (JRE).

Both the official Oracle Java distribution and the OpenJDK distribution are supported by the what3words SDK.

Installation

The what3words Android SDK is distributed as a compressed archive. To install, firstly uncompress the archive onto your development machines's filesystem.

.
├── sample
│   └── W3wDemo
│       ├── settings.gradle
│       ├── gradlew.bat
│       ├── gradlew
│       ├── gradle.properties
│       ├── gradle
│       │   └── wrapper
│       │       └── gradle-wrapper.jar
│       ├── build.gradle
│       ├── app
│       │   ├── src
│       │   │   ├── test
│       │   │   │   └── java
│       │   │   │       └── com
│       │   │   │           └── what3words
│       │   │   │               └── android
│       │   │   │                   └── w3wdemo
│       │   │   │                       └── ExampleUnitTest.java
│       │   │   ├── release
│       │   │   ├── main
│       │   │   │   ├── java
│       │   │   │   │   └── com
│       │   │   │   │       └── what3words
│       │   │   │   │           └── android
│       │   │   │   │               └── w3wdemo
│       │   │   │   │                   ├── W3wDemoActivity.java
│       │   │   │   │                   ├── MapsActivity.java
│       │   │   │   │                   └── Globals.java
│       │   │   │   ├── assets
│       │   │   │   │   ├── wordlists
│       │   │   │   │   ├── reversegeocode
│       │   │   │   │   ├── dym_settings.txt
│       │   │   │   │   └── att
│       │   │   │   └── AndroidManifest.xml
│       │   │   └── androidTest
│       │   │       └── java
│       │   │           └── com
│       │   │               └── what3words
│       │   │                   └── android
│       │   │                       └── w3wdemo
│       │   │                           └── ApplicationTest.java
│       │   ├── libs
│       │   │   └── w3w-android.jar
│       │   ├── build.gradle
│       │   └── app.iml
│       ├── W3wDemo.iml
│       └── README.md
├── lib
│   └── w3w-android.jar
├── javadoc
├── assets
│   ├── wordlists
│   ├── reversegeocode
│   ├── dym_settings.txt
│   ├── att
│   └── README.txt
└── README.txt
            

The following steps should then be performed before using the SDK:

  1. Copy ./lib/w3w-android.jar to your Android app's library directory and include it in your project; this will ensure that the Android SDK is available inside the app.
  2. Copy ./assets into your project's assets directory; this will ensure that the Android SDK is able to read them when initialising.

Documentation

Complete and detailed documentation of the what3words Android SDK, its public classes and methods are available in Javadoc format .

The remainder of this page provides an introduction to the concepts and useage of each of the Android SDK's public methods.

SDK Initialisation

To initialise the what3words Android SDK, instantiate a new instance of W3wAndroidSDKFactory, passing the required display language and an instance of a class that implements the W3wLoadedListener interface. The what3words Android SDK initialises asynchronously; upon successful initialisation the W3wLoadedLister's loaded method will be invoked with an instance of W3wAndroidSDK.

Reinitialising the SDK is expensive and time consuming; we recommend that the W3wAndroidSDK instance is stored within your application and only reinitialised if a different display language is required.

                        
import com.what3words.sdk.android.W3wAndroidSDKFactory;
import com.what3words.sdk.android.W3wAndroidSDK;
import com.what3words.sdk.android.W3wLoadedListener;

W3wAndroidSDK sdk = null;

new W3wAndroidSDKFactory(context, "en", new W3wLoadedListener() {
	@Override
	public void loaded(W3wAndroidSDK sdkInst) {
		sdk = sdkInst;
	}

	@Override
	public void fail(Exception e) {
	    // handle initialisation failure gracefully
	}
}).init();
                        
                    

Forward Geocoding

The W3wAndroidSDK.forwardGeocode() method converts a 3 word addresses to coordinates.

                        
import com.what3words.apiinstance.W3wPosition;
import com.what3words.sdk.android.W3wAndroidSDKFactory;
import com.what3words.sdk.android.W3wAndroidSDK;
import com.what3words.sdk.android.W3wLoadedListener;

W3wAndroidSDK sdk = null;

new W3wAndroidSDKFactory(context, "en", new W3wLoadedListener() {
	@Override
	public void loaded(W3wAndroidSDK sdkInst) {
		sdk = sdkInst;

		String addr = "index.home.raft";
		W3wPosition pos = sdk.forwardGeocode(addr);
	}

	@Override
	public void fail(Exception e) {
	    // handle initialisation failure gracefully
	}
}).init();
                        
                    

Reverse Geocoding

The W3wAndroidSDK.reverseGeocode() method converts coordinates to a 3 word address.

                        
import com.what3words.common.LatLng;
import com.what3words.apiinstance.W3wPosition;
import com.what3words.sdk.android.W3wAndroidSDKFactory;
import com.what3words.sdk.android.W3wAndroidSDK;
import com.what3words.sdk.android.W3wLoadedListener;

W3wAndroidSDK sdk = null;

new W3wAndroidSDKFactory(context, "en", new W3wLoadedListener() {
	@Override
	public void loaded(W3wAndroidSDK sdkInst) {
		sdk = sdkInst;

		LatLng coords = new LatLng(51.455905, -0.341492);
		W3wPosition pos = sdk.reverseGeocode(coords);
	}

	@Override
	public void fail(Exception e) {
	    // handle initialisation failure gracefully
	}
}).init();
                        
                    

AutoSuggest

The W3wAndroidSDK.autosuggest() method returns a list of 3 word addresses based on user input and other parameters.

This method provides corrections for the following types of input error:

  • typing errors
  • spelling errors
  • misremembered words (e.g. singular vs. plural)
  • words in the wrong order

The autosuggest method determines possible corrections to the supplied 3 word address string based on the probability of the input errors listed above and returns a ranked list of suggestions. This method can also take into consideration the geographic proximity of possible corrections to a given location to further improve the suggestions returned.

Input 3 word address

You will only receive results back if the partial 3 word address string you submit contains the first two words and at least the first character of the third word; otherwise an error message will be returned.

Clipping and Focus

We provide various clip policies to allow you to specify a geographic area that is used to exclude results that are not likely to be relevant to your users. We recommend that you use the clip parameter to give a more targeted, shorter set of results to your user. If you know your user’s current location, we also strongly recommend that you use the focus to return results which are likely to be more relevant.

In summary, the clip policy is used to optionally restrict the list of candidate AutoSuggest results, after which, if focus has been supplied, this will be used to rank the results in order of relevancy to the focus.

Results

A maximum of 10 AutoSuggest results may be returned, but you may choose to display fewer results to your user e.g. the first 3 or 5 (depending on your user interface). By default, 3 results will be returned. It is possible we may increase the number of results returned in the future, so if you choose to limit the list of results returned, we recommend that you choose to include e.g. the top 3/5/7 results rather than choose to exclude the bottom e.g. 8/9/10 results.

Clipping Policies

None default

ClipNone. No clipping takes place; this is the default.

Radius

ClipRadius(LatLng coords, double radius). Clips to a radius of radius kilometers from the point specified as coords.

Bounding Box

ClipBBox(double nelat, double neLng, double swLat, double swlat). Clips to 3 word addresses that are fully contained inside a bounding box, specified by the northeast and southwest corner coordinates.

                        
import com.what3words.common.LatLng;
import com.what3words.apiinstance.Suggestion;
import com.what3words.autosuggest.IClip;
import com.what3words.autosuggest.ClipNone;
import com.what3words.apiinstance.W3wPosition;
import com.what3words.sdk.android.W3wAndroidSDKFactory;
import com.what3words.sdk.android.W3wAndroidSDK;
import com.what3words.sdk.android.W3wLoadedListener;

W3wAndroidSDK sdk = null;

new W3wAndroidSDKFactory(context, "en", new W3wLoadedListener() {
    @Override
    public void loaded(W3wAndroidSDK sdkInst) {
        sdk = sdkInst;

        String addr = "index.home.ra";
        LatLng focus = new LatLng(51.455905, -0.341492);
        IClip clip = new ClipNone();
        List<Suggestion> = sdk.autosuggest(addr, focus, clip);
    }

    @Override
    public void fail(Exception e) {
        // handle initialisation failure gracefully
    }
}).init();
                        
                    

StandardBlend

W3wAndroidSDK.standardblend() method returns a blend of the three most relevant 3 word address candidates for a given location, based on a full or partial 3 word address.

The specified 3 word address may either be a full 3 word address or a partial 3 word address containing the first 2 words in full and at least 1 character of the 3rd word. The standardblend resource provides the search logic that powers the search box on map.what3words.com and in the what3words mobile apps.

Input 3 word address

You will only receive results back if the partial 3 word address string you submit contains the first two words and at least the first character of the third word; otherwise an error message will be returned.

Visualising StandardBlend

The what3words sample Android app uses the standardBlend method to display candidate 3 word addresses. If the contents of the search box matches a partial 3 word address, detected by the regular expression ^\p{L}{4,}+\.\p{L}{4,}+\.\p{L}{1,}+$, then standardBlend will be invoked and any resulting candidate 3 word addresses displayed. The app also displays a relevant flag, keyed on the ISO 3166-1 alpha-2 country code that is returned by the SDK. For the app, we are using a flag set licensed from IconDrawer with the addition of two additional flags for tn and xk .

                        
import com.what3words.common.LatLng;
import com.what3words.apiinstance.Blend;
import com.what3words.apiinstance.W3wPosition;
import com.what3words.sdk.android.W3wAndroidSDKFactory;
import com.what3words.sdk.android.W3wAndroidSDK;
import com.what3words.sdk.android.W3wLoadedListener;

W3wAndroidSDK sdk = null;

new W3wAndroidSDKFactory(context, "en", new W3wLoadedListener() {
    @Override
    public void loaded(W3wAndroidSDK sdkInst) {
        sdk = sdkInst;

        String addr = "index.home.ra";
        // Populate focus with the return from LocationServices.FusedLocationApi.getLastLocation()
        LatLng focus = new LatLng(51.455905, -0.341492);

        List<Blend> = sdk.standardBlend(addr, focus);
    }

    @Override
    public void fail(Exception e) {
        // handle initialisation failure gracefully
    }
}).init();
                        
                    

Get Languages

The W3wAndroidSDK.getAvailableLanguages() method allows you to query the what3words SDK for the list of languages that the SDK currently supports.

                        
import com.what3words.apiinstance.W3wPosition;
import com.what3words.sdk.android.W3wAndroidSDKFactory;
import com.what3words.sdk.android.W3wAndroidSDK;
import com.what3words.sdk.android.W3wLoadedListener;

import java.util.Set;

W3wAndroidSDK sdk = null;

new W3wAndroidSDKFactory(context, "en", new W3wLoadedListener() {
	@Override
	public void loaded(W3wAndroidSDK sdkInst) {
		sdk = sdkInst;

        Set<String> languages = sdk.getAvailableLanguages();
        String lang = sdk.getCurrentLanguage();
	}

	@Override
	public void fail(Exception e) {
	    // handle initialisation failure gracefully
	}
}).init();
                        
                    

Calculate Distance

The what3words SDK provides two helper functions to calculate distances. W3wAndroidSDK.distanceToPoint() returns the distance between a 3 word address and a given point, whilst W3wAndroidSDK.distanceBetweenPoints() returns the distance between two points. Both of these methods return distance in meters.

                        
import com.what3words.common.LatLng;
import com.what3words.sdk.android.W3wAndroidSDKFactory;
import com.what3words.sdk.android.W3wAndroidSDK;
import com.what3words.sdk.android.W3wLoadedListener;

import java.util.Set;

W3wAndroidSDK sdk = null;

new W3wAndroidSDKFactory(context, "en", new W3wLoadedListener() {
	@Override
	public void loaded(W3wAndroidSDK sdkInst) {
		sdk = sdkInst;

		String addr = "index.home.raft";
		LatLng endPoint = new LatLng(64.13577516756123, -21.919784545898438);
		double distance = sdk.distanceToPoint(addr, endPoint);

		LatLng startPoint = new LatLng(51.455905, -0.341492);
		distance = sdk.distanceBetweenPoints(startPoint, endPoint);
	}

	@Override
	public void fail(Exception e) {
	    // handle initialisation failure gracefully
	}
}).init();
                        
                    

Sample Application

The what3words Android SDK provides a sample Android application, located in [sdk-installation-path]/sample and can be compiled and run from within Android Studio .

The sample app demonstrates how to initialise the what3words Android SDK, to forward geocode a 3 word address to coordinates, to reverse geocode coordinates to a 3 word address and how to create a search box that uses the SDK's Standard Blend method to obtain the most relevant 3 word address candidates from a search string.