Developer

All tutorials

Legacy Android

intermediate

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

1Get an API Key
2Installation

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

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

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
4Usage

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

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