The {RClimacell} R package provides a high level wrapper around the Climacell version 4 API using the Timeline Interface. Currently, the {RClimacell} package only provides access to the Core data fields using the Timeline Interface. Each function call results in one API call and the free API (registration required) has both hourly rate limits and daily limits.
The {RClimacell} package consists of five functions:
climacell_temperature: obtains temperature related variablesclimacell_wind: obtains wind related variablesclimacell_precip: obtains precipitation related variablesclimacell_celestial: obtains the sunrise time, sunset time, and the moon phaseclimacell_core: obtains all of the data fields from the Core data layer using the Timeline interfaceEach of these functions returns a formatted tibble in which each column is correctly encoded.
The following table summarizes which Core layers are available in the current package version (all of these fields can be obtained using the climacell_core() function):
| API Field | {RClimacell} Equivalent Name | Implemented in package? | Part of Function |
|---|---|---|---|
| temperature | temp_c | yes | climacell_temperature() |
| temperatureApparent | temp_feel_c | yes | climacell_temperature() |
| dewPoint | dewpoint | yes | climacell_temperature() |
| humidity | humidity | yes | climacell_temperature() |
| windSpeed | wind_speed | yes | climacell_wind() |
| windDirection | wind_direction | yes | climacell_wind() |
| windGust | wind_gust | yes | climacell_wind() |
| pressureSurfaceLevel | pressure_surface_level | yes | climacell_precip() |
| pressureSeaLevel | pressure_sea_level | yes | climacell_precip() |
| precipitationIntensity | precipitation_intensity | yes | climacell_precip() |
| precipitationProbability | precipitation_probability | yes | climacell_precip() |
| precipitationType | precipitation_type | yes | climacell_precip() |
| sunriseTime | sunrise_time | yes | climcell_celestial() |
| sunsetTime | sunset_tim | yes | climcell_celestial() |
| solarGHI | solar_ghi | yes | climacell_precip() |
| visibility | visibility | yes | climacell_precip() |
| cloudCover | cloud_cover | yes | climacell_precip() |
| cloudBase | cloud_base | yes | climacell_precip() |
| cloudCeiling | cloud_ceiling | yes | climacell_precip() |
| moonPhase | moon_phase_code | yes | climcell_celestial() |
| weatherCode | weather_code | yes | climacell_precip() |
The Climacell API has certain limitations based on the subscription tier. This package is tested using the free tier. Due to this limitation, the author is only able to provide access to the Core layers. Note that the free tier allows for 500 calls per day, 25 calls per hour, and 3 calls per second (these limitations can change without notice).
The timestep argument defines the intervals at which to retrieve the data (e.g., daily, hourly, etc.). Valid values are:
| Timestep | Interval | Lower Limit | Upper Limit |
|---|---|---|---|
| 1m | 1 minute (per minute) | 6 hours prior to actual current UTC time | 6 hours ahead of actual current UTC time |
| 15m | 15 minutes | 6 hours prior to actual current UTC time | 6 hours ahead of actual current UTC time |
| 30m | 30 minutes | 6 hours prior to actual current UTC time | 6 hours ahead of actual current UTC time |
| 1h | 1 hour (hourly) | 6 hours prior to actual current UTC time | 108 hours ahead of actual current UTC time |
| 1d | 1 day (daily) | actual current UTC time | 15 days ahead of actual current UTC time |
| current | n/a | actual current UTC time | actual current UTC time |
Up to date information on these limits can be found here.
Version 4 of the Climacell API returns all values in metric and UTC times. The {RClimacell} package is designed to return the values returned by the API call with minimal modifications. Most of the modifications are to ensure that the appropriate data value types are used. For instance, codes are typically integers and are coded as such.
Please note that the UTC times are in ISO 8601 standard.
At times, the API will not return values for every data field. This can be due to a variety of reasons and no explanation or warning is provided by the API. NA values simply imply that no value was returned by the API for the respective data field.