Convert between a latitude/longitude pair and a more user-friendly description of that location.
- Core Location
CLLocation object reports locations as a latitude/longitude pair. While these values uniquely represent any location on the planet, they are not values that users immediately associate with the location. Users are more familiar with names that describe a location, such as street names or city names. The
CLGeocoder class lets you convert between geographic coordinates and the user-friendly names associated with that location. You can convert from either a latitude/longitude pair to a user friendly place name, or the other way around.
User place names are represented by a
CLPlacemark object, which contains properties for specifying the street name, city name, country name, postal code, and many others. Placemarks also contain properties describing relevant geographic features or points of interest at the location, such as the names of mountains, rivers, businesses, or landmarks.
Geocoder objects are one-shot objects—that is, you use each object to make a single conversion. You can create multiple geocoder objects and perform multiple conversions, but Apple rate limits the number of conversions you can perform. Making too many requests in a short period of time may cause some of those requests to fail. For tips on how to manage any conversions, see the overview of
Convert a Coordinate into a Placemark
If you have a
CLLocation object, call the
reverse method of your geocoder object to retrieve a
CLPlacemark object for that location. Typically, you convert coordinates into placemarks when you want to display information about the location to the user. For example, if the user selects a location on a map, you might want to show the address at that location.
Listing 1 shows how to obtain placemark information for the last location reported by the
CLLocation object. Because calls to the geocoder object are asynchronous, the caller of this method passes in a completion handler, which is executed with the results.
Convert a Placemark into a Coordinate
If you have user-provided address information, call the methods of
CLGeocoder to obtain the corresponding location data. The
CLGeocoder class provides options for converting a user-typed string or for converting a dictionary of address-related information. That information is forwarded to Apple servers, which interpret the information and return the results.
Depending on the precision of the user-provided information, you may receive one result or multiple results. For example, passing a string of "100 Main St., USA" may return many results unless you also specify a search region or additional details. To help you decide which result is correct, the geocoder actually returns
CLPlacemark objects, which contain both the coordinate and the original information that you provided.
Listing 2 shows how you might obtain a coordinate value from a user-provided string. The example calls the provided completion handler with only the first result. If the string does not correspond to any location, the method calls the completion handler with an error and an invalid coordinate.