v0.5.0

This is a complete rewrite of MapboxGeocoder.swift that focuses on making the API more Swift-like in Swift but also improves Objective-C support (#41). The goal is no longer to be a drop-in replacement for Core Location’s CLGeocoder API, but the library continues to use terminology familiar to Cocoa and Cocoa Touch developers. This version includes a number of breaking changes:

• Removed the MB class prefix from Swift but kept it for Objective-C.
• Added a shared (singleton) Geocoder object. Use the shared object if you’ve set your Mapbox access token in the MGLMapboxAccessToken key of your application’s Info.plist file. (You may have already done so if you’ve installed the Mapbox iOS SDK or Mapbox OS X SDK.) Otherwise, create a Geocoder object with the access token explicitly.
• Simplified the networking part of the library:
  • Removed the dependency on RequestKit. If you’re upgrading to this version using CocoaPods, you can remove the NBNRequestKit dependency override.
  • Geocoder no longer needs to be strongly held in order for the request to finish. Instead, the request is made against the shared URL session; to use a custom URL session, make the request yourself using the URL returned by the URLForGeocoding(options:) property.
  • A single geocoder object uses the shared URL session for all requests, so it can handle multiple requests concurrently without raising an exception.
  • Removed the cancelGeocode() method; instead, directly cancel the NSURLSessionDataTask returned by geocode(options:completionHandler:).
• Replaced geocodeAddressString(_:completionHandler:) and reverseGeocodeLocation(_:completionHandler:) with a single geocode(options:completionHandler:) method that takes a GeocodeOptions object. The two concrete subclasses of GeocodeOptions, ForwardGeocodeOptions and ReverseGeocodeOptions, support all the options exposed by the Geocoding API.
• Added an attribution parameter to the completion handler that contains required legal notices.
• Replaced the Placemark.Scope enum with a PlacemarkScope bitmask. Renamed .AdministrativeArea to .Region.
• Removed the CLLocationCoordinate2D equality operator to avoid conflicts with client code that may define the same.

There are also many breaking changes to the Placemark object that results from a request to the API:

• For Placemark objects representing addresses and points of interest, the name property is no longer fully qualified; that is, it no longer contains the full administrative hierarchy. For the fully-qualified name, use the qualifiedName property.
• Properties such as country and postalCode return Placemark objects instead of strings. To get the name of e.g. the surrounding country, use the returned placemark object’s name property.
• Renamed ISOcountryCode to code. This property may be included in subnational placemarks, such as placemarks representing regions.
• Replaced the administrativeArea and subAdministrativeArea properties with administrativeRegion and district, respectively. Unlike the old subAdministrativeRegion property, district may be nil if it isn’t applicable.
• Renamed locality to place, and subLocality to neighborhood.

Other changes since v0.4.2:

• Added official support for OS X, tvOS, and watchOS. (#44, #48)
• Added support for the Contacts framework’s CNPostalAddress class. You can directly forward geocode a CNPostalAddress. You can also get the postalAddress of a placemark, suitable to format with CNPostalAddressFormatter or place inside a CNContact. (#41, #42)
• Added options for disabling autocompletion behavior and limiting results to a rectangular region. (#41)
• Added support for batch geocoding requests via ForwardBatchGeocodeOptions and ForwardReverseGeocodeOptions. (#41)
• When a request fails, the returned error includes a failure reason. When the error is due to rate-limiting, the error also includes a hint that indicates how long to wait before making another request. (#41)
• A new superiorPlacemarks property returns the entire hierarchy of placemarks (in indexer order) that contain a given placemark, in case there’s any overlap between containing placemarks. (#41)
• Added a wikidataItemIdentifier property identifying a placemark’s corresponding Wikidata item. (#41)