JarCasting
w3w-android-components
An Android library to use the what3words v3 API autosuggest.
To obtain an API key, please visit https://what3words.com/select-plan and sign up for an account.
Installation
The artifact is available through
Gradle
implementation 'com.what3words:w3w-android-components:2.0.2'
Documentation
See the what3words public API documentation
Usage
AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.yourpackage.yourapp">
<uses-permission android:name="android.permission.INTERNET" />
...
if minSdkVersion < 24 add this to build.gradle (app level)
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
activity_main.xml
<androidx.constraintlayout.widget.ConstraintLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent">
<com.what3words.components.text.W3WAutoSuggestEditText
android:id="@+id/suggestionEditText"
android:layout_width="0dp"
android:layout_height="wrap_content"
app:layout_constraintEnd_toEndOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintTop_toTopOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>
Kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
suggestionEditText.apiKey("YOUR_API_KEY_HERE")
.returnCoordinates(false)
.onSelected { w3wSuggestion ->
if (w3wSuggestion != null) {
Log.i( "MainActivity","words: ${w3wSuggestion.suggestion.words}, country: ${w3wSuggestion.suggestion.country}, distance: ${w3wSuggestion.suggestion.distanceToFocusKm}, near: ${w3wSuggestion.suggestion.nearestPlace}, latitude: ${w3wSuggestion.coordinates?.lat}, longitude: ${w3wSuggestion.coordinates?.lng}"
)
} else {
Log.i("MainActivity", "invalid w3w address")
}
}
.onError {
Log.e("MainActivity", "${it.key} - ${it.message}")
}
}
Java
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
W3WAutoSuggestEditText autoSuggestEditText = findViewById(R.id.suggestionEditText);
autoSuggestEditText.apiKey("YOUR_API_KEY_HERE")
.returnCoordinates(false)
.onSelected(null, null, (W3WSuggestion w3wSuggestion) -> {
if (w3wSuggestion != null) {
Log.i("MainActivity", String.format("words: %s, country: %s, near: %s", w3wSuggestion.getSuggestion().getWords(), w3wSuggestion.getSuggestion().getCountry(), w3wSuggestion.getSuggestion().getNearestPlace()));
} else {
Log.i("MainActivity", "invalid w3w address");
}
})
.onError(null, (APIResponse.What3WordsError what3WordsError) -> Log.e("MainActivity", String.format("%s - %s", what3WordsError.getKey(), what3WordsError.getMessage())));
}
If you run our Enterprise Suite API Server yourself, you may specify the URL to your own server like so:
suggestionEditText.apiKey("YOUR_API_KEY_HERE", "https://api.yourserver.com")
General properties:
| property | default value | type | description | XML | Programatically |
|---|---|---|---|---|---|
| apiKey | N/A | String | Your what3words API key. mandatory | |
|
| hint | e.g. lock.spout.radar | String | Placeholder text to display in the input in its default empty state. | |
|
| errorMessage | No valid what3words address found | String | Overwrite the validation error message with a custom value. | |
|
| focus | N/A | Coordinates | This is a location, specified as a latitude/longitude (often where the user making the query is). If specified, the results will be weighted to give preference to those near the focus |
|
|
| clipToCountry | N/A | String | Clip results to a given country or comma separated list of countries. Example value:"GB,US". | |
|
| clipToCircle | N/A | Coordinates, Int | Clip results to a circle, specified by Coordinate(lat,lng) and kilometres, where kilometres in the radius of the circle. | |
|
| clipToBoundingBox | N/A | BoundingBox | Clip results to a bounding box specified using co-ordinates. | |
|
| clipToPolygon | N/A | List of Coordinates | Clip results to a bounding box specified using co-ordinates. | |
|
| returnCoordinates | false | Boolean | Calls the what3words API to obtain the coordinates for the selected 3 word address (to then use on a map or pass through to a logistic company etc) | |
|
| allowInvalid3wa | false | Boolean | Allow invalid 3 word address | |
|
| imageTintColor | #E11F26 | Color | Changes /// image colour. | |
|
| suggestionsListPosition | BELOW | Enum | Suggestion list position which can be below (default) the EditText or above |
|
|
Enable voice autosuggest:
The component also allows for voice input using the what3words Voice API. This feature 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.
By default the voice language is set to English but this can be changed using the voiceLanguage property (for list of available languages please check the properties table below). Voice input respects the clipping and focus options applied within the general properties. We recommend applying clipping and focus where possible to display as accurate suggestions as possible. To enable voice you can do with programmatically or directly in the XML.
AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.yourpackage.yourapp">
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
...
activity_main.xml
<com.what3words.components.text.W3WAutoSuggestEditText
android:id="@+id/suggestionEditText"
android:layout_width="0dp"
android:layout_height="wrap_content"
app:layout_constraintEnd_toEndOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintTop_toTopOf="parent"
app:voiceEnabled="true" />
or
suggestionEditText.apiKey("YOUR_API_KEY_HERE")
.returnCoordinates(false)
.voiceEnabled(true)
...
Voice properties:
| property | default value | type | description | XML | Programatically |
|---|---|---|---|---|---|
| voiceEnabled | false | Boolean | Enables voice suggestion to allow the user to say the three word address instead of writing it. | |
|
| voiceFullscreen | false | Boolean | Voice activation will be fullscreen instead of inline. | |
|
| voiceLanguage | en | String | Available voice languages: ar for Arabic, cmn for Mandarin Chinese, de for German, en Global English (default), es for Spanish, hi for Hindi, ja for Japanese and ko for Korean |
|
|
Voice only:
If you want to use voice-only (no text input) please look at our voice-sample app in this repo for examples of how to use our W3WAutoSuggestVoice component.
Advanced usage:
If you want to check different ways to use our component please look at our advanced-sample app in this repo for examples of how to use and customize our W3WAutoSuggestText component.
Styles:
Use our base style as parent and you can set the custom properties available with XML on the table above and the normal EditText styling, i.e:
<style name="YourCustomStyle" parent="Widget.AppCompat.W3WAutoSuggestEditText">
<item name="android:textColor">#000000</item>
<item name="android:textColorHint">#888888</item>
<item name="errorMessage">Your custom error message</item>
<item name="android:hint">Your custom placeholder</item>
<item name="android:textAppearance">@style/YourCustomStyleTextAppearance</item>
</style>
<style name="YourCustomStyleTextAppearance" parent="TextAppearance.AppCompat">
<item name="android:textSize">22sp</item>
<item name="android:fontFamily">sans-serif-medium</item>
</style>
Full documentation:
Existing components:
| Name | Summary |
|---|---|
| W3WAutoSuggestEditText | class W3WAutoSuggestEditText : AppCompatEditTextA AppCompatEditText to simplify the integration of what3words text and voice auto-suggest API in your app. |
| W3WAutoSuggestVoice | class W3WAutoSuggestVoice : ConstraintLayoutA View to simplify the integration of what3words voice auto-suggest API in your app. |
| W3WAutoSuggestErrorMessage | class W3WAutoSuggestErrorMessage : AppCompatTextViewA AppCompatTextView styled and ready to show error messages. |
| W3WAutoSuggestPicker | class W3WAutoSuggestPicker : RecyclerViewA RecyclerView to show W3WSuggestion returned by w3w auto suggest component modularized to allow developers to choose picker location on the screen. |
