Introduction
In RClimacell: R Wrapper for the 'Climacell' API

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message = FALSE,
  fig.height = 8,
  fig.width = 5
)

library(RClimacell)

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:

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.