Revamp API to be more idiomatic in Swift #41
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Rewrote the library to more closely parallel mapbox/MapboxStatic.swift#19. Removed the class prefix from Swift but kept it for Objective-C. The goal is no longer to be a (poor) drop-in replacement for MapKit’s MKDirections API but rather to be as idiomatic as possible in Swift and Objective-C, with a priority on Swift. Symbols conform to platform naming conventions but in some cases eschew MapKit terminology in favor of Geocoding API terminology, so that api-documentation makes sense in the context of this library. Removed the dependency on RequestKit. This library chooses reasonable default networking behavior; if you need anything more sophisticated, you can access the URL request information to use with a custom NSURLSession. 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. Removed the cancelGeocode() method; instead, directly cancel the NSURLSessionDataTask returned by geocode(options:completionHandler:). 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. Otherwise, create a Geocoder object with the access token explicitly. A single geocoder object can handle multiple requests concurrently (since it just passes the requests off to the shared URL session). Unified geocodeAddressString(_:completionHandler:) and reverseGeocodeLocation(_:completionHandler:) into a single geocode(options:completionHandler:) method that takes a GeocodeOptions object. There are two subclasses of GeocodeOptions, ForwardGeocodeOptions and ReverseGeocodeOptions, that support all the options exposed by the Geocoding API. Effectively, this change adds support for the Geocoding API’s autocomplete and bbox options. Added an attribution parameter to the completion handler that contains required legal notices. The access_token parameter is now the last URL parameter instead of the first. Replaced the Placemark.Scope enum with the PlacemarkScope bitmask, which is implemented in Objective-C so that Objective-C code can use it too. Using a bitmask prevents client code from specifying a scope multiple times. Renamed AdministrativeArea to Region, reflecting the Geocoding API result type. 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. A new qualifiers property returns the entire placemark hierarchy in indexer order, in case there’s any overlap between containing placemarks. 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. Added a wikidataEntityIdentifier property corresponding to the Geocoding API’s wikidata property. Removed the CLLocationCoordinate2D equality operator to avoid conflicts with client code that may define the same. Upgraded Podfile to CocoaPods 1.0 format. Enabled code coverage gathering. Updated text fixtures and expectations. Fixes #39, fixes #40.
Added class prefix to Placemark in Objective-C. Removed class prefix from MBRectangularRegion in Swift. Renamed autocompletionEnabled to autocompletesQuery and moved it to ForwardGeocodeOptions, since it doesn’t make sense in ReverseGeocodeOptions.
It’s less awkward to work with an optional (nullable) object than a struct that has a magic value.
Wikidata tends to call them “items” these days.
Took formattedAddressLines private like it used to be. Added postalAddress to return a CNPostalAddress on iOS 9.0 and above. A CNPostalAddress from the Contacts framework is easier to work with than a full Address Book framework–style addressDictionary.
CLRegion.containsCoordinate(_:) is marked unavailable, the return type is marked implicitly unwrapped as a workaround.
Added examples in both Swift and Objective-C to the readme and updated the pod description to deemphasize the API’s similarity to CLGeocoder.
Include a failure reason from the response body in a failed request’s error. Include a hint when the error is due to rate-limiting. Split raw request and response logic into a separate method. Fixes #26.
Batch geocoding uses a separate method on Geocoder and separate ForwardBatchGeocodeOptions and ReverseBatchGeocodeOptions objects. The batch geocoding completion handler accepts more deeply nested data.
Also point to the Mapbox Geocoding website.
1ec5
added a commit
that referenced
this pull request
May 22, 2016
Fixed a regression introduced in #41.
This was referenced May 22, 2016
Merged
1ec5
added a commit
to mapbox/mapbox-directions-swift
that referenced
this pull request
May 31, 2016
Rewrote the library to more closely parallel mapbox/MapboxGeocoder.swift#41 and mapbox/MapboxStatic.swift#19. Removed the class prefix from Swift but kept it for Objective-C. The goal is no longer to be a (poor) drop-in replacement for MapKit’s MKDirections API but rather to be as idiomatic as possible in Swift and Objective-C, with a priority on Swift. Symbols conform to platform naming conventions but in some cases eschew MapKit terminology in favor of Geocoding API terminology, so that api-documentation makes sense in the context of this library. Removed the dependency on RequestKit. This library chooses reasonable default networking behavior; if you need anything more sophisticated, you can access the URL request information to use with a custom NSURLSession. Directions 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 URLForCalculatingDirections(options:) method. Removed the cancel() method; instead, directly cancel the NSURLSessionDataTask returned by calculateDirections(options:completionHandler:). Added a shared (singleton) Directions object. Use the shared object if you’ve set your Mapbox access token in the MGLMapboxAccessToken key of your application’s Info.plist file. Otherwise, create a Directions object with the access token explicitly. A single directions object can handle multiple requests concurrently (since it just passes the requests off to the shared URL session). Eliminated the separate APIs for calculating ETAs. Instead, all the options supported by the Directions API, including flags for including steps and the overview geometry, are now exposed through a new RouteOptions class. Effectively, this change adds support for the geometries, overview, radiuses, steps, and continue_straight query parameters and allows the heading accuracy of any waypoint to be customized. However, note that steps are no longer returned by default, and the overview geometry is simplified by default. The access_token parameter is now the last URL parameter instead of the first. Broke out MBDirectionsRequest.TransportType into three profile identifier constants. You always specify a profile identifier, not a transport type. That makes the desired mode of transportation more open-ended. Removed the MBDirectionsResponse class in favor of passing the waypoints and routes from the response directly into the completion handler. Renamed Route.geometry to Route.coordinates. For Objective-C compatibility, all enums are backed by integer types instead of String, but they’re CustomStringConvertible to allow for the same expressiveness we’re used to in Swift. Error handling is much more robust now. Various error conditions returned by the API cause the localized failure reason and recovery suggestion to be set in the NSError object that is passed into the completion handler. Updated test fixtures and expectations for the v5 server-side API and the revamped client-side API, and updated examples. Fixes #41, fixes #43, fixes #44.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Rewrote the library to more closely parallel mapbox/MapboxStatic.swift#19. Removed the class prefix from Swift but kept it for Objective-C. The goal is no longer to be a (poor) drop-in replacement for MapKit’s MKDirections API but rather to be as idiomatic as possible in Swift and Objective-C, with a priority on Swift. Symbols conform to platform naming conventions but in some cases eschew MapKit terminology in favor of Geocoding API terminology, so that api-documentation makes sense in the context of this library.
Removed the dependency on RequestKit. This library chooses reasonable default networking behavior; if you need anything more sophisticated, you can access the URL request information to use with a custom NSURLSession. 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. Removed thecancelGeocode()method; instead, directly cancel the NSURLSessionDataTask returned bygeocode(options:completionHandler:).Added a shared (singleton) Geocoder object. Use the shared object if you’ve set your Mapbox access token in the
MGLMapboxAccessTokenkey of your application’s Info.plist file. Otherwise, create a Geocoder object with the access token explicitly. A single geocoder object can handle multiple requests concurrently (since it just passes the requests off to the shared URL session).Unified
geocodeAddressString(_:completionHandler:)andreverseGeocodeLocation(_:completionHandler:)into a singlegeocode(options:completionHandler:)method that takes a GeocodeOptions object. There are two subclasses of GeocodeOptions, ForwardGeocodeOptions and ReverseGeocodeOptions, that support all the options exposed by the Geocoding API. Effectively, this change adds support for the Geocoding API’s autocomplete and bbox options. Added an attribution parameter to the completion handler that contains required legal notices. Theaccess_tokenparameter is now the last URL parameter instead of the first. Added support for batch geocoding requests via ForwardBatchGeocodeOptions and ForwardReverseGeocodeOptions.Replaced the Placemark.Scope enum with the
PlacemarkScopebitmask, which is implemented in Objective-C so that Objective-C code can use it too. Using a bitmask prevents client code from specifying a scope multiple times. RenamedAdministrativeAreatoRegion, reflecting the Geocoding API result type.For Placemark objects representing addresses and points of interest, the
nameproperty is no longer fully qualified; that is, it no longer contains the full administrative hierarchy. For the fully-qualified name, use thequalifiedNameproperty. Properties such ascountryandpostalCodereturn Placemark objects instead of strings; to get the name of e.g. the surrounding country, use the returned placemark object’snameproperty. A newsuperiorPlacemarksproperty returns the entire placemark hierarchy in indexer order, in case there’s any overlap between containing placemarks. RenamedISOcountryCodetocode; this property may be included in subnational placemarks, such as placemarks representing regions. Replaced theadministrativeAreaandsubAdministrativeAreaproperties withadministrativeRegionanddistrict, respectively. Unlike the oldsubAdministrativeRegionproperty,districtmay benilif it isn’t applicable. Renamedlocalitytoplace, andsubLocalitytoneighborhood. Added awikidataItemIdentifierproperty corresponding to the Geocoding API’swikidataproperty. Added apostalAddressproperty that can be formatted using the Contacts framework’s CNPostalAddressFormatter or placed inside a CNContact.Include a failure reason from the response body in a failed request’s error. Include a hint when the error is due to rate-limiting. Split raw request and response logic into a separate method.
Removed the
CLLocationCoordinate2Dequality operator to avoid conflicts with client code that may define the same.Upgraded Podfile to CocoaPods 1.0 format. Enabled code coverage gathering. Updated text fixtures and expectations.
Fixes #26, fixes #39, fixes #40.
/cc @friedbunny @tmcw