Converting an address to a set of map coordinates is called forward geocoding, while converting from a set of coordinates to an address is called reverse geocoding. Both forward and reverse geocoding are supported in Apple’s CLGeocoder class—which is part of Apple’s CoreLocation framework.

The CLGeocoder class provides services for converting between a coordinate (specified as a latitude and longitude) and the user-friendly representation of that coordinate. User-friendly representation of the coordinate means the street, city, state, and country information of a given location or a relevant point of interest, landmark, or other identifying information.

The CLGeocoder class also provides services for the reverse: returning the coordinate value for a text string that is the user-friendly representation of that coordinate.

To use a CLGeocoder object, first create it and then send it a forward- or reverse-geocoding message.

  • Reverse-geocoding: These requests take a latitude and longitude value and find a user-readable address.

  • Forward-geocoding: These 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 as an array of CLPlacemark objects to a completion handler block. In the case of forward-geocoding requests, multiple placemark objects may be returned if the provided information yields multiple possible locations.

A CLPlacemark object contains, among other things, the following properties:

  • location: Very useful for forward geocoding

  • name: The name of the placemark

  • addressDictionary: A dictionary containing the Address Book keys and values for the placemark

  • ISOcountryCode: The abbreviated country name

  • country: The name of the country

  • postalCode: The postal code

  • administrativeArea: The state or province

  • subAdministrativeArea: Additional administrative area information (such as county)

  • locality: The city

  • subLocality: Additional city-level information such as neighborhood or a common name for the location

  • thoroughfare: The street

  • subThoroughfare: Additional street-level information, such as the building number

  • region: The CLRegion

Landmark and geographic information may also be available in the CLPlacemark object in the following properties:

  • areasOfInterest: The relevant areas of interest associated with the placemark

  • * inlandWater: The name of the inland water body associated with the placemark

  • ocean: The name of the ocean associated with the placemark

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, the geocoder might return the name of the overall region rather than the name of a small park that the user is passing through.

Here are some rather loose rules (Apple’s) for using the CLGeocoder object:

  • Send at most one geocoding request for any single user action. That is, don’t start another request until the first one has completed.

  • If the app needs the geocoded location in more than one map location, save and then reuse the results from the initial geocoding request instead of doing another one.

  • 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, a reasonable amount of time has passed, or both. For example, in a typical situation, you should not send more than one geocoding request per minute.

  • Do not start a geocoding request if your application is inactive or in the background.

  • An iOS-based device must have access to the network in order for the CLGeocoder object to return detailed placemark information. Although iOS 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 CLGeocoder object may still report an error.

You can use a CLGeocoder object either in conjunction with, or independent of, the classes of the MapKit framework.