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

Inheritance


Conforms To


Import Statement


import CoreLocation @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

    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

    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

    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

    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

    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

    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

    import CoreLocation

    Availability

    Available in iOS 5.0 and later.