Add example of using Directions API beta query parameters

[1ec5]

At any given time, the Directions API documentation describes several query parameters that are available for beta testing. Since these parameters lack long-term support, the MapboxDirections library can’t support them and guarantee API stability at the same time. However, it is possible for developers to take advantage of these parameters by subclassing RouteOptions or better yet NavigationRouteOptions, overriding the query item array that goes into the generated request URL. We should have an example of this custom usage; it would be easier to keep this example up-to-date with any beta-related changes than to update the library itself.

For example, here’s a NavigationRouteOptions subclass that takes advantage of the maxspeed query parameter, which is currently in beta, to identify routes suitable for street-legal golf carts and calculate an ETA based on a departure an hour from now. (Street-legal golf carts are sometimes used in urban areas for delivery purposes. In Ohio, they may be capable of travel up to 20 miles per hour but no faster.)

class GolfCartRouteOptions: NavigationRouteOptions {
    override var urlQueryItems: [URLQueryItem] {
        let maximumSpeed = Measurement(value: 20, unit: UnitSpeed.milesPerHour) // maximum legal speed in Ohio
        let hourFromNow = Date().addingTimeInterval(60 * 60) // an hour from now
        let hourFromNowString = ISO8601DateFormatter.string(from: hourFromNow, timeZone: .current, formatOptions: .withInternetDateTime)
        return super.urlQueryItems + [
            // Assuming this parameter is supposed to be expressed in kilometers per hour
            URLQueryItem(name: "maxspeed", value: String(maximumSpeed.converted(to: .kilometersPerHour).value)),
            URLQueryItem(name: "depart_at", value: hourFromNowString),
        ]
    }
}

let options = GolfCartRouteOptions(coordinates: coordinates, profileIdentifier: .automobile)
…

Relatedly, for customers who are allowed to use a routing profile that isn’t officially documented for the general public, we could point out the possibility of setting profileIdentifier to a custom value such as DirectionsProfileIdentifier(rawValue: "mapbox/unicycle").

/cc @mapbox/navigation-ios