Home

Awesome

OpenInGoogleMaps-iOS is Deprecated

This library was created to handle a the use case of opening the correct app to show a Map, Street View, or Directions. At Google I/O 2017 we announced a better, cross platform, approach to handling this requirement - Maps URLs.

Using Maps URLs, you can build a universal, cross-platform URL to launch Google Maps and perform searches, get directions and navigation, and display map views and panoramic images. The URL syntax is the same regardless of the platform in use.

OpenInGoogleMapsController

The OpenInGoogleMapsController class is designed to make it easy for an iOS developer to open a map, show a Street View location, or show a set of directions directly in Google Maps. The class supports using the x-callback-URL standard so that you can add a "Back to my app" button directly within Google Maps, and supports a number of fallback strategies, so that you can automatically open the map in another application if the user does not have Google Maps installed. Analytics

About the Google Maps URL Scheme

The OpenInGoogleMapsController class makes use of the Google Maps URL Scheme. If you want to understand how the class works under the hood, we highly recommend reading the URL Scheme documentation first.

Installing OpenInGoogleMapsController

You can download the OpenInGoogleMapsController class, along with a sample app demonstrating its use, from the OpenInGoogleMaps Github page.

To add the class to your Xcode project, simply drag the OpenInGoogleMapsController .m and .h files into Xcode. Make sure you call #import OpenInGoogleMapsController.h where necessary.

Alternately, if you want to use CocoaPods in your project, you can install the necessary files by adding the following line to your Podfile:

pod "OpenInGoogleMaps"

Running the Sample Application

If you would like to try out the sample application, open OpenInGoogleMapsSample.xcodeproj in Xcode. You will probably want to run this on a real device, as the simulator does not have Google Maps installed.

Using OpenInGoogleMapsController

OpenInGoogleMapsController is a singleton class, which you can reference by calling the sharedInstance class method.

[[OpenInGoogleMapsController sharedInstance] <make calls here>]

Supporting iOS 9

In iOS 9.0, further restrictions were placed on the canOpenURL method -- for this method to work, you will need to add a LSApplicationQueriesSchemes array to your app's info.plist file, and then add items for each URL scheme you will want to query. For OpenInGoogleMapsController, these schemes as comgooglemaps, comgooglemaps-x-callback, and your own app's custom URL scheme.

Please see the sample application for an example of this info.plist file in action.

Adding a Callback URL

Google Maps and Google Chrome both support the x-callback-URL specification, which allows you to easily add a "Back to my app" button in Google Maps. To add a callback url:

  1. Within your Xcode project, select your target, and then select Info -> URL Types

  2. Add a URLType for your application. This string should be unique for your app. Many developers choose to use their bundle identifier, without the periods (comgooglemyapp, for instance).

  3. Set the callbackURL property in your OpenInGoogleMapsController class.

     NSString myURLScheme = @"comexamplemyapp://";
 NSURL myCallbackURL = [NSURL URLWithString:myURLScheme];
 [OpenInGoogleMapsController sharedInstance].callbackURL = myCallbackURL;

When you open your maps now in Google Maps (or Google Chrome), you should see a button that redirects users back to your app when they're done viewing the map.

You only need to set the callback URL once during the lifetime of your application and it will be used in all future OpenInGoogleMapsController requests.

Fallback Strategies

If the user does not have Google Maps installed, you can specify a number of fallback strategies for OpenInGoogleMapsController to try by setting the fallbackStrategy property.

[OpenInGoogleMapsController sharedInstance].fallbackStrategy =
	kGoogleMapsFallbackChromeThenAppleMaps;

The fallback strategies you can try are as follows:

If you have specified a callback URL, it will also be passed to Google Chrome.

You only need to set the fallback strategy once during the lifetime of your application and it will be used in all future OpenInGoogleMapsController requests.

Detecting if Google Maps is installed

If you want to manually detect if Google Maps is installed, you can use the isGoogleMapsInstalled property.

BOOL isGoogleMapsInstalled = [OpenInGoogleMapsController sharedInstance].isGoogleMapsInstalled;

Opening a map

Opening a map requires first creating a GoogleMapDefinition object to define the map you want opened. You can then pass the definition object to the openMap method. This method will return YES if it was able to open the map in some application, and NO if it was unable to open a map, either because you didn't define anything to search for, or your user does not have Google Maps installed and you did not specify a fallback strategy.

GoogleMapDefinition *definition = [[GoogleMapDefinition alloc] init];
// Steps to define the definition.
[[OpenInGoogleMapsController sharedInstance] openMap:definition];

GoogleMapDefinition

The GoogleMapDefinition class includes several properties, some of which may be set to nil:

Here's an example that opens up a map for "123 Main Street, Anytown, CA" with the "traffic" and "satellite" map layers turned on.

GoogleMapDefinition *definition = [[GoogleMapDefinition alloc] init];
definition.queryString = @"123 Main Street, Anytown, CA";
definition.viewOptions = kGoogleMapsViewOptionSatellite | kGoogleMapsViewOptionTraffic;
[[OpenInGoogleMapsController sharedInstance] openMap:definition];

Opening a street view location

Opening a Street View location requires creating a GoogleStreetViewDefinition class to define the location you want to open. You can then pass this definition to the openStreetView method. This method will return YES if it was able to open the Street View request in some application, and NO if it was not, either because you didn't define a set of coordinates, or your user does not have Google Maps installed and you did not specify a fallback strategy.

Note that a YES value does not actually guarantee the coordinates you specified were a valid Street View location.

If your fallback strategy involves an app that does not support Street View, the OpenInGoogleMapsController class will open a zoomed-in satellite view on a map instead.

Here's an example that opens up a Street View location near the Taj Mahal.

GoogleStreetViewDefinition *definition = [[GoogleStreetViewDefinition alloc] init];
definition.center = CLLocationCoordinate2DMake(27.1724439,78.0420174);
[[OpenInGoogleMapsController sharedInstance] openStreetView:definition];

GoogleStreetViewDefinition

The GoogleStreetViewDefinition class includes one property:

Opening directions

Opening a set of directions in Google Maps requires creating a GoogleDirectionsDefinition class to define the set of points you want to travel between. You can then pass this definition to the openStreetView method. This method will return YES if it was able to open the set of directions in some application, and NO if it was unable to, either because both your start and end point were empty, or your user does not have Google Maps installed and you did not specify a fallback strategy.

Note that a YES value does not guarantee that Google Maps (or the fallback application) was able to find a set of directions between these two points:

GoogleDirectionsWaypoint

The GoogleDirectionsDefinition class uses the GoogleDirectionsWaypoint class to define its start and end points for a direction request. This class includes these properties:

If both of these values are set, the location takes precedence over the query string.

The GoogleDirectionsWaypoint class also has two class helper methods: + waypointWithQuery:(NSString *)queryString and + waypointWithLocation:(CLLocationCoordinate2D)location to easily construct waypoints.

GoogleDirectionsDefinition

The GoogleDirectionsDefinition class includes these properties:

The following example will help you plan your next burrito-centric road trip:

GoogleDirectionsDefinition *definition = [[GoogleDirectionsDefinition alloc] init];
definition.startingPoint = [GoogleDirectionsWaypoint
    waypointWithQuery:@"La Taqueria, 2889 Mission St San Francisco, CA 94110"];
definition.destinationPoint = [GoogleDirectionsWaypoint
    waypointWithQuery:@"Delicious Mexican Eatery, 3314 Fort Blvd, El Paso, TX 79930"];
definition.travelMode = kGoogleMapsTravelModeDriving;
[[OpenInGoogleMapsController sharedInstance] openDirections:definition];

The following example will give you biking directions from MI6 headquarters to Sherlock Holmes' address:

GoogleDirectionsDefinition *definition = [[GoogleDirectionsDefinition alloc] init];
definition.startingPoint = [GoogleDirectionsWaypoint
                            waypointWithLocation:CLLocationCoordinate2DMake(51.487242,-0.124402)];
definition.destinationPoint = [GoogleDirectionsWaypoint
                               waypointWithQuery:@"221B Baker Street, London"];
definition.travelMode = kGoogleMapsTravelModeBiking;
[[OpenInGoogleMapsController sharedInstance] openDirections:definition];

The following example will give you walking directions from your current location to the North American International Auto Show:

GoogleDirectionsDefinition *definition = [[GoogleDirectionsDefinition alloc] init];
definition.startingPoint = nil;
GoogleDirectionsWaypoint *destination = [[GoogleDirectionsWaypoint alloc] init];
destination.queryString = @"1 Washington Blvd, Detroit, MI 48226";
definition.destinationPoint = destination;
definition.travelMode = kGoogleMapsTravelModeWalking;
[[OpenInGoogleMapsController sharedInstance] openDirections:definition];

Reference Documentation

You can find the reference documentation in the Docs/html/ folder or online. It makes for some thrilling late-night reading.

Special Thanks

Special thanks go out to Ian Barber, Leo Hourvitz, and Sam Thorogood, for thoroughly reviewing this code. Any remaining mistakes are the author's.

Safari is a registered trademark of Apple Inc.

Reference documentation was generated by appledoc.