How to use Waze Deep Links

Waze supports an API that enables developers to open the Waze client application or web page through an external URL. The URL can be accessed from within another mobile application or a mobile web page.

The base URL to use Waze Deep Links is:

https://waze.com/ul

The Waze application can then locate an address, mark an address on the map, or start a navigation session to an address or destination, based on which parameters you pass to this URL.

How Deep Links work

Whether Waze opens as a client app or a web page depends on the user's system configuration:

  • Desktop: Waze opens as a web page.
  • Mobile device (and the Waze app is installed): The Waze app opens.
  • Mobile device (and Waze isn’t installed): Waze opens as a web page.

If you're sure that the Waze app is installed, you can use the URL "waze://" for app-to-app communication without the web experience. This is in place of the base URL described above. Only use this option if you’re sure that your users have Waze installed; otherwise, if users tap the link, nothing happens.

Use Waze Deep Links

You can use the following URL to launch Waze with parameters from a third-party app, email, SMS, web page link, or other source.

Waze Deep Links uses the following URL:

https://waze.com/ul?param_name=value[&param_name=value]

The following are a number of common Waze Deep Links tasks.

To navigate to a specific location:

  1. Open the Waze Live Map and search for your location. Either type in the search box or zoom in and click on a specific segment of the map.
  2. Click the share icon in the bottom-right corner of the map.
  3. A dialog appears. Click Share driving directions, then copy and paste the link.

Example

The following example centers the map on Times Square in New York:

https://www.waze.com/ul?ll=40.75889500%2C-73.98513100&navigate=yes&zoom=17

You can navigate to the following favorites saved in the Waze app:

  • work
  • home

Use the following URL to navigate to a specified favorite:

https://waze.com/ul?favorite=favorite&navigate=yes

The following example sets the destination to work:

https://waze.com/ul?favorite=work&navigate=yes

Search for an address with the following syntax:

https://waze.com/ul?q=search_terms

Values that you pass for the parameters must be URL-encoded. For example, you must replace spaces with %20.

The following example searches for "66 Acacia Avenue":

https://waze.com/ul?q=66%20Acacia%20Avenue

Show on map

Use the following syntax to set the map's magnification level (or zoom) of the Waze map view:

https://waze.com/ul?z=magnification_level

The minimum value for magnification_level is 6 (closest, or most magnification). The maximum value for magnification_level is 8192 (farthest, or least magnification).

The following example sets the magnification level to 8:

https://waze.com/ul?z=8

Combine parameters

You can use the parameters together in the same URL by separating the name-value pairs with an "&". The following examples show how to use combinations of the parameters:

  • To center the map on Maryhill and zoom to 10:

    https://waze.com/ul?ll=45.6906304,-120.810983&z=10

  • To search for an address and then navigate to that address:

    https://waze.com/ul?q=66%20Acacia%20Avenue&ll=45.6906304,-120.810983&navigate=yes

Include utm_source

If you include a utm_source in your implementation, we can associate usage with particular partners. If an issue occurs that impacts the integration, the utm_source lets us follow up with the partner and provide them with a better partner experience. For more details, see the iOS example. If you run into any issues, feel free to reach out to us.

Examples

This section provides examples of how to use the Waze Deep Links API on the Android and iOS platforms.

Android example

The following code snippet example launches Waze to look for the specified location, if Waze is installed. If Waze isn't installed, it opens the Waze page in Google Play:

try {
  // Launch Waze to look for Hawaii:
  String url = "https://waze.com/ul?q=Hawaii";
  Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url));
  startActivity(intent);
} catch (ActivityNotFoundException ex) {
  // If Waze is not installed, open it in Google Play:
  Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=com.waze"));
  startActivity(intent);
}

iOS example

The following code snippet example navigates to lat/lon if Waze is installed; otherwise, it launches the App Store to install Waze:

- (void) navigateToLatitude:(double)latitude longitude:(double)longitude
{
  if ([[UIApplication sharedApplication]
    canOpenURL:[NSURL URLWithString:@"waze://"]]) {
      NSString *bundleIdentifier = NSBundle.mainBundle.bundleIdentifier;
      // Waze is installed. Launch Waze and start navigation
      NSString *urlStr =
        [NSString stringWithFormat:@"https://waze.com/ul?ll=%f,%f&navigate=yes&utm_source=%s",
        latitude, longitude, bundleIdentifier];
      [[UIApplication sharedApplication] openURL:[NSURL URLWithString:urlStr]];
  } else {
    // Waze is not installed. Launch AppStore to install Waze app
    [[UIApplication sharedApplication] openURL:[NSURL
      URLWithString:@"http://itunes.apple.com/us/app/id323229106"]];
  }
}

When you compile with iOS SDK 9.0 and later, you must update your application's property list file with the following to include Waze:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>waze</string>
</array>