All tutorials

Legacy Android


Note: This library has been deprecated and will no longer receive support. To upgrade to the Version 4.x of the Android API Wrapper library, please refer to this Version 4.x Tutorial and this Migration Guide.

The Android API wrapper is useful for Android developers who wish to seamlessly integrate the what3words API into their Android applications, without the hassle of having to manage the low level API calls themselves.

The what3words API allows conversion between 3-word addresses (e.g., ///index.home.raft) and coordinates (e.g., -0.203586, 51.521251). It features powerful autosuggest functions to validate and autocorrect user input, restrict suggestions to specific areas, request sections of the what3words grid as GeoJSON, and list all supported languages. Advanced users can also post-process voice output with autosuggest.

All coordinates are in latitude, longitude pairs using the WGS-84 standard, with latitudes ranging from -90 to 90.

Full sample app for the wrapper can be found in our Github repo
github icon white Android Sample Apps



The library is available through Maven Central. Please add the following to your

implementation 'com.what3words:w3w-android-wrapper:3.1.22'


Add to AndroidManifest.xml:

<manifest xmlns:android=""

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

    <!-- add if using voice api autosuggest -->
    <uses-permission android:name="android.permission.RECORD_AUDIO" />

Add the following to build.gradle (app level):

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8

dependencies {
    // we are going to use coroutines for kotlin examples, feel free to use any other library of your choice.
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.7"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.7"

    // we are going to use rxjava for java examples, feel free to use any other library of your choice.
    implementation 'io.reactivex.rxjava3:rxjava:3.0.7'
    implementation 'io.reactivex.rxjava3:rxandroid:3.0.0'


convertTo3wa example in kotlin with Coroutines.

Because it is not possible to perform a networking operation on the main application thread, API calls need to be made in a background thread, we used Coroutines in this example. for more Kotlin examples try our sample app in this repo.

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {

        val wrapper = What3WordsV3("YOUR_API_KEY_HERE", this)
        CoroutineScope(Dispatchers.IO).launch {
            //use wrapper.convertTo3wa() with Dispatcher.IO - background thread
            val result = wrapper.convertTo3wa(Coordinates("51.2305", "-0.24123")).execute()
            CoroutineScope(Dispatchers.Main).launch {
                //use Dispatcher.Main to update your views with the results if needed - Main thread
                if (result.isSuccessful) {
                    Log.i("MainActivity", "3 word address: ${result.words}")
                } else {
                    Log.e("MainActivity", result.error.message)

convertTo3wa example in Java with RxJava

Because it is not possible to perform a networking operation on the main application thread, API calls need to be made in a background thread, we used RxJava in this example. for more Java examples try our sample-java app in this repo

public class MainActivity extends AppCompatActivity {

    protected void onCreate(@Nullable Bundle savedInstanceState) {

        What3WordsV3 wrapper = new What3WordsV3("YOUR_API_KEY_HERE", this);
        Observable.fromCallable(() -> wrapper.convertTo3wa(new Coordinates(51.2423, -0.12423)).execute())
                .subscribe(result -> {
                    if (result.isSuccessful()) {
                        Log.i("MainActivity", String.format("3 word address: %s", result.getWords()));
                    } else {
                        Log.e("MainActivity", result.getError().getMessage());

voice autosuggest example in Kotlin

The Voice API AutoSuggest allows the user to say 3 words and using speech recognition technology displays 3 word address suggestions to the user.

Before enabling Voice AutoSuggest you will need to add a Voice API plan in your account.

For a full working example with voice and AUDIO_RECORD permission, request check our sample and sample-java

Note: Please bear in mind that the Android Emulator cannot record audio. Therefore, you will need to test on a real device that can record.

val microphone = VoiceBuilder.Microphone().onListening { volume ->
    Log.i("VoiceSample","volume: $volume")

wrapper.autosuggest(microphone, "en")
    .focus(51.423, -0.1245)
    .onSuggestions { suggestions ->
        Log.i("VoiceSample","Suggestions: ${suggestions.joinToString { it.words }}")
    }.onError { error ->
        Log.e("VoiceSample", error)

Other available wrapper calls and examples.

wrapper.convertToCoordinates() – Convert a 3 word address to a latitude and longitude

val result = wrapper.convertToCoordinates("index.home.raft").execute()

wrapper.autosuggest() – AutoSuggest can take a slightly incorrect 3 word address, and suggest a list of valid 3 word addresses. For more autosuggest proprieties similar to focus below go to our documentation

 val result = wrapper.autosuggest("index.home.r").focus(51.502,-0.12345).execute()

wrapper.gridSection() – Returns a section of the 3m x 3m what3words grid for a bounding box.

val result = wrapper.gridSection(BoundingBox(
        Coordinates(51.515900, -0.212517), 
        Coordinates(51.527649, -0.191746)

wrapper.availableLanguages() – Retrieves a list all available 3 word address languages.

val result = wrapper.availableLanguages().execute()

If you run our Enterprise Suite API Server yourself, you may specify the URL to your own server like so:

val wrapper = What3Words("YOUR_API_KEY_HERE", "")  

Reminder: To upgrade to the latest version (4.x) of the Android API Wrapper library, please refer to the Migration Guide from Version 3.x to 4.x.

Mobile AppAdd a 3 word address input fieldUse 3 word addresses with a mapUse 3 word addresses with voice inputUse 3 word addresses within an address searchAndroid

Related tutorials