OCGoogleDirectionsAPI

A lightweight wrapper for The Google Directions API. See the Google Maps API Web Services documentation.

As Google wrote: "The Google Directions API is a service that calculates directions between locations using an HTTP request. You can search for directions for several modes of transportation, include transit, driving, walking or cycling. Directions may specify origins, destinations and waypoints either as text strings (e.g. "Chicago, IL" or "Darwin, NT, Australia") or as latitude/longitude coordinates. The Directions API can return multi-part directions using a series of waypoints."

0.1.7

The OCGoogleDirectionsAPI library allows your iOS apps to deal with this powerful service easily. IMPORTANT: It uses NSURLSession only available in iOS 7.0+. It is not compatible with iOS 6.x and lower.

Installation with CocoaPods

CocoaPods is the dependency manager for Objective-C projects. It has thousands of libraries and can help you scale your projects elegantly.

Podfile

platform :ios, '7.0'
pod "OCGoogleDirectionsAPI", "~> 0.1.7"

How to get started

It's really simple. To get directions you need to do 4 easy steps.

1. Importing headers. From now all OCDirections* general classes will be accessible for you.

   #import <OCGoogleDirectionsAPI/OCGoogleDirectionsAPI.h>

2. Secondly you can provide your Google API Key. The method application:didFinishLaunchingWithOptions: in AppDelegate seams to be a good place for this code. However the API Key is now optional. Please check API Key section to decide if you need the key or not.

   [OCDirectionsAPIClient provideAPIKey:@"<YOUR API KEY>"];

3. Prepare a OCDirectionsRequest object to specify route(s) you want to retrieve from the service.

   OCDirectionsRequest *request = [OCDirectionsRequest requestWithOriginString:@"<ORIGIN>" andDestinationString:@"<DESTINATION>"];

4. Create an instance of OCDirectionsAPIClient and call directions:response: method to retrieve required data (OCDirectionsResponse) asynchronously.

   OCDirectionsAPIClient *client = [OCDirectionsAPIClient new];
   [client directions:request response:^(OCDirectionsResponse *response, NSError *error) {
   
        // e.g.
        if (error) {
            return;
        }
        if (response.status != OCDirectionsResponseStatusOK) {
            return
        }
   
        // some code
   }];

Alternatively you can use - (NSURLSessionDataTask *)dataTaskWithRequest:response: factory method to have full control over NSURLSessionDataTask object. It might be especially useful when you need to cancel download operation. After creating instance of NSURLSessionDataTask you need to remember to call resume method to start retrieving data.

Some init methods of OCDirectionsAPIClient:

 - (instancetype)initWithKey:(NSString *)key;

 - (instancetype)initWithNoKeyUseHttps:(BOOL)useHttps;

 - (instancetype)initWithKey:(NSString *)key useHttps:(BOOL)https;

Sequence diagram

That's all! It's quite easy, isn't it? If you like to know a bit more about requests please read the next section OCDirectionsRequest.

OCDirectionsRequest

Creating an instance

To create an isntance of OCDirectionsRequest you can use one of the following factory methods.

+ (instancetype)requestWithOriginLocation:(CLLocation *)origin andDestinationLocation:(CLLocation *)destination;

+ (instancetype)requestWithOriginString:(NSString *)origin andDestinationLocation:(CLLocation *)destination;

+ (instancetype)requestWithOriginLocation:(CLLocation *)origin andDestinationString:(NSString *)destination;

+ (instancetype)requestWithOriginString:(NSString *)origin andDestinationString:(NSString *)destination;

Request attributes

To read more about available attributes please see the Request parameters page.

Alternatives

[request setAlternatives:YES];

Region

[request setRegion:@"pl"];

Language

[request setLanguage:@"pl"];

Here you can find the list of supported languages: https://developers.google.com/maps/faq#languagesupport

Restrictions

There are 3 different restrictions:

• OCDirectionsRequestRestrictionAvoidTolls
• OCDirectionsRequestRestrictionAvoidHighways
• OCDirectionsRequestRestrictionAvoidFerries

You can ask to avoid one or even all of them by calling the setRestrictions: method.

[request setRestrictions:@[@(OCDirectionsRequestRestrictionAvoidTolls), @(OCDirectionsRequestRestrictionAviodFerries)];

Travel mode

The API allows to choose one of the following travel modes:

• OCDirectionsRequestTravelModeDriving
• OCDirectionsRequestTravelModeWalking
• OCDirectionsRequestTravelModeBicycling
• OCDirectionsRequestTravelModeTransit

[request setTravelMode:OCDirectionsRequestTravelModeBicycling];

Unit

Available units:

• OCDirectionsRequestUnitDefault
• OCDirectionsRequestUnitMetric
• OCDirectionsRequestUnitImperia

[request setUnit:OCDirectionsRequestUnitMetric];

Waypoints

You need to set NSArray of NSString and CLLocation objects.

CLLocation *firstLocation = [[CLLocation alloc] initWithLatitude:51.2314 longitude:21.3243];
CLLocation *secondLocation = [[CLLocation alloc] initWithLatitude:51.1314 longitude:21.1321];
[request setWaypoints:@[@"London", firstLocation, "Reading", secondLocation]];

Waypoints optimise

[request setWaypointsOptimise:YES];

Traffic model

[request setTrafficModel:OCDirectionsRequestTrafficModelOptimistic];

Transit mode

[request setTransitMode:OCDirectionsRequestTransitModeBus | OCDirectionsRequestTransitModeTrain];

Transit routing preference

[request setTransitRoutingPreference:OCDirectionsRequestTransitRoutingPreferenceFewerTransfers];

Response

Classes:

• OCDirectionsResponse
• OCDirectionsResponseStatus
• OCDirectionsRoute
• OCDirectionsLeg
• OCDirectionsPolyline
• OCDirectionsBounds
• OCDirectionsDistance
• OCDirectionsDuration
• OCDirectionsStep
• OCDirectionsWaypoint
• OCDirectionsFare

OCDirectionsResponse

Properties:

• dictionary NSDictionary*
• status OCDirectionsResponseStatus
• routes NSArray* (array of OCDirectionsRoute*)
• errorMessage NSString*
• route NSDirectionsRoute*

Be aware that geocoded_waypoints property is not supported in the current version (#8).

OCDirectionsResponseStatus

Enum:

• OCDirectionsResponseStatusNotInitialized
• OCDirectionsResponseStatusOK
• OCDirectionsResponseStatusNotFound
• OCDirectionsResponseStatusZeroResults
• OCDirectionsResponseStatusMaxWaypointsExceeded
• OCDirectionsResponseStatusInvalidRequest
• OCDirectionsResponseStatusOverQueryLimit
• OCDirectionsResponseStatusRequestDenied
• OCDirectionsResponseStatusUnknownError

OCDirectionsRoute

Properties:

• dictionary NSDictionary*
• legs NSArray* (array of OCDirectionsLeg*)
• copyrights NSString*
• warnings NSArray* (array of NSString*)
• waypointOrder NSArray* (array of NSNumber*)
• overviewPolyline OCDirectionsPolyline*
• bounds OCDirectionsBounds*
• summary NSString*

OCDirectionsLeg

Properties:

• dictionary NSDictionary*
• distance OCDirectionsDistance*
• duration OCDirectionsDuration*
• durationInTraffic OCDirectionsDuration*
• endAddress NSString*
• endLocation OCLocationCoordinate2D
• startAddress NSString*
• startLocation OCLocationCoordinate2D
• steps NSArray* (array of OCDirectionsStep*)
• viaWaypoint NSArray* (array of OCDirectionsWaypoint*)

OCDirectionsPolyline

Properties:

• dictionary NSDictionary*
• points NSString*

OCDirectionsBounds

Properties:

• dictionary NSDictionary*
• southwest CLLocationCoordinate2D
• northeast CLLocationCoordinate2D

OCDirectionsDistance

Properties:

• dictionary NSDictionary*
• text NSString*
• value NSNumber*

OCDirectionsDuration

Properties:

• dictionary NSDictionary*
• text NSString*
• value NSNumber*

OCDirectionsStep

Properties:

• dictionary NSDictionary*
• distance OCDirectionsDistance*
• duration OCDirectionsDuration*
• endLocation CLLocationCoordinate2D
• htmlInstructions NSString*
• maneuver NSString*
• polyline OCDirectionsPolyline*
• startLocation CLLocationCoordinate2D
• travelMode OCDirectionsRequestTravelMode

OCDirectionsWaypoint

Properties:

• dictionary NSDictionary*
• location CLLocationCoordinate2D
• stepIndex NSNumber*
• stepInterpolation NSNumber*

OCDirectionsFare

Properties:

• dictionary NSDictionary*
• currency NSString*
• text NSString*
• value NSNumber*

Contact

Did you find a bug? Do you have great ideas how to make the library better? or you just want to say hello:) ... drop me a line on twitter @marciniwanicki.

TODO

• Add samples.
• Write unit tests.
• Implement releasing dictionary object when the response tree is fully initialised.

License

OCGoogleDirectionsAPI is available under the MIT license. See the LICENSE file for more info.