Developer

All tutorials

Navigation

intermediate

The easiest way to add what3words to your navigation applications is to use one of what3words API wrapper libraries in Java and Kotlin for your Android apps or in Swift for your iOS apps.

Follow our UX guidelines and these easy self-explanatory steps on how to integrate what3words into a navigation app.

1Get a what3words API Key
2Install API wrapper

To utilise our wrappers, you will first need to download the packages, from either Maven Central (or this GitHub page) or through the Swift Package Manager.

For full details on how to install and initialise the what3words wrappers, see the Swift and Android wrapper tutorials.

Note: For Android integrations, we recommend using exclusively—either the what3words Android wrapper or the what3words Java wrapper.

The what3words Android wrapper essentially encompasses the functionality of the Java wrapper, offering additional features such as voice capabilities and the ability to manage API key restrictions.

The code snippets that we have added in this tutorial assume that you will be using the what3words Android wrapper.

To aid user education, it is useful to add placeholder text in your app’s address search bar indicating to users that what3words addresses can be searched for.

An example of placeholder text

what3words address entry encompasses:

  • copy and paste a what3words address into the search bar (with or without the preceding ///)
  • detect when a user is typing in a what3words address and display intelligent suggestions using the what3words API’s AutoSuggest functionality (this will be covered in more detail at a later step)

The latter case requires utilising the RegEx function of our wrappers, to identify the what3words address pattern.

what3words Address Detection Example:

import com.what3words.javawrapper.What3WordsV3

String text = "index.home.raft"
if(What3WordsV3.isPossible3wa(text)){
	 System.out.println("Input is in the form of a three word address")
} else {
	 System.out.println("Input is NOT in the form of a three word address")
}
Copied
4Enable calls to the API for suggestions

Once the user has entered the first letter of the final word of a what3words address, your app should call the what3words API to provide intelligent what3words address suggestions, using our API’s AutoSuggest endpoint. These results will be updated as the user continues entering the what3words address.

A highly important step in optimising the user experience is in contextualising the address suggestions to where the user is located. This can be done by supplying the API with the user’s device location, enabling the returned suggestions to be tailored to the user’s current location using an API call parameter called focus.

Similarly, if your service operates in a fixed country, you can use the clip-to-country parameter to restrict the returned suggestions to geographically relevant results.

AutoSuggest API Call Example:

import com.what3words.javawrapper.request.Coordinates

// Create optional options to fine-tune the autosuggest request
AutosuggestOptions options = AutosuggestOptions()
Coordinates focus = Coordinates(/*latitude:*/51.502,/*longitude:*/-0.12345)
options.setFocus(focus)

Autosuggest result = wrapper.autosuggest("filled.count.so").options(options).execute()
if (result.isSuccessful) {
		System.out.println(result.suggestions.size)
} else {
		System.out.println(resut.error.message)
}
Copied
5Displaying AutoSuggest results

As the user types the final word of the what3words address, you can show 3 AutoSuggest results with each keystroke; offering intelligent address suggestions to the user, and expediting the entry of the correct address.

There are three components to effectively displaying a what3words address suggestion:

  • three slashes preceding the what3words address (e.g. ///filled.count.soap)
  • the nearest place listed alongside the address suggestion (given as nearestPlace in the API response)
  • distance from the user to the suggested address location (this is given by the distanceToFocusKm result in the API AutoSuggest response)

Collectively, the final two points help provide the suggested address’ location context to the user, and the first signifies that the suggested address is a what3words address, not a traditional street address.

suggestions in navigation app

6Validate what3words and get coordinates

Once the user has selected the desired what3words address from the list of suggestions, it needs to be converted into standard GPS coordinates to then plot the point on the map using your standard POI marker, enable route calculation, or display travel options.

Validate what3words and get coordinates

To do this, use the convertToCoordinates wrapper function. An example of doing this using our mobile wrappers is given below:

String selectedSuggestion = "filled.count.soap"
ConvertToCoordinates result = wrapper.convertToCoordinates(selectedSuggestion)
if (result.isSuccessful) {
		System.out.println("Coordinates: ${result.coordinates.lat}, ${result.coordinates.lng}")		
} else {
		System.out.println(result.error.message)
}
Copied

Development Checklist

  • Created an API key for the what3words API;
  • The packages have been loaded correctly, and the API initialised according to the relevant wrapper guidance.
  • Placeholder text in the search bar educates the user on the ability to enter what3words addresses;
  • The keyboard displays the full stop on the first screen shown to the user;
  • Check if the keyboard supports all enabled languages;
  • Up until the final word of the what3words address is entered, traditional destination options are returned;
  • Once the final word begins to be entered, what3words results are shown.

API Parameters

  • Focus is enabled;
  • Other parameters, such as clipping, or language settings, are enabled (if applicable).

Front End

  • Results update live with each keystroke;
  • Three what3words address suggestions are displayed per keystroke;
  • Nearest place information (either ours or via an alternative source) is displayed alongside distance from the user;
  • /// is affixed to the address (e.g. ///filled.count.soap vs. filled.count.soap);
  • If there is use of what3words brand assets, they must be the current versions;
  • Correct localisation of copy for non-English languages (e.g. distances stated in kilometers or miles).

Contact Support

Have any questions?

We’re here to support you! If you have any questions while using what3words for Excel, get in touch with us by writing us an email at support@what3words.com.

Mobile AppAdd a 3 word address input fieldDetect if text looks like a 3 word addressDisplay a 3 word addressUse 3 word addresses with a mapUse 3 word addresses within an address searchAndroidJavaObjective-CSwift

Related tutorials