All tutorials

Android

intermediate

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 is a fast, simple interface which allows you to convert 3 word addresses such as ///index.home.raft to latitude and longitude coordinates such as (-0.203586, 51.521251) and vice versa. It features a powerful autosuggest function, which can validate and autocorrect user input and limit it to certain geographic areas (this powers the search box on our map site). It allows you to request a section of the what3words grid (which can be requested as GeoJSON for easy display on online maps), and to request the list of all languages supported by what3words. For advanced users, autosuggest can be used to post-process voice output. See links on the left to navigate.

All coordinates are latitude,longitude pairs in standard WGS-84 (as commonly used worldwide in GPS systems). All latitudes must be in the range of -90 to 90 (inclusive).

1

You will need a what3words API key to complete this tutorial.

2

Installation

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

implementation 'com.what3words:w3w-android-wrapper:3.1.11'
Copied
3

Setup

Add to AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.yourpackage.yourapp">

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

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

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'
}
Copied

add the following ProGuard rules:

-keep class com.what3words.javawrapper.request.* { *; }
-keep class com.what3words.javawrapper.response.* { *; }
-keep class com.what3words.androidwrapper.voice.* { *; } // add if using voice api autosuggest 
Copied
4

Usage

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?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        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)
                }
            }
        }
    }
}
Copied

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 {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

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

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)
    }.startListening()
Copied

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()
Copied

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()
Copied

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)
    )).execute()
Copied

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

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

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", "https://api.yourserver.com")  
Copied

Related tutorials

Back to top