An Objective-C wrapper for the Google Places Autocomplete API
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
- 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.
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.
- 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
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.
pod "HNKGooglePlacesAutocomplete", "~> 1.1"The models present in HNKGooglePlacesAutocomplete directly reflect the objects provided by the Google Places Autocomplete API - review that documentation to get a full picture of what data is provided by a Place.
Bear in mind that the CLPlacemark convenience method can also be used to obtain additional location-related information.
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
HNKGooglePlacesAutocomplete makes use of the CoreLocation framework. Make sure this framework is added in your Xcode settings.
These classes form the core functionality of HNKGooglePlacesAutocomplete
HNKGooglePlacesAutocompletePlaceQuery- used to query the API for Place suggestionsHNKGooglePlacesAutocompletePlace- Place object returned from a Query
CLPlacemark+HNKAdditions.h- provides translation fromHNKGooglePlacesAutocompletePlacetoCLPlacemark
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):
[HNKGooglePlacesAutocompleteQuery setupSharedQueryWithAPIKey:@"YOUR_API_KEY"];You should replace YOUR_API_KEY with your Google Places API key.
HNKGooglePlacesAutocompleteQuery is responsible for handling queries for Places. Once Setup is complete, queries can be made to [HNKGooglePlacesAutocopmleteQuery sharedQuery].
[[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.
HNKGooglePlacesAutocompletePlace objects are returned from Queries and represent the suggested Places for that Query.
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:
[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
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 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.
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 Francefilter- anHNKGooglePlacesTypeAutocompleteFiltervalue that restricts results to specific Place Typeslanguage- the language in which results should be expressed; must be one of Google's supported domain languageslatitude&longitude- the location to which results should be biasedoffset- how many characters are used in the requestsearchRadius- the distance in meters within which to bias results
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:.
Every HNKGooglePlacesAutocompleteQuery has a configuration whether one is explicitly supplied or not.
The default configuration values are:
country=nilfilter=HNKGooglePlacesTypeAutocompleteFilterAlllanguage=nillatitudeandlongitude=0(Google's way of indicating no location bias)offset=NSNotFoundsearchRadius=20000000(Google's way of indicating no specific search radius)
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.
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.
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".
HNKGooglePlacesAutocomplete was created by Harlan Kellaway. It was inspired by SPGooglePlacesAutocomplete.
Thanks to all contributors 🎉
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.
