An interface for converting between geographic coordinates and place names.


@interface CLGeocoder : NSObject


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, you 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.

Tips for Using a Geocoder Object

Apps must 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 kCLErrorNetwork error 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 MapKit framework.


Reverse Geocoding a Location

- reverseGeocodeLocation:preferredLocale:completionHandler:

Submits a reverse-geocoding request for the specified location and locale.

- reverseGeocodeLocation:completionHandler:

Submits a reverse-geocoding request for the specified location.

Geocoding an Address

- geocodeAddressString:inRegion:preferredLocale:completionHandler:

Submits a forward-geocoding requesting using the specified address string and locale information.

- geocodeAddressString:completionHandler:

Submits a forward-geocoding request using the specified string.

- geocodeAddressString:inRegion:completionHandler:

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

- geocodePostalAddress:completionHandler:

Submits a forward-geocoding requesting using the specified Contacts framework information.

- geocodePostalAddress:preferredLocale:completionHandler:

Submits a forward-geocoding requesting using the specified locale and Contacts framework information.

- geocodeAddressDictionary:completionHandler:

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


Managing Geocoding Requests

- cancelGeocode

Cancels a pending geocoding request.


A Boolean value indicating whether the receiver is in the middle of geocoding its value.

Processing Requests


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


Inherits From

See Also


Converting Between Coordinates and User-Friendly Place Names

Convert between a latitude/longitude pair and a more user-friendly description of that location.


A user-friendly description of a geographic coordinate, often containing the name of the place, its address, and other relevant information.