CLGeocoder Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CoreLocation.framework
Availability
Available in OS X v10.8 and later.
Companion guide
Declared in
CLGeocoder.h

Overview

The CLGeocoder class provides services for converting between a coordinate (specified as a latitude and longitude) and the user-friendly representation of that coordinate. A user-friendly representation of the coordinate typically consists of the street, city, state, and country information corresponding to the given location, but it may also contain a relevant point of interest, landmarks, or other identifying information. A geocoder object is a single-shot object that works with a network-based service to look up placemark information for its specified coordinate value.

To use a geocoder object, create it and call one of its forward- or reverse-geocoding methods to begin the request. Reverse-geocoding requests take a latitude and longitude value and find a user-readable address. Forward-geocoding requests take a user-readable address and find the corresponding latitude and longitude value. Forward-geocoding requests may also return additional information about the specified location, such as a point of interest or building at that location. For both types of request, the results are returned using a CLPlacemark object. In the case of forward-geocoding requests, multiple placemark objects may be returned if the provided information yielded multiple possible locations.

To make smart decisions about what types of information to return, the geocoder server uses all the information provided to it when processing the request. For example, if the user is moving quickly along a highway, it might return the name of the overall region, and not the name of a small park that the user is passing through.

Applications should be conscious of how they use geocoding. Geocoding requests are rate-limited for each app, so making too many requests in a short period of time may cause some of the requests to fail. (When the maximum rate is exceeded, the geocoder returns an error object with the value kCLErrorNetwork to the associated completion handler.) Here are some rules of thumb for using this class effectively:

The computer or device must have access to the network in order for the geocoder object to return detailed placemark information. Although, the geocoder stores enough information locally to report the localized country name and ISO country code for many locations. If country information is not available for a specific location, the geocoder may still report an error to your completion block.

You can use geocoder objects either in conjunction with, or independent of, the classes of the Map Kit framework.

Tasks

Reverse Geocoding a Location

Geocoding an Address

Managing Geocoding Requests

Properties

geocoding

A Boolean value indicating whether the receiver is in the middle of geocoding its value. (read-only)

@property (nonatomic, readonly, getter=isGeocoding) BOOL geocoding
Discussion

This property contains the value YES if the process is ongoing or NO if the process is done or has not yet been initiated.

Availability
  • Available in OS X v10.8 and later.
Declared In
CLGeocoder.h

Instance Methods

cancelGeocode

Cancels a pending geocoding request.

- (void)cancelGeocode
Discussion

You can use this method to cancel a pending request and free up the resources associated with that request. Canceling a pending request causes the completion handler block to be called.

If the request is not pending, because it has already returned or has not yet begun, this method does nothing.

Availability
  • Available in OS X v10.8 and later.
Declared In
CLGeocoder.h

geocodeAddressDictionary:completionHandler:

Submits a forward-geocoding request using the specified address dictionary.

- (void)geocodeAddressDictionary:(NSDictionary *)addressDictionary completionHandler:(CLGeocodeCompletionHandler)completionHandler
Parameters
addressDictionary

An Address Book dictionary containing information about the address to look up.

completionHandler

A block object containing the code to execute at the end of the request. This code is called whether the request is successful or unsuccessful.

Discussion

This method submits the specified location data to the geocoding server asynchronously and returns. Your completion handler block will be executed on the main thread. After initiating a forward-geocoding request, do not attempt to initiate another forward- or reverse-geocoding request.

Geocoding requests are rate-limited for each app, so making too many requests in a short period of time may cause some of the requests to fail. When the maximum rate is exceeded, the geocoder passes an error object with the value kCLErrorNetwork to your completion handler.

Availability
  • Available in OS X v10.8 and later.
Declared In
CLGeocoder.h

geocodeAddressString:completionHandler:

Submits a forward-geocoding request using the specified string.

- (void)geocodeAddressString:(NSString *)addressString completionHandler:(CLGeocodeCompletionHandler)completionHandler
Parameters
addressString

A string describing the location you want to look up. For example, you could specify the string “1 Infinite Loop, Cupertino, CA” to locate Apple headquarters.

completionHandler

A block object containing the code to execute at the end of the request. This code is called whether the request is successful or unsuccessful.

Discussion

This method submits the specified location data to the geocoding server asynchronously and returns. Your completion handler block will be executed on the main thread. After initiating a forward-geocoding request, do not attempt to initiate another forward- or reverse-geocoding request.

Geocoding requests are rate-limited for each app, so making too many requests in a short period of time may cause some of the requests to fail. When the maximum rate is exceeded, the geocoder passes an error object with the value kCLErrorNetwork to your completion handler.

Availability
  • Available in OS X v10.8 and later.
Declared In
CLGeocoder.h

geocodeAddressString:inRegion:completionHandler:

Submits a forward-geocoding request using the specified string and region information.

- (void)geocodeAddressString:(NSString *)addressString inRegion:(CLRegion *)region completionHandler:(CLGeocodeCompletionHandler)completionHandler
Parameters
addressString

A string describing the location you want to look up. For example, you could specify the string “1 Infinite Loop, Cupertino, CA” to locate Apple headquarters.

region

A geographical region to use as a hint when looking up the specified address. Specifying a region lets you prioritize the returned set of results to locations that are close to some specific geographical area, which is typically the user’s current location. If nil and the application is authorized for location services, the set of results is prioritized based on the user’s approximate location. Invoking this method does not trigger a location services authorization request.

completionHandler

A block object containing the code to execute at the end of the request. This code is called whether the request is successful or unsuccessful.

Discussion

This method submits the specified location data to the geocoding server asynchronously and returns. Your completion handler block will be executed on the main thread. After initiating a forward-geocoding request, do not attempt to initiate another forward- or reverse-geocoding request.

Geocoding requests are rate-limited for each app, so making too many requests in a short period of time may cause some of the requests to fail. When the maximum rate is exceeded, the geocoder passes an error object with the value kCLErrorNetwork to your completion handler.

Availability
  • Available in OS X v10.8 and later.
Declared In
CLGeocoder.h

reverseGeocodeLocation:completionHandler:

Submits a reverse-geocoding request for the specified location.

- (void)reverseGeocodeLocation:(CLLocation *)location completionHandler:(CLGeocodeCompletionHandler)completionHandler
Parameters
location

The location object containing the coordinate data to look up.

completionHandler

A block object containing the code to execute at the end of the request. This code is called whether the request is successful or unsuccessful.

Discussion

This method submits the specified location data to the geocoding server asynchronously and returns. Your completion handler block will be executed on the main thread. After initiating a reverse-geocoding request, do not attempt to initiate another reverse- or forward-geocoding request.

Geocoding requests are rate-limited for each app, so making too many requests in a short period of time may cause some of the requests to fail. When the maximum rate is exceeded, the geocoder passes an error object with the value kCLErrorNetwork to your completion handler.

Availability
  • Available in OS X v10.8 and later.
Declared In
CLGeocoder.h

Constants

CLGeocodeCompletionHandler

A block to be called when a geocoding request is complete.

typedef void (^CLGeocodeCompletionHandler)(NSArray *placemark, NSError *error);
Discussion

Upon completion of a geocoding request, a block of this form is called to give you a chance to process the results. The parameters of this block are as follows:

placemark

Contains an array of CLPlacemark objects. For most geocoding requests, this array should contain only one entry. However, forward-geocoding requests may return multiple placemark objects in situations where the specified address could not be resolved to a single location.

If the request was canceled or there was an error in obtaining the placemark information, this parameter is nil.

error

Contains a pointer to an error object (if any) indicating why the placemark data was not returned. For a list of possible error codes, see Core Location Constants Reference.

Availability
  • Available in OS X v10.8 and later.
Declared In
CLGeocoder.h