A simple, asynchronous Objective-C wrapper for the Forecast.io API
MIT License
Support this project via Gratipay
A simple Objective-C wrapper to make asynchronous requests to the Forecast.io API version 2
Note: You will need to request an API key and set that key when you first instantiate Forecastr, otherwise an exception will be thrown.
Updated to match the Forecast.io API as of October 21, 2014
The code base comes with two examples:
And here is a very basic example:
#import "FCViewController.h"
#import "Forecastr.h"
@interface FCViewController ()
{
Forecastr *forecastr;
}
@end
@implementation FCViewController
- (void)viewDidLoad
{
[super viewDidLoad];
// Get a reference to the Forecastr singleton
forecastr = [Forecastr sharedManager];
forecastr.apiKey = @""; // You will need to set the API key here (only set it once in the entire app)
[forecastr getForecastForLatitude:45.5081 longitude:-73.5550 time:nil exclusions:nil extend:nil language:nil success:^(id JSON) {
NSLog(@"JSON Response was: %@", JSON);
} failure:^(NSError *error, id response) {
NSLog(@"Error while retrieving forecast: %@", [forecastr messageForError:error withResponse:response]);
}];
}
@end
US
, SI
, UK
, or CA
unitsbs
(Bosnian), de
(German), en
(English, which is the default), es
(Spanish), fr
(French), it
(Italian), nl
(Dutch), pl
(Polish), pt
(Portuguese), tet
(Tetum), or x-pig-latin
(Pig Latin)someJavascriptMethodName({jsonResponseGoesHere})
)currently
, minutely
, hourly
, daily
, alerts
, or flags
)[forecastr cancelAllForecastRequests];
extend
hourly options to return hourly data for the next seven days rather than the next twoCLLocation
object instead of pure latitude/longitude, import Forecastr+CLLocation.h
instead of Forecastr.h
forecastr.cacheEnabled = NO;
forecastr.cacheExpirationInMinutes = 10;
or some other integer value[forecastr flushCache];
(might be a good idea to do this every time your app starts)The wrapper has a number of extras so please have a look at all of the source files included with it so you don't duplicate existing work. For instance, there are constants created for all constant values in the API such as data block / point dictionary key names, weather icon names, unit types, etc.
Additionally, there are a few helper methods that were written to help with UI display of the JSON data:
descriptionForPrecipIntensity
will return a human readable description based on the precipitation intensity floating point valueimageNameForWeatherIconType
will return an image name based on the weather icon type specified in the forecast responsemessageForError:withResponse:
will try and find the most human readable error description based on the response and then reverts to the error's localized description if nothing else is foundThere are only two types of error responses: 400 errors (where you provide invalid input, such as an impossible latitude or longitude) or 500 errors (where something unexpected happened on the Forecast.io servers). Both cases return a JSON object with a string "error" property that can be used to determine the cause of the error. In all other scenarios, an HTTP 200 is returned, but pieces of data may be lacking (even in circumstances of normal operation). Therefore, you should always check that the properties you intend to use actually exist before using them, and in the event that they are missing, treat it as an error at your discretion.
One simple way of checking if a dictionary key exists is:
id temperature = [forecast objectForKey:kFCTemperature];
self.temperatureLabel.text = temperature ? [NSString stringWithFormat:@"%d°", [temperature intValue]] : @"N/A";
In this example, we simply check if the object is nil and return N/A
if so, otherwise we return a formatted temperature value.
Essentially, this code is free to use in commercial and non-commercial projects with no attribution necessary.
See the LICENSE
file for more details.
A HUGE thank you to the following people for helping me improve and maintain Forecastr:
If you'd like to help, please submit a pull request with tested code and please also update any examples that your code might affect.