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.

Sapanesh/HNKGooglePlacesAutocomplete