Google Maps SDK for iOS

Google Maps URL Scheme

You can use the a Google Maps URL scheme to launch the Google Maps app for iOS and perform searches, get direction requests, and display map views. When you launch Google Maps your bundle identifier is automatically sent as part of the request.

Overview

A URL scheme allows you to launch a native iOS application from another iOS app or a web application. You can set options in the URL that will be passed to the launched application. The Google Maps for iOS app supports two different URL Schemes: comgooglemaps:// and comgooglemaps-x-callback://. Both schemes allow you to launch the Google Maps iOS Application, and perform one of several actions:

  1. Display a map at a specified location and zoom level.
  2. Search for locations or places, and display them on a map.
  3. Request directions from one location to another. Directions can be returned for four modes of transportation: driving, walking, bicycling and public transit.

With comgooglemaps-x-callback:// you are also able to issue a callback when the app has completed. Callbacks are often used to return a user to the app that originally opened Google Maps for iOS.

Google Maps URL Scheme Requests

A request to the Google Maps URL Scheme should be of the following form:

comgooglemaps://?parameters

Parameters are described in detail later in this document.

Before you present one of these URLs to a user in your app you should first verify that the application is installed. Your app can check that the URL scheme is available with the following code:

[[UIApplication sharedApplication] canOpenURL:
    [NSURL URLWithString:@"comgooglemaps://"]];

For example, to display a map of Central Park in New York, you can use the following code:

if ([[UIApplication sharedApplication] canOpenURL:
     [NSURL URLWithString:@"comgooglemaps://"]]) {
  [[UIApplication sharedApplication] openURL:
   [NSURL URLWithString:@"comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic"]];
} else {
  NSLog(@"Can't use comgooglemaps://");
}

Display a Map

Use the URL scheme to display the map at a specified zoom level and location. You can also overlay other views on top of your map, or display Street View imagery.

Parameters

All of the following parameters are optional. If no parameters are set, the URL scheme will simply launch the Google Maps for iOS app.

  • center: This is the map viewport center point. Formatted as a comma separated string of latitude,longitude.
  • mapmode: Sets the kind of map shown. Can be set to: standard or streetview. If not specified, the current application settings will be used.
  • views: Turns specific views on/off. Can be set to: satellite, traffic, or transit. Multiple values can be set using a comma-separator. If the parameter is specified with no value, then it will clear all views.
  • zoom: Specifies the zoom level of the map.

An example URL is below, which displays the map centered on New York at zoom 14 with the traffic view on:

comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic

New York traffic map

Some additional examples are below:

comgooglemaps://?center=37.788463,-122.392545&zoom=12
comgooglemaps://?center=46.414382,10.013988&mapmode=streetview

Use this scheme to display search queries in a specified viewport location.

Parameters

In addition to the parameters used to display a map, Search supports the q parameter.

  • q: The query string for your search.

An example URL is below to search for “Pizza” around the specified location:

comgooglemaps://?q=Pizza&center=37.759748,-122.427135

Nearby Pizza

Some additional examples are below:

comgooglemaps://?q=Steamers+Lane+Santa+Cruz,+CA&center=37.782652,-122.410126&views=satellite,traffic&zoom=15
comgooglemaps://?q=Google+Japan,+Minato,+Tokyo,+Japan&center=35.660888,139.73073&zoom=15&views=transit

Directions

Use this scheme to request and display directions between two locations. You can also specify the transportation mode.

Parameters

  • saddr: Sets the starting point for directions 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. If the value is left blank, then the user’s current location will be used.
  • daddr: Sets the end point for directions searches. Has the same format and behavior as saddr.
  • directionsmode: Method of transportation. Can be set to: driving, transit, bicycling or walking.

An example URL is below to display transit directions between Google NYC and JFK Airport:

comgooglemaps://?saddr=Google+Inc,+8th+Avenue,+New+York,+NY&daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York&directionsmode=transit

Transit directions

Some additional example are below:

comgooglemaps://?saddr=Google,+1600+Amphitheatre+Parkway,+Mountain+View,+CA+94043&daddr=Google+Inc,+345+Spear+Street,+San+Francisco,+CA&center=37.422185,-122.083898&zoom=10
comgooglemaps://?saddr=2025+Garcia+Ave,+Mountain+View,+CA,+USA&daddr=Google,+1600+Amphitheatre+Parkway,+Mountain+View,+CA,+United+States&center=37.423725,-122.0877&directionsmode=walking&zoom=17

Specify a callback URL

If you'd like to specify a callback URL, you will need to use the comgooglemaps-x-callback:// URL scheme. This scheme adheres to the x-callback-url specification. When you call the Google Maps for iOS app with this scheme, the app will display a button at the top of the screen. Tapping this button will issue a callback to a URL that you've specified.

x-callback requests

Requests to the comgooglemaps-x-callback:// must be of the form:

comgooglemaps-x-callback://?parameters

Parameters

The x-callback URL scheme accepts the same parameters as thecomgooglemaps:// URL scheme, with the following additional parameters. Both parameters are required.

  • x-source — The name of the application sending the x-callback request. Short names are preferred.
  • x-success — The URL to call when complete. Often this will be a URL scheme for your own app, allowing users to return to the original application.

The following example will launch the Google Maps for iOS app and display a map centered on New York. The app will also display a button labelled "SourceApp". When the "SourceApp" button is clicked, the Google Maps for iOS app will issue a callback to a fictitious URL scheme, sourceapp://?resume=true.

comgooglemaps-x-callback://?center=40.765819,-73.975866&zoom=14
   &x-success=sourceapp://?resume=true
   &x-source=SourceApp

As with the comgooglemaps:// URL scheme, you should first verify that the Google Maps for iOS application is available on the device, and supports the x-callback URL scheme. Your app can check that the URL scheme is available with the following code:

[[UIApplication sharedApplication] canOpenURL:
   [NSURL URLWithString:@"comgooglemaps-x-callback://"]];

Add a back button to Google Maps for iOS

With an x-callback URL, you can launch Google Maps for iOS and give your users a way to return to your app. Note that your app will have to register its own URL scheme so that it can respond to the callback URL. To add a back button:

  1. Ensure that your application has registered a URL scheme that can respond to the callback request.
  2. Pass the label for the button in the x-source parameter.
  3. Pass the callback URL in the x-success parameter.

An example of a URL that lets users return to an app after searching for dessert is shown below.

comgooglemaps-x-callback://?q=dessert&center=37.759748,-122.427135
   &x-success=sourceapp://?resume=true
   &x-source=Nom+Nom

Add navigation to your app

Launching Google Maps for iOS with a directions request is an easy way to give your users access to turn-by-turn navigation from your app. You can use either the comgooglemaps:// or comgooglemaps-x-callback:// URL schemes.

The below code snippet shows how to use the comgooglemaps-x-callback:// scheme to request directions, and then return to your app when your user is ready. The code will do the following:

  1. Verify that the comgooglemaps-x-callback:// URL scheme is available.
  2. Launch the Google Maps for iOS app, and request directions to JFK Airport in New York city. Leave the start address blank to request directions from the user's current location.
  3. Add a button labelled "AirApp" to the Google Maps for iOS App. The button label is defined by the x-source parameter.
  4. Call the fictitious URL scheme, sourceapp://, when the users clicks the back button.

The code is shown below.

NSURL *testURL = [NSURL URLWithString:@"comgooglemaps-x-callback://"];
if ([[UIApplication sharedApplication] canOpenURL:testURL]) {
  NSString *directionsRequest = @"comgooglemaps-x-callback://" +
      @"?daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York" +
      @"&x-success=sourceapp://?resume=true&x-source=AirApp";
  NSURL *directionsURL = [NSURL URLWithString:directionsRequest];
  [[UIApplication sharedApplication] openURL:directionsURL];
} else {
  NSLog(@"Can't use comgooglemaps-x-callback:// on this device.");
}

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.