CZWeatherKit is a simple, extensible weather library for iOS and OS X that allows for easy downloading of weather data from various weather services. CZWeatherKit is extremely lightweight and requires no external dependencies.

CZWeatherKit started as way to simplify weather API requests for Sol°, a simple open-source iOS weather app (App Store Link). The README will be updated when CZWeatherKit has been integrated back into Sol° so you can see what it looks like in a completed app.

Add the following to your Podfile:

    platform :ios, '7.0'
    pod "CZWeatherKit"

and run pod install. If you're not using Cocoa Pods, add the CZWeatherKit directory to your project (but you should probably consider using Cocoa Pods).

CZWeatherKit has only been tested on iOS 7 and OS X 10.9, but the library avoids using newer Cocoa/Cocoa Touch API so it may work on older deployment targets.

CZWeatherKit currently supports the following weather services:

• Weather Underground
• Open Weather Map

Some weather services require an API key while others do not. Consult the documentation for the weather API you would like to use. Additional services can be added (somewhat) easily by adopting the CZWeatherService protocol. See the 'Adding New Services' section of the README.

CZWeatherCondition objects have a climaconCharacter property that contains an appropriate climacon character mapping for the weather condition description. The Climacons Font is a font set created by Adam Whitcroft featuring various weather-related icons. In order to use the climaconCharacter property, download the Climacons font and add it to your project. The following example illustrates how to use the character in a UILabel:

    ...

    CZWeatherCondition *condition = ... // Pretend we have this!

    UILabel *label = [[UILabel alloc]initWithFrame:<your_frame>];
    label.font = [UIFont fontWithName:CLIMACON_FONT size:<your_font_size>];
    label.text = [NSString stringWithFormat:@"%c", condition.climaconCharacter];
    
    ...
    

You can also check out the iOS example project to see a few more examples.

    CZWeatherRequest *request = [CZWeatherRequest requestWithType:CZCurrentConditionsRequestType];
    request.location = [CZWeatherLocation locationWithCity:@"Austin" state:@"TX"];
    request.service = [CZWundergroundService serviceWithKey:<API_KEY_HERE>];
    [request performRequestWithHandler:^(id data, NSError *error) {
        if (data) {
            CZWeatherCondition *current = (CZWeatherCondition *)data;
            // Do whatever you like with the data here
        }
    }];

    CLLocationCoordinate2D coordinate = CLLocationCoordinate2DMake(30.2500, -97.7500);
    CZWeatherRequest *request = [CZWeatherRequest requestWithType:CZForecastRequestType];
    request.location = [CZWeatherLocation locationWithCLLocationCoordinate2D:coordinate];
    request.service = [CZWundergroundService serviceWithKey:<API_KEY_HERE>];
    [request performRequestWithHandler:^(id data, NSError *error) {
        if (data) {
            NSArray *forecasts = (NSArray *)data;
            // Do whatever you like with the data here
        }
    }];

    CZWeatherRequest *request = [CZWeatherRequest requestWithType:CZForecastRequestType];
    request.location = [CZWeatherLocation locationWithCity:@"Sydney" country:@"Australia"];
    request.service = [CZWundergroundService serviceWithKey:<API_KEY_HERE>];
    request.detailLevel = CZWeatherRequestFullDetail;
    [request performRequestWithHandler:^(id data, NSError *error) {
        if (data) {
            NSArray *forecasts = (NSArray *)data;
            // Do whatever you like with the data here
        }
    }];

    CLLocationCoordinate2D coordinate = CLLocationCoordinate2DMake(30.2500, -97.7500);
    CZWeatherRequest *request = [CZWeatherRequest requestWithType:CZCurrentConditionsRequestType];
    request.location = [CZWeatherLocation locationWithCLLocationCoordinate2D:coordinate];
    request.service = [CZOpenWeatherMapService serviceWithKey:<API_KEY_HERE>];
    [request performRequestWithHandler:^(id data, NSError *error) {
        if (data) {
            CZWeatherCondition *current = (CZWeatherCondition *)data;
            // Do whatever you like with the data here
        }
    }];

    CZWeatherRequest *request = [CZWeatherRequest requestWithType:CZForecastRequestType];
    request.location = [CZWeatherLocation locationWithCity:@"London" country:@"UK"];
    request.service = [CZOpenWeatherMapService serviceWithKey:<API_KEY_HERE>];
    [request performRequestWithHandler:^(id data, NSError *error) {
        if (data) {
            NSArray *forecasts = (NSArray *)data;
            // Do whatever you like with the data here
        }
    }];

    CZWeatherRequest *request = [CZWeatherRequest requestWithType:CZForecastRequestType];
    request.location = [CZWeatherLocation locationWithCity:@"Austin" state:@"TX"];
    request.service = [CZOpenWeatherMapService serviceWithKey:<API_KEY_HERE>];
    request.detailLevel = CZWeatherRequestFullDetail;
    [request performRequestWithHandler:^(id data, NSError *error) {
        if (data) {
            NSArray *forecasts = (NSArray *)data;
            // Do whatever you like with the data here
        }
    }];

Weather services differ in the variety of locations they support. For example, Wunderground allows you to query by City/State, City/Country, Zipcode, Latitude/Longitude, and IP address. Open Weather Map only allows you to query by City/State, City/Country, Latitude/Longitude. When performing requests to a service, ensure that the query type is supported.

Requests carry with them a detail level. A detail level loosely defines how much information you wish to retrieve for the request, but the meaning can vary for each service. For example, when requesting forecast data from Wunderground, a detail level of CZWeatherRequestLightDetail will retrieve a 3-day forecast and CZWeatherRequestFullDetail will retrieve a 10-day forecast. When requesting forecast data from Open Weather Map, a detail level of CZWeatherRequestLightDetail will retrieve an hourly forecast and CZWeatherRequestFullDetail will retrieve a daily forecast.

Services can be added somewhat painlessly to CZWeatherKit. To be a weather service, a class should adopt the CZWeatherService protocol. Weather service objects separate URL generation/response parsing from performing actual requests. This allows new weather services to be added without any changes to the rest of the CZWeatherKit's API. If you would like to contribute to this project by adding new weather services, please take a look at both CZWundergroundService and CZOpenWeatherMapService.

The unit tests for the project aren't all-encompassing and are somewhat lacking. If you would like to add unit tests, that would be appreciated.

The project is also being tested on the continuous integration service Travis CI. You can check the build history here.

If you would like to contribute to this project, please try to follow the coding style of the rest of the project. I have a somewhat particular (Ok, very particular...) coding style and would like new features to match. Also, I would appreciate if you add unit tests for anything you add (especially new services!). Last but no least, these are the general terms:

• The project is under the BSD license, so uh take note of that, I guess.
• I will keep the project open-source and on GitHub as long as it's relevant (like, if 10 years from now Cocoa is dead then I'll probably take it down)
• If this project results in your production app exploding users' phones, sorry I'm not liable :( . Also, please post an issue if it does.
• If you make contributions, thanks! If that leads to any issues with licensing or whatever, just let me know and we'll (hopefully) work it out.
• If you have any issues or suggestions for the general architecture of CZWeatherKit, I'd love to hear them! Please post an issue.

• Comyar Zaheri, @comyarzaheri
• Eli Perkins, @eliperkins