Developer

All tutorials

Ride-hailing Integration

intermediate

The easiest way to add what3words to your ride-hailing, web booking, and call booking 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 ride-hailing app.

1Get 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 offer the best user experience, enable users to enter a what3words address into an existing address search bar. The ability to do this is best communicated by placeholder text in the search bar prompting a user to enter a what3words address.

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 to the user using the what3words API’s AutoSuggest functionality (this will be covered in more detail at a later step)

To add this functionality to an existing search bar, your app will first need to detect if a full or partial input string is in the format of a what3words address. This can be achieved using the RegEx function of the API wrapper.

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 to the user, 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

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

  1. 3 slashes (“///”) before each what3words address suggestion;
  2. A nearest place;
  3. Distance from the user to each of the what3words address suggestions (distanceToFocusKm for each suggestion in the API response).

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

ride-hailing-suggestions

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 enable route calculation and pricing.

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
7Displaying the what3words on the map

Once the user has selected a what3words address from the AutoSuggest-generated list, the point should be displayed on the route by appending a label with the what3words address on it to the map marker, allowing the user to see the location of the what3words address before confirming the ride.

Coordinates Used For User Confirmation

8Full Example

The example below takes the concepts described earlier and demonstrates how a what3words integration could look on your ride-hailing apps.

ride hailing demo app

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).
  • Upon selection of a suggested address, the selected option is highlighted to indicate it is chosen;
  • The selected address is successfully converted to coordinates;
  • The resulting coordinates are used to display the destination location on the map and sent for route/price calculation;
  • The map destination marker has the correct what3words address attached via a label.

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 AppDetect if text looks like a 3 word addressDisplay a 3 word addressUse 3 word addresses with a mapUse 3 word addresses with voice inputUse 3 word addresses within an address searchAndroidJavaSwift

Related tutorials