CLGeocoder Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/CoreLocation.framework |
| Availability | Available in iOS 5.0 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. Here are some rules of thumb for using this class effectively:
Send at most one geocoding request for any one user action.
If the user performs multiple actions that involve geocoding the same location, reuse the results from the initial geocoding request instead of starting individual requests for each action.
When you want to update the user’s current location automatically (such as when the user is moving), issue new geocoding requests only when the user has moved a significant distance and after a reasonable amount of time has passed. For example, in a typical situation, you should not send more than one geocoding request per minute.
Do not start a geocoding request at a time when the user will not see the results immediately. For example, do not start a request if your application is inactive or in the background.
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
-
– geocodeAddressDictionary:completionHandler: -
– geocodeAddressString:completionHandler: -
– geocodeAddressString:inRegion:completionHandler:
Managing Geocoding Requests
-
– cancelGeocode -
geocodingproperty
Properties
geocoding
A Boolean value indicating whether the receiver is in the middle of geocoding its value. (read-only)
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 iOS 5.0 and later.
Declared In
CLGeocoder.hInstance Methods
cancelGeocode
Cancels a pending geocoding request.
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 iOS 5.0 and later.
Declared In
CLGeocoder.hgeocodeAddressDictionary:completionHandler:
Submits a forward-geocoding request using the specified address dictionary.
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.
Availability
- Available in iOS 5.0 and later.
Declared In
CLGeocoder.hgeocodeAddressString:completionHandler:
Submits a forward-geocoding request using the specified string.
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.
Availability
- Available in iOS 5.0 and later.
Declared In
CLGeocoder.hgeocodeAddressString:inRegion:completionHandler:
Submits a forward-geocoding request using the specified string and region information.
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
niland 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.
Availability
- Available in iOS 5.0 and later.
Declared In
CLGeocoder.hreverseGeocodeLocation:completionHandler:
Submits a reverse-geocoding request for the specified location.
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.
Availability
- Available in iOS 5.0 and later.
Declared In
CLGeocoder.hConstants
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
CLPlacemarkobjects. 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 CLLocationManager Class Reference.
Availability
- Available in iOS 5.0 and later.
Declared In
CLGeocoder.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-07-17)