Tutorials | what3words
We use cookies, including third party cookies, to improve your experience and for marketing purposes. By continuing to browse we assume you have consented to their use.Learn more
got it
All tutorials

Ride-hailing

intermediate

This tutorial outlines the six steps to integrating what3words into a ride-hailing app. Make sure to download the what3words component library before starting this tutorial. You can review our UX 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.

2

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 displaying intelligent suggestions for the user using what3words API AutoSuggest. We’ll guide you through this feature in section 4 of this tutorial.

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”.

Partial RegEx code sample:

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()) 
  System.out.println(matcher.group());
Copied

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");
else
  System.out.println(text + " is not a three word address");
Copied
3

Enable calls to the what3words API for 3 word address suggestions

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.

If your ride-hailing service is restricted to specific countries, use the clip-to-country parameter to restrict suggestions and improve the relevance of suggested addresses.

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")
        .clipToCountry("UK")
        .focus(new Coordinates(51.4243877,-0.34745))
        .execute();
System.out.println("Autosuggest: " + autosuggest);
Copied
4

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).

5

Validate the entered 3 word address and get the latitude and longitude

To validate that the input is a 3 word address and obtain the latitude and longitude once a user has entered a full string and selected a result, a call to the convert-to-coordinates API endpoint should be made.

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")
        .execute();
System.out.println("Coordinates: " + coordinates);
Copied
6

Displaying the drop off location

Once a user has entered a valid 3 word address and the map has zoomed to the 3 word address, displaying it in the map marker allows the user to see the location of the 3 word address before confirming the ride.

Development Checklist

  • Added 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.

Related tutorials

Back to top