iOS Developer Library

Developer

CoreLocation Framework Reference CLGeocoder Class Reference

Options
Deployment Target:

On This Page
Language:

CLGeocoder

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:

  • 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.

Inheritance


Conforms To


Import Statement


Swift

import CoreLocation

Objective-C

@import CoreLocation;

Availability


Available in iOS 5.0 and later.
  • Submits a reverse-geocoding request for the specified location.

    Declaration

    Swift

    func reverseGeocodeLocation(_ location: CLLocation!, completionHandler completionHandler: CLGeocodeCompletionHandler!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func geocodeAddressDictionary(_ addressDictionary: [NSObject : AnyObject]!, completionHandler completionHandler: CLGeocodeCompletionHandler!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 5.0 and later.

  • Submits a forward-geocoding request using the specified string.

    Declaration

    Swift

    func geocodeAddressString(_ addressString: String!, completionHandler completionHandler: CLGeocodeCompletionHandler!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func geocodeAddressString(_ addressString: String!, inRegion region: CLRegion!, completionHandler completionHandler: CLGeocodeCompletionHandler!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 5.0 and later.

  • Cancels a pending geocoding request.

    Declaration

    Swift

    func cancelGeocode()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 5.0 and later.

  • geocoding geocoding Property

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

    Declaration

    Swift

    var geocoding: Bool { get }

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 5.0 and later.

Data Types

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

    Declaration

    Swift

    typealias CLGeocodeCompletionHandler = ([AnyObject]!, NSError!) -> Void

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreLocation;

    Swift

    import CoreLocation

    Availability

    Available in iOS 5.0 and later.