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.

Functions

The {RClimacell} package consists of five functions:

  • climacell_temperature: obtains temperature related variables
  • climacell_wind: obtains wind related variables
  • climacell_precip: obtains precipitation related variables
  • climacell_celestial: obtains the sunrise time, sunset time, and the moon phase
  • climacell_core: obtains all of the data fields from the Core data layer using the Timeline interface

Each of these functions returns a formatted tibble in which each column is correctly encoded.

Climacell API Core Data Layer Fields

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()

Limitations

API Call Limits

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).

Date/Time Range Limits

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.

Units

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.

Missing Values

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.