iOS Developer Library

Developer

MapKit Framework Reference MKReverseGeocoder Class Reference

Options
Deployment Target:

On This Page

MKReverseGeocoder

The MKReverseGeocoder class provides services for converting a map coordinate (specified as a latitude/longitude pair) into information about that coordinate, such as the country, city, or street. A reverse geocoder object is a single-shot object that works with a network-based map service to look up placemark information for its specified coordinate value.

The Google terms of service require that the reverse geocoding service be used in conjunction with a Google map; take this into account when designing your application's user interface.

Each Map Kit application has a limited amount of reverse geocoding capacity, so it is to your advantage to use reverse geocode requests sparingly. Here are some rules of thumb for using this class most effectively:

  • Send at most one reverse-geocoding request for any one user action.

  • If the user performs multiple actions that involve reverse-geocoding the same location, reuse the results from the initial reverse-geocoding request instead of starting individual requests for each action.

  • When you want to update the location automatically (such as when the user is moving), reissue the reverse-geocoding request only when the user's location 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 reverse-geocode request per minute.

  • Do not start a reverse-geocoding request at a time when the user will not see the results immediately. For example, do not start a request if your application recently resigned the active state (possibly because of an interruption such as a phone call) and is waiting to become active again.

An iOS-based device must have access to the network in order for the reverse geocoder object to return valid information. The reverse geocoder returns information through its associated delegate object, which is an object that conforms to the MKReverseGeocoderDelegate protocol. If the reverse geocoder is unable to retrieve the requested information, it similarly reports the error to its delegate object. For more information on this protocol, see MKReverseGeocoderDelegate Protocol Reference.

  • Initializes the reverse geocoder with the specified coordinate value.

    Deprecation Statement

    Use the CLGeocoder class instead.

    Declaration

    - (instancetype)initWithCoordinate:(CLLocationCoordinate2D)coordinate

    Parameters

    coordinate

    The map coordinate whose placemark information you want to retrieve.

    Return Value

    An initialized MKReverseGeocoder object.

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 5.0.

  • delegate (iOS 5.0) Property

    The reverse geocoder’s delegate object.

    Deprecation Statement

    Use the CLGeocoder class instead.

    Declaration

    @property(nonatomic, weak) id< MKReverseGeocoderDelegate > delegate

    Discussion

    A reverse-geocoder object sends messages to its delegate regarding the successful (or unsuccessful) acquisition of placemark data. You must provide a delegate object to receive this data.

    For more information about the MKReverseGeocoderDelegate protocol, see MKReverseGeocoderDelegate Protocol Reference.

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 5.0.

  • coordinate (iOS 5.0) Property

    The coordinate whose placemark data you want to retrieve. (read-only)

    Deprecation Statement

    Use the CLGeocoder class instead.

    Declaration

    @property(nonatomic, readonly) CLLocationCoordinate2D coordinate

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 5.0.

  • placemark (iOS 5.0) Property

    The result of the reverse-geocoding operation. (read-only)

    Deprecation Statement

    Use the CLGeocoder class instead. Note that placemarks in CLGeocoder always come back to the coordinate of the place, not the requested coordinate.

    Declaration

    @property(nonatomic, readonly) MKPlacemark *placemark

    Discussion

    The value of this property is nil by default. After a successful reverse-geocoding operation, it is set to the placemark object that was generated.

    Availability

    Available in iOS 3.2 and later.

    Deprecated in iOS 5.0.

  • - start (iOS 5.0)

    Starts the reverse-geocoding process asynchronously.

    Deprecation Statement

    Use the CLGeocoder class instead.

    Declaration

    - (void)start

    Discussion

    You should call this method only once to begin the reverse-geocoding process. This method submits the coordinate value to the map server asynchronously and returns. Once the process is complete, the results are delivered to the associated delegate object.

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 5.0.

  • querying (iOS 5.0) Property

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

    Deprecation Statement

    Use the CLGeocoder class instead.

    Declaration

    @property(nonatomic, readonly, getter=isQuerying) BOOL querying

    Discussion

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

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 5.0.

  • - cancel (iOS 5.0)

    Cancels a pending reverse-geocoding request.

    Deprecation Statement

    Use the CLGeocoder class instead.

    Declaration

    - (void)cancel

    Discussion

    You can use this method to cancel a pending request and free up the resources associated with that request. If the request has already returned or has not yet begun, calling this method has no effect.

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 5.0.