HNKGooglePlacesAutocomplete

An Objective-C wrapper for the Google Places Autocomplete API

Background

HNKGooglePlacesAutocomplete is an Objective-C wrapper for the Google Places Autocomplete API. It encapsulates the same core functionality as SPGooglePlacesAutocomplete - autocomplete suggestions and Google Place-to-CLPlacemark translation - with the intention of modernizing the approach.

Improvements include:

• Modern, vetted pods utilized (AFNetworking, Mantle)
• Code is well-tested using Kiwi
• Documentation is thorough
• Designed for reusability and dissemination with Cocoapods

Communication

• If you have found a bug, and can provide steps to reliably reproduce it, open an issue.
• If you have a feature request, open an issue.
• If you want to contribute, submit a pull request. Pull request should be made against the develop branch.

Dependencies

Mantle

As of version 1.1, HNKGooglePlacesAutocomplete uses Mantle 2.0. If you require Mantle 1.x, version 1.0.1 can be used - however, note that that only version 1.1+ will incorporate new updates.

Getting Started

• Download HNKGooglePlacesAutocomplete and try out the included iOS example app
• Check out the documentation for a more comprehensive look at the classes available in HNKGooglePlacesAutocomplete

Installation with CocoaPods

CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries like HNKGooglePlacesAutocomplete in your projects. Cocoapods is the preferred way to incorporate HNKGooglePlacesAutocomplete in your project; if you are unfamiliar with how to install Cocoapods or how create a Podfile, there are many tutorials online.

Podfile

pod "HNKGooglePlacesAutocomplete", "~> 1.1"

API Key

HNKGooglePlacesAutocomplete uses the Google Places Autocomplete API. You will need an API key for this service in order to use HNKGooglePlacesAutocomplete.

• Create a Google Developer account
• Create a new Project
• Turn on the Google Places API Web Service
• Find your API key in your Project's API Credentials

CoreLocation Framework

HNKGooglePlacesAutocomplete makes use of the CoreLocation framework. Make sure this framework is added in your Xcode settings.

Classes

Core Classes

These classes form the core functionality of HNKGooglePlacesAutocomplete

• HNKGooglePlacesAutocompletePlaceQuery - used to query the API for Place suggestions
• HNKGooglePlacesAutocompletePlace - Place object returned from a Query

Utilities

• CLPlacemark+HNKAdditions.h - provides translation from HNKGooglePlacesAutocompletePlace to CLPlacemark

Usage

Setup

Requests cannot be made without first supplying HNKGooglePlacesAutocomplete with your Google Places API Key (see API Key). Once your API key is obtained, you can setup HNKGooglePlacesAutocomplete for use by calling setupSharedQueryWithAPIKey: on HNKGooglePlacesAutocompleteQuery (typically within the AppDelegate):

setupSharedQueryWithAPIKey:

[HNKGooglePlacesAutocompleteQuery setupSharedQueryWithAPIKey:@"YOUR_API_KEY"];

You should replace YOUR_API_KEY with your Google Places API key.

Queries

HNKGooglePlacesAutocompleteQuery is responsible for handling queries for Places. Once Setup is complete, queries can be made to [HNKGooglePlacesAutocopmleteQuery sharedQuery].

fetchPlacesForSearchQuery:completion:

[[HNKGooglePlacesAutocompleteQuery sharedQuery] fetchPlacesForSearchQuery:@"Amoeba" 
	completion:^(NSArray *places, NSError *error)  {
    	if (error) {
        	NSLog(@"ERROR: %@", error);
    	} else {
        	for (HNKGooglePlacesAutocompletePlace *place in places) {
	        	NSLog(@"%@", place);
			}
    	}
    }
];

The completion block provides an array of HNKGooglePlaceAutcompletePlace objects when successful. If not successful, error information can be found in the error object.

Places

HNKGooglePlacesAutocompletePlace objects are returned from Queries and represent the suggested Places for that Query.

CLPlacemark from Place

HNKGooglePlacesAutocomplete comes with a category that facilitates translating HNKGooglePlacesAutocompletePlaces to CLPlacemarks - this is often used when placing pins on a Map. To translate a Place to a CLPlacemark, first include the proper header: #import "CLPlacemark+HNKAdditions.h". Then call as follows:

hnk_placemarkFromGooglePlace:apiKey:completion:

[CLPlacemark hnk_placemarkFromGooglePlace:place
	apiKey:YOUR_API_KEY
  	completion:^(CLPlacemark *placemark, NSString *addressString, NSError *error) {
    	if(error) {
    		NSLog(@"ERROR: %@", error);
    	} else {
    		NSLog(@"PLACEMARK: %@", placemark);
    	}
    }
];

You should replace YOUR_API_KEY with your Google Places API key; hnk_placemarkFromGooglePlace uses your API key to query the Google Place Details API if needed.

For convenience, the API key you provided HNKGooglePlacesAutocompleteQuery during setup is available as a property: [HNKGooglePlacesAutocompleteQuery sharedQuery].apiKey

Advanced Topics

The core functionality needed to use HNKGooglePlacesAutocomplete is described in Setup, Queries, Places, and CLPlacemark from Place. The following sections describe additional topics that may be of use in particular situations.

Errors

Errors returned by HNKGooglePlacesAutocomplete have a domain that starts with com.hnkgoogleplacesautocomplete.

A short description of the error can be found in the error object's localizedDescription property.

If the error has an underlying error, such as an error returned by CLGeocoder, it can be found in the error object's userInfo dictionary, via the NSUnderlyingError key.

Advanced Query Topics

Querying with Optional Parameters

Optional parameters can be used to restrict the results returned by the Google Places API in certain ways.

• HNKGooglePlacesAutocompleQueryConfig - object used to supply optional parameter values for requests

Configuration properties include:

• country - the country within which to restrict results; must be a a two character, ISO 3166-1 Alpha-2 compatible country code, such as "fr" for France
• filter - an HNKGooglePlacesTypeAutocompleteFilter value that restricts results to specific Place Types
• language - the language in which results should be expressed; must be one of Google's supported domain languages
• latitude & longitude - the location to which results should be biased
• offset - how many characters are used in the request
• searchRadius - the distance in meters within which to bias results

fetchPlacesForSearchQuery:configurationBlock:completion:

In addition to fetchPlacesForSearchQuery:completion:, HNKGooglePlacesAutocompleteQuery provides fetchPlacesForSearchQuery:configurationBlock:completion: to allow optional parameters to be applied to individual Queries.

[[HNKGooglePlacesAutocomplete sharedQuery] fetchPlacesForSearchQuery:@"Amo"
	configurationBlock:(HNKGooglePlacesAutocompleteQueryConfig *config) {
		config.country = @"fr";
        config.filter = HNKGooglePlaceTypeAutocompleteFilterCity;
        config.language = @"pt";
	}
	completion:^(NSArray *places, NSError *error)  { 
		// Completion here 
	}
];

Any or all of the Query Configuration properties can be set in the configurationBlock. If not set, default values will be used.

The example above specifies that the Places returned should be restricted to France, should be cities, and should be listed in Portuguese.

If a certain Query Configuration should be used for every query, then setup should include a Query Configuration, via setupSharedQueryWithAPIKey:configurationBlock:.

Default Query Configuration

Every HNKGooglePlacesAutocompleteQuery has a configuration whether one is explicitly supplied or not.

The default configuration values are:

• country = nil
• filter = HNKGooglePlacesTypeAutocompleteFilterAll
• language = nil
• latitude and longitude = 0 (Google's way of indicating no location bias)
• offset = NSNotFound
• searchRadius = 20000000 (Google's way of indicating no specific search radius)

Advanced Setup Topics

setupSharedQueryWithAPIKey:configurationBlock:

In addition to setupSharedQueryWithAPIKey:, HNKGooglePlacesAutocompleteQuery provides setupSharedQueryWithAPIKey:configurationBlock: to specify optional parameters to be applied to every Query.

[HNKGooglePlacesAutocompleteQuery setupSharedQueryWithAPIKey:@"YOUR_API_KEY"
	configurationBlock:(HNKGooglePlacesAutocompleteQueryConfig *config) {
		config.country = @"jp";
        config.filter = HNKGooglePlaceTypeAutocompleteFilterEstablishment;
        config.language = @"ru";
	}
];

The example above specifies that the Places returned from every Query should be restricted to Japan, should be business establishments, and should be listed in Russian.

Advanced Place Topics

Place Substrings

• HNKGooglePlacesAutocompletePlaceSubstring

HNKGooglePlacesAutocompletePlace objects have an array of substrings that describe the location of the entered term in the prediction result text - this is useful if the application is to highlight the user's query text in the result Place suggestions.

For example, if a user typed "Amoeba" and a resulting Place suggestion had a name of "Amoeba Music, Telegraph Avenue, Berkeley, CA, United States", the substrings array would contain one entry indicating that the phrase "Amoeba" was in that name from character 0 to 6.

Place Terms

• HNKGooglePlacesAutocompletePlaceTerm

HNKGooglePlacesAutocompletePlace objects have an array of terms that identify sections of the returned name.

For example, if a user types "Amoeba" and a resulting Place suggestion had a name of "Amoeba Music, Telegraph Avenue, Berkeley, CA, United States", the terms array would contain entries indicating that the name was composed of the terms "Amoeba Music", "Telegraph Avenue", "Berkeley", "CA", and "United States".

Credits

HNKGooglePlacesAutocomplete was created by Harlan Kellaway. It was inspired by SPGooglePlacesAutocomplete.

Thanks to all contributors 🎉

License & Terms

HNKGooglePlacesAutocomplete uses the Google Places API and is bound under Google's Places API Policies.

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