Developer

All tutorials

Migrating Android API Wrapper from version 3.x. to 4.x

intermediate

In version 4.0, the Android API Wrapper library changed significantly. This guide will help you gradually adapt your existing code to the new wrapper.

Note:

  • For users still using version 3.x, you can access the legacy Android tutorial here.
  • For users using version 4.x, you can access the latest Android tutorial here.
1Introduction to the Core Library

The core library establishes essential models and interfaces that maintain consistency across various other libraries. Significant changes have been made by substituting existing models with those from the core library. It is imperative to update your code accordingly to utilise these new models.

Android v4 Tutorial: For a comprehensive guide on using the latest version 4.x, see its tutorial here.

Model Replacements

Android v3 modelsAndroid v4 models
com.what3words.javawrapper.response.SuggestionWithCoordinatescom.what3words.core.types.domain.W3WSuggestion
com.what3words.javawrapper.request.AutosuggestOptionscom.what3words.core.types.options.W3WAutosuggestOptions
com.what3words.javawrapper.response.Coordinatescom.what3words.core.types.geometry.W3WCoordinates
com.what3words.javawrapper.response.Squarecom.what3words.core.types.geometry.W3WRectangle
com.what3words.core.domain.language.W3WLanguagecom.what3words.core.types.language.W3WLanguage
com.what3words.javawrapper.request.BoundingBoxcom.what3words.core.types.geometry.W3WRectangle
com.what3words.androidwrapper.voice.Microphonecom.what3words.core.datasource.voice.audiostream.W3WMicrophone
2Transition to W3WApiTextDataSource and W3WApiVoiceDataSource

The Android API Wrapper version 3 What3WordsV3 has been restructured into two distinct classes:

  • W3WApiTextDataSource: Handles text-based tasks like address searching and conversions.
  • W3WApiVoiceDataSource: Specialises in voice-based address suggestions.

For more information on version 4.x usage, see the latest tutorial here.

3Method Changes List

convertToCoordinates

Converts a what3words address to coordinates.

val wrapper = What3WordsV3(API_KEY, activityContext)
val result = wrapper.convertToCoordinates(words).execute()
Copied

Parameters:

  • words: String (the what3words address to convert)

Return: ConvertToCoordinates (coordinates corresponding to the what3words address)

val textDataSource = W3WApiTextDataSource.create(context, API_KEY) 
val result = textDataSource.convertToCoordinates(words) // Must run on background thread
Copied

Parameters:

  • words: String (the what3words address to convert)

Return: W3WResult<W3WAddress> (result containing the coordinates)

For more details and instructions, see Convert to Coordinates Example.

convertTo3wa

Converts coordinates to a what3words address.

val wrapper = What3WordsV3(API_KEY, activityContext)
val result = wrapper.convertTo3wa(coordinates).execute()
Copied

Parameters:

  • coordinates: Coordinates (latitude and longitude to convert)

Return: ConvertTo3WA (the corresponding what3words address)

val textDataSource = W3WApiTextDataSource.create(context, API_KEY) 
val result = textDataSource.convertTo3wa(coordinates, language) // Must run on background thread
Copied

Parameters:

  • coordinates: W3WCoordinates (latitude and longitude to convert)
  • language: W3WLanguage (the language for the what3words address)

Return: W3WResult<W3WAddress> (result containing the what3words address)

For more details and instructions, see Convert to what3words Address Example.

AutoSuggest

Provides address suggestions based on a partial or full what3words address.

val wrapper = What3WordsV3(API_KEY, activityContext)
val result = wrapper.autosuggest(word).execute()
Copied

Parameters:

  • word: String (the partial or full what3words address to get suggestions for)

Return: Autosuggest (list of suggested addresses)

val textDataSource = W3WApiTextDataSource.create(context, API_KEY) 
val result = textDataSource.autosuggest(word, options) // Must run on background thread
Copied

Parameters:

  • word: String (the partial or full what3words address to get suggestions for)
  • options: W3WAutosuggestOptions? (optional parameters to refine suggestions)

Return: W3WResult<List<W3WSuggestion>> (result containing the list of suggestions)

For more details and instructions, see Autosuggest Example.

availableLanguages

Fetches the list of available languages for what3words addresses.

val wrapper = What3WordsV3(API_KEY, activityContext)
val result = wrapper.availableLanguages().execute()
Copied

Return: AvailableLanguages (set of supported languages)

val textDataSource = W3WApiTextDataSource.create(context, API_KEY) 
val result = textDataSource.availableLanguages() // Must run on background thread
Copied

Return: W3WResult<Set<W3WProprietaryLanguage>> (result containing the set of supported languages)

For more details and instructions, see Get Available Languages Example.

gridSection

Retrieves a section of the what3words address grid for a specified bounding box.

val wrapper = What3WordsV3(API_KEY, activityContext)
val result = wrapper.gridSection(boudingBox).execute()
Copied

Parameters:

  • boundingBox: BoundingBox (the area to get the grid section for)

Return: GridSection (section of the grid)

val textDataSource = W3WApiTextDataSource.create(context, API_KEY) 
val result = textDataSource.gridSection(boundingBox) // Must run on background thread
Copied
  • Parameters:
    • boundingBox: W3WRectangle (the area to get the grid section for)
  • Return: W3WResult<W3WGridSection> (result containing the section of the grid)

For more details and instructions, see Grid Section Example.

Voice AutoSuggest

Provides address suggestions based on voice input.

val wrapper = What3WordsV3(API_KEY, activityContext)
val result = wrapper.autosuggest(microphone, voiceLanguage)
    .onSuggstions { suggestions ->
        // Handle the suggestions
    }
    .onError { error ->
        // Handle the error
    }
Copied

Parameters:

  • microphone: Microphone (the audio input device)
  • voiceLanguage: String (the language for voice recognition)

Return:

  • suggestions: List<Suggestion> (list of suggested addresses)
  • error: APIResponse.What3WordsError (error information)
val voiceDataSource = W3WApiVoiceDataSource.create(API_KEY) 
val result = voiceDataSource.autosuggest(
        audioStream,
        voiceLanguage,
        options,
        onSpeechDetected,
    ) { result ->
        // Handle result
    }
Copied

Parameters:

  • input: W3WAudioStream (the audio input stream)
  • voiceLanguage: W3WLanguage (the language for voice recognition)
  • options: W3WAutosuggestOptions? (optional parameters to refine suggestions)
  • onSpeechDetected: ((String) -> Unit)? (callback for speech detection)

Return:

  • result: W3WResult<List<W3WSuggestion>> (result containing the list of suggestions)

For more details and instructions, see Voice Autosuggest Example.

4AutosuggestHelper

In the previous version, AutosuggestHelper relied on the Android API Wrapper v3 (What3WordsV3). Now, it has transitioned to using W3WApiTextDataSource.

val what3words = What3WordsV3("YOUR_API_KEY_HERE", this)
val autosuggestHelper = AutosuggestHelper(what3words)
Copied
val dataSource = W3WApiTextDataSource.create(context, "YOUR_API_KEY_HERE")
val autosuggestHelper = AutosuggestHelper(dataSource)
Copied

For more details and instructions, see AutoSuggestHelper.

Server and ScriptingAdd a 3 word address input fieldBatch convert 3 word addresses or co-ordinatesDetect if text looks like a 3 word addressDisplay a 3 word addressUse 3 word addresses with voice inputAndroid

Related tutorials