Swiftpack.co - Package - loopwxservices/WXKDarkSky

WXKDarkSky

MIT License Swift 4.0, Swift 4.1, Swift 4.2

This Swift package is a Codable layer over the Dark Sky API for quick and easy access to API response objects. It’s super straightforward and directly modeled after the Dark Sky API docs. We use it in Loop Weather 2, and we thought others might find it helpful.

It also has some helpful basic networking functionality for requesting data from the Dark Sky API. It might not fully satisfy your networking needs, but it’s written in pure Swift, so you don’t need to worry about conflicting dependencies or anything like that. If the networking functionality in this package doesn’t cut it, you’re free to handle networking yourself and pass responses to the Codable class, WXKDarkSkyResponse.

Compatibility

WXKDarkSky should work great with all versions of Swift 4, from 4.0 to 4.2 beta.

Installation

Swift Package Manager (recommended)

Of course, you'll need to add this package as a dependency in Swift Package Manager.

For Swift 4's Package Manager tools:

.package(url: "https://github.com/loopwxservices/WXKDarkSky.git", from: "2.2.0")

Then, just be sure to add "WXKDarkSky" as a dependency in the targets section.

CocoaPods

Adding WXKDarkSky via CocoaPods is super-simple. Just add this line to your Podfile:

pod 'WXKDarkSky', '~> 2.2.0'

Carthage

We do not currently provide official support for installation via Carthage. However, there is a decent chance that it works out of the box. If interest warrants, we'll be happy to add official support.

Manual

Just get the source files out of the Sources folder and drag them into your Xcode project, and add them to any relevant targets. Just make sure to keep updated should changes be made to the Dark Sky API.

Usage

The WXKDarkSkyResponse object structure perfectly matches that of the documented response format for ease of reference. In keeping with the documentation, nearly everything is an optional value, even if it is frequently included. Absolutely no assumption is made about the availability of weather data!

With networking

IMPORTANT! Do NOT make requests through WXKDarkSky's networking code if the code is run client-side. Doing so puts your API key at risk of being compromised. It's best to use your own networking code to obtain Dark Sky data from a custom server-side solution that simply re-serves Dark Sky output so that your API key cannot be exposed. (You can even use WXKDarkSky's networking code with server-side Swift frameworks like Vapor or Perfect if your project allows for it.)

WXKDarkSky includes basic networking functionality to load data from the Dark Sky API. You can make requests to the API by making use of the WXKDarkSkyRequest(key:).loadData method. Here’s an example:

let request = WXKDarkSkyRequest(key: "YOURKEYHERE")
let point = Point(latitude: 37.4, -96.8)

request.loadData(point: point) { (data, error) in
    if let error = error {
        // Handle errors here...
    } else if let data = data {
        // Handle the received data here...
    }
}

Beyond this point, handling data is just as in the "Without networking" section.

Request configuration

The loadData method supports two additional parameters for configuring your request. It takes an optional time parameter which defaults to nil, to which you may pass a Date object for a Time Machine request.

It also takes an optional options parameter which you can set with any of the following options:

  • exclude: Data blocks to exclude from the request.
  • extendHourly: Whether to extend the hourly forecast to 168 hours instead of 48 hours.
  • language: Language to be used in the response.
  • units: Units to be used in the response.

An Options object can be initialized with any combination of the above four. If you do not include one, it will use the default setting. You can also use Options.defaults to access the default options (for example, Options.defaults.extendHourly). Here’s an example:

let options = Options(exclude: [.minutely, .alerts], extendHourly: true, language: .german, units: .si)

WXKDarkSkyRequest.loadData(point: point, options: options) { (response, error) in
    if let response = response {
        // Successful request. Sample to get the current temperature...
        if let currently = response.currently {
            if let temperature = currently.temperature {
                print("Current temperature: " + String(describing: temperature))
            }
        }
    } else if let error = error {
        // Encountered an error, handle it here...
    }
}

As before, handle the results as in the "Without networking" section.

Without networking

If you use other networking code, using WXKDarkSky is still very simple:

if let response = WXKDarkSkyResponse.converted(from data: data) {
    // Sample to get the current temperature
    if let currently = response.currently {
        if let temperature = currently.temperature {
            print("Current temperature: " + String(describing: temperature))
        }
    }
}

Contributing

If the Dark Sky API changes and we haven’t gotten around to updating WXKDarkSky yet, feel free to open an issue or a pull request and we’ll handle it promptly.

If you have a question about using WXKDarkSky, please either open an issue or email us at help {at} loopweather {dot} services. We’ll be happy to help!

WXKDarkSky in use

If you’ve done something using WXKDarkSky, we’d love to see it! Just send us an email at help {at} loopweather {dot} services with the project name and a link (and anything else interesting that you'd like to include), and we'll list it below. If your project is top-secret and you'd rather not share, that’s fine, too. We have our own top-secret projects.

Licensing/legal

This package is licensed under the MIT License, which allows you to do just about anything with this Swift package (within Dark Sky's rules, of course) except sue us for any malfunctions, as long as you give us credit. We hope someone finds it useful.

While we're at it with the legal stuff: We are not affiliated in any way with The Dark Sky Company, LLC. Also, "Dark Sky" is their trademark, not ours.

Github

link
Stars: 9
Help us keep the lights on

Dependencies

Used By

Total: 0

Releases

2.2.0 - Jun 22, 2018

WXKDarkSky 2.2 includes the following changes:

  • We now support CocoaPods installation! Let us know if you run into any issues.
  • You can now directly create WXKDarkSkyResponse objects from Data objects that contain Dark Sky API JSON responses.
  • Inline documentation improvements.

2.1.0 - Jun 18, 2018

This release simply makes the method which constructs a URL for a Dark Sky request public (instead of internal) so that the method may be used with custom networking code.

2.0.3 - Jun 18, 2018

  • Adds language support for summaries in Hebrew and Korean (#3).

2.0.2 - Jan 9, 2018

This update fixes some issues with non-public initializers which should, in fact, be public. It also makes the version number palindromic, so there’s that.


What’s new in WXKDarkSky 2.0.x:

  • Removed the deprecated max/min temperatures in favor of daytime highs and overnight lows (#2).
  • Added basic networking functionality for retrieving data from the Dark Sky API (#3).
  • Now decodes times from JSON as Date objects rather than Ints (#4).

These changes may break your code. Please ensure compatibility with the above tweaks (particularly the new temperature and date coding conventions) before updating to the new version.

1.0.4 - Jan 2, 2018

This release adds support for apparentTemperatureHigh, apparentTemperatureHighTime, apparentTemperatureLow, and apparentTemperatureLowTime on daily data points

It also adds deprecation warnings for the old maximum/minimum temperature (and apparent temperature) items. They will be removed in the next release, version 2.0.0. If you are still using them, you should see buildtime warnings suggesting that you move away from them.

Please move to the new high/low convention as soon as possible—adopting them should require nearly no effort on your part beyond some renaming.