Google Maps for Android Automotive Intents

Disclaimer

This product/feature will change and is not subject to any service level agreement (SLA) or deprecation policy. The implementation is subject to change in future releases.

Regarding sample software, data files, and/or source code that accompany this documentation: This product is provided "as is" and without warranty of any kind, and Google expressly disclaims any and all warranties, whether express, implied, statutory or otherwise, including without limitation warranties of merchantability, fitness for a particular purpose and noninfringement of any rights relating to this product.

Through Android Automotive intents, you can launch navigation in Google Maps.

For more information, see Google Maps Intents for Android.

For more information about bringing your app to vehicles running either Android Auto or Android Automotive OS, see Android for Cars.

Overview

This page describes the intents you can use with Google Maps for Android Automotive. For detailed Android developer documentation, read:

Intent requests

To launch Google Maps for Android Automotive with an intent, you must first create an Intent object, specifying its action, URI and package.

  • Action. All Google Maps intents are called as a View action, ACTION_VIEW.

  • URI. Google Maps intents use URI encoded strings that specify a desired action, along with some data with which to perform the action.

  • Package. Calling setPackage("com.google.android.apps.maps") ensures that the Google Maps app for Android handles the Intent. If the package isn't set, the system determines which apps can handle the Intent. If multiple apps are available, you may be asked which app you would like to use.

After creating the Intent, you can request that the system launch the related app in a number of ways. A common method is to pass the Intent to the [startActivity()] method. The system will launch the necessary app, in this case, Google Maps, and start the corresponding Activity.

// Create a Uri from an intent string. Use the result to create an Intent.
Uri mapIntentUri =
Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
// Create an Intent from mapIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

If the system can't identify an app that can respond to the Intent, your app may crash. For this reason, first verify that a receiving application is installed before you present one of these intents to a user.

To verify that an app is available to receive the intent, call [resolveActivity()] on your [Intent] object. If the result is non-null, there is at least one app that can handle the intent and it's safe to call [startActivity()]. If the result is null, you should not use the intent and, if possible, disable the feature that invokes the intent.

if (mapIntent.resolveActivity(getPackageManager()) != null) {
...
}

For example, to launch turn-by-turn navigation to Taronga Zoo in Sydney, you can use the following code:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
startActivity(mapIntent);
}

URI encoded query strings

All strings passed to the Google Maps Intents must be URI encoded. For example, the string "1st & Pike, Seattle" should become 1st%20%26%20Pike%2C%20Seattle. Spaces in the string can be encoded with %20 or replaced with the plus sign (+).

You can use the android.net.Uri parse() method to encode your strings. For example:

Uri mapIntentUri = Uri.parse("google.navigation:q=" + Uri.encode("1st & Pike, Seattle"));

Launch turn-by-turn navigation

Use this intent to launch Google Maps navigation with turn-by-turn directions to one or several addresses or coordinates specified. Directions are always given from the user’s current location.

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude
google.navigation:place=placename

Parameters

To launch navigation, use place or q with waypoints, which is optional. To optionally mark a waypoint as a charging station, see Send an electric vehicle trip plan to Google Maps.

  • q sets the end point for navigation searches. This can be a latitude/longitude or a query formatted address. If it is a query string that returns more than one result, the first result will be selected.

  • place sets the endpoint to home or work. Specify home to navigate to the user's home, and work to navigate to the user's workplace.

  • avoid sets features the route should try to avoid. avoid is optional and can be set to one or more of:

    • t for tolls
    • h for highways
    • f for ferries

  • waypoints specifies one or more intermediary places to route directions to the final destination specified by q. You can specify multiple waypoints by using the pipe character (|) to separate places -- for example, Berlin,Germany|Paris,France. You can use as many waypoints as needed. The waypoints will be added to the route in the same order that they are listed in the URL. Each waypoint can either be an address or comma-separated latitude/longitude coordinates; and, you can have addresses and lat/long coordinates in the same intent. Strings should be URL-escaped, so waypoints like "Berlin,Germany|Paris,France" should be converted to Berlin%2CGermany%7CParis%2CFrance.

Examples

This Intent will request turn-by-turn navigation to Taronga Zoo, in Sydney Australia:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

If you prefer not to pay tolls or ride a ferry, you can request routing that tries to avoid these situations:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Or if you'd rather navigate to your home, use:

Uri mapIntentUri = Uri.parse("google.navigation:place=home");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

To launch turn-by-turn navigation to the following three addresses in order, pass Taronga Zoo as the final destination q, and Google Sydney and Sydney Opera House as the waypoints:

  1. Google Sydney

  2. Sydney Opera House

  3. Taronga Zoo, Sydney Australia

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7CSydney+Opera+House");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Similar to q, you can represent any of the waypoints by a comma-separated latitude and longitude instead of an address. For example, to launch the same navigation while passing latitude longitude for Sydney Opera House instead of the address:

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7C-33.856159,151.215256");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Send an electric vehicle trip plan to Google Maps

Use this multi-destination navigation intent to specify some destinations as electric vehicle (EV) charging stops. This intent, which extends the multi-waypoint intent, helps drivers maintain sufficient electric vehicle battery charge to reach their destinations by syncing charging stop information between EV trip planning apps and Google Maps.

For charging stops, trip intents:

  • Must contain name and lat-long
  • May optionally contain power output, to be used for calculating charging time

Google uses the charging station name and lat-long to find a matching charging station place to display rich data like connector types, totals, speeds and real-time availability, supported payment methods, and host points of interest (POI). For example, driving directions within outdoor parking lots for the final part of the navigation, opening hours, ratings. To ensure that charging stations match well to Google data, use <brand name>, for example ChargePoint.

Parameters

Final destination

To set a charging station as the final destination, use:

  • q: Must contain the lat-long value of the charging station.
  • q_type: 1 specifies that the final destination is a charging station.
  • q_name: The name of the final destination. Required if q_type is 1.
  • q_power_output_kw: A double number for charging station power output in kilowatts. Optional.

Waypoints

For waypoints, all of the parameters are parallel, |-separated arrays of values in the same order as waypoints, not including final destination. A mismatch in the number of elements in parallel arrays is treated as a malformed intent.

To add one or more charging stations waypoints, use the following parameters, all of which are optional. If one of the destinations is marked as a charging station, then the waypoint name becomes mandatory for that destination.

  • waypoints: List of waypoints as described in the turn-by-turn navigation intent. Must be a lat-long value for charging station waypoints.

  • waypoint_types: Types per waypoint specified as a number. 0 is any stop (default value) and 1 is the charging station.

  • waypoint_names: Waypoint names. This field is mandatory for charging stations.

  • waypoint_power_outputs_kw: Double numbers for charging station power in kilowatts. For charging stations, you can optionally specify a waypoint power output value, which is used as a fallback if the matching station is not found. Empty slot means no value is provided.

User experience (UX) behavior

For trip intents with multiple destinations, the route overview screen is displayed, but the navigation doesn't start automatically.

For a correctly formatted intent, Google Maps will present a route overview screen for the trip. The route overview screen will display all waypoints and the final destination from the intent, with charging recommendations where applicable.

For any waypoints or final destination marked as a charging station, Google Maps will search for a matching place in Google’s database.

Where a match is found, Google Maps uses Google data to display the charging station in the user interface (UI) and provide a charging recommendation for the charging station. If the match is not found, data provided in the intent for a charging station (lat-long, name and power output) will be used to display this charging station in the UI and provide a charging recommendation at this charging station.

Examples

Navigate to a final destination via multiple charging stations

The following intent navigates to the final destination, Port Macquarie NSW, via two charging stations, ChargePoint and Evie.

Destinations in order:

  1. ChargePoint Charging Station (location: -32.9599188,151.6240806, power output: 6.6kw)

  2. Evie Charging Station (location: -31.9432539,152.4699808, power output: 350kw)

  3. Port Macquarie NSW

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806%7C-31.9432539%2C152.4699808"
            + "&waypoint_types=1%7C1"
            + "&waypoint_names=ChargePoint+Charging+Station%7CEvie+Charging+Station"
            + "&waypoint_power_outputs_kw=6.6%7C350");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Unknown power output

If power output value is unknown leave the relevant slot of waypoint_power_outputs_kw empty. Or if all slots are empty, there is no need to specify the waypoint_power_outputs_kw parameter.

Destinations in order:

  1. ChargePoint Charging Station (location: -32.9599188,151.6240806, power output: unknown)

  2. Port Macquarie NSW

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806"
            + "&waypoint_types=1"
            + "&waypoint_names=ChargePoint+Charging+Station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

Mark final destination as a charging station

To mark the final destination as a charging station, specify q_type, q_name and q_power_output_kw parameters.

Destinations in order:

  1. Taronga Zoo, Sydney Australia

  2. ChargePoint Charging Station (location: -32.9599188,151.6240806, power output: unknown)

  3. Evie Charging Station (location: -31.9432539,152.4699808, power output: 350kw)

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=-31.9432539,152.4699808&q_type=1&q_name=Evie+Charging+Station&q_power_output_kw=350"
            + "&waypoints=Taronga+Zoo%2C+Sydney+Australia%7C-32.9599188%2C151.6240806"
            + "&waypoint_types=0%7C1"
            + "&waypoint_names=%7CChargePoint+Charging+Station"
            + "&waypoint_power_outputs_kw=%7C");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);