Tutorials | what3words
All tutorials



This tutorial outlines the six steps to integrating what3words into a navigation app. Make sure to download the what3words component library before starting this tutorial. You can review the design guidelines here.

Using our API wrappers is a straightforward way of integrating quickly with our API. For full installation details, check out our wrapper pages:

Swift: https://developer.what3words.com/tutorial/swift/
Objective-C: https://developer.what3words.com/tutorial/objective-c/
Android: https://developer.what3words.com/tutorial/android/

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


Add 3 word address functionality to the search bar

To offer the best user experience, enable users to enter a 3 word address into an existing drop off/destination bar. This includes the ability to:

  1. Copy and paste a 3 word address into the search bar (with or without proceeding ///)
  2. Detect when a user is typing a 3 word address and display intelligent suggestions for the user using what3words API AutoSuggest (see section 4).

To add 3 word address functionality to a search box, firstly your app needs to detect if an input string looks like a partial or full 3 word address.

This can be done by utilising the RegEx in this tutorial. Our partial RegEx allows detection of a 3 word address once the user has typed the first character of the third word. For example, “filled.count.s”

In contrast, the full search RegEx will only detect when a user has entered a complete string that looks like a 3 word address e.g. “filled.count.soap”

String text = "filled.count.s";

String regex = "[^0-9`~!@#$%^&*()+\\-_=\\[{\\}\\\\|'<,.>?/\";:£§º©®\\s]{1,}[・.。][^0-9`~!@#$%^&*()+\\-_=\\[{\\}\\\\|'<,.>?/\";:£§º©®\\s]{1,}[・.。][^0-9`~!@#$%^&*()+\\-_=\\[{\\}\\\\|'<,.>?/\";:£§º©®\\s]{1,}";

Pattern pattern = Pattern.compile(regex);
Matcher matcher = pattern.matcher(text);
while (matcher.find()) 

Full 3 word address RegEx code sample:

String text = "index.home.raft";
String regex = "^/*[^0-9`~!@#$%^&*()+\\-_=\\[{\\}\\\\|'<,.>?/\";:£§º©®\\s]{1,}[・.。][^0-9`~!@#$%^&*()+\\-_=\\[{\\}\\\\|'<,.>?/\";:£§º©®\\s]{1,}[・.。][^0-9`~!@#$%^&*()+\\-_=\\[{\\}\\\\|'<,.>?/\";:£§º©®\\s]{1,}$";

Pattern pattern = Pattern.compile(regex);
Matcher matcher = pattern.matcher(text);

if (matcher.find())
  System.out.println(text + " is the format of a three word address");
  System.out.println(text + " is not a three word address");

Enable calls to the what3words API for 3 word address suggestions (search bar)

When a user enters a partial 3 word address (after the first letter of the third word) your app should start to call the what3words API to obtain 3 word address suggestions to display to the user, using the AutoSuggest endpoint.

Supplying the AutoSuggest focus parameter with a latitude and longitude of the user’s location will enable more locally relevant suggestions to be served to the user.  This may be relevant in cases where local results are significantly more important than total world results.

Below are examples of using our API wrappers to call the what3words API passing in clipping and focus parameters:

Autosuggest autosuggest = api.autosuggest("index.home.raft")
        .focus(new Coordinates(51.4243877,-0.34745))
System.out.println("Autosuggest: " + autosuggest);

Displaying AutoSuggest results

You can configure the number of AutoSuggest results using the n-focus-results parameter. To display the results, we recommend using our 3 word address search component with the following key attributes:

  1. 3 slashes (“///”) before each 3 word address suggestion.
  2. A country flag for each 3 word address suggestion (country for each suggestion in the API response).
  3. Distance from the user to each of the 3 word address suggestions (distanceToFocusKm for each suggestion in the API response).

Location context for each 3 word address suggestion (we return this as nearestPlace for each suggestion in the API response).


Plot the 3 word address on the map

Use the convert-to-coordinates endpoint of the API to obtain the latitude and longitude for the user’s chosen 3 word address.  Plot this on the map, remembering to label the pin with the 3 word address it came from (either in search bar or on map).

Below are examples of using our API wrappers to call the what3words API:

// Convert a 3 word address to coordinates
ConvertToCoordinates coordinates = api.convertToCoordinates("filled.count.soap")
System.out.println("Coordinates: " + coordinates);

Displaying the drop off location

In many navigation apps, users are able to drop a pin on the map and discover the location information attached to that point.

It is possible to display a 3 word address for such a point by using the convert-to-3wa endpoint of the what3words API.  Simply supply the endpoint with the latitude and longitude in WGS84 decimal format and it will output the corresponding 3 word address.

You can also choose an optional language parameter in case you want to display the 3 word address in a language other than the default English.

Development Checklist

  • Add 3 word address RegEx to the search to determine when a user is searching for a 3 word address.
  • Call the what3words API Autosuggest function to provide suggestions.
  • Display Autosuggest results with ///, nearest place and country flag.
  • Validate the input and gain the latitude and longitude using the convert-to-coordinates API function.
  • Display the drop off location with a map marker.
  • Display the 3 word address when selecting the map marker.

Related tutorials

Back to top