The {RClimacell} package provides four high-level wrapper functions to retrieve the Core layer data fields from the Climacell API version 4 using the Timeline Interface:
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 interfaceAll of the high level wrapper functions consist of the following 5 arguments:
api_keylatlongtimestepstart_timeend_timeA valid API key from Climacell is required to use any of the functions within this package. Obtaining an API key is free and is limited to 1000 calls per day when using the CORE layers. By default, the functions will try to find an environment variable (within the .Renviron file) called “CLIMACELL_API”. If found, it will automatically use it. If you have a different environment variable name for the API key, you will need to explicity retrieve the environment variable and may not omit it from the function call.
The latitude and longitude values are required and the functions will not work without them. Both of these values must be decimal values and cannot be in degrees, minutes, seconds, UTM, etc.
This argument identifies what interval the data must be in. For instance, if you are looking for daily data, then you’ll want to set the timestep to ‘1d’. This field is limited to the following values only:
| 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 |
If a timestep of ‘current’ is used, then the start and end times will not be used.
This field must be identified correctly or the functions will not work. The only exception is the climacell_celestial() function since it can ONLY use a timestep of ‘1d’ (per the requirements of the API).
The start and end times help define the constraints around the data retrieval from the API. The start time is required; however, if it is missing, the functions will automatically use the current system time. If the system time is not reflective of the actual time, then the functions may not work as expected.
The end time is optional due to the error handling built in to the functions. Typically, omitting the end time value will yield a warning (which can be safely ignored) and the function will create an end time (internally) that will return the maximum results based on the timestep value chosen.
Detailed information on any of the variables returned by the functions can be found on the CORE Layers page.
The climacell_temperature() function returns the following variables:
start_time: the time of the reading. This value increments based on the timestep interval chosen (UTC).temp_c: the temperature at the time of reading (degrees Celsius).temp_feel_c: what the temperature actually feels like (degrees Celsius).dewpoint: the dewpoint at the time of the reading (degrees Celsius).humidity: the humidity at the time of the reading (%).
library(dplyr)
library(RClimacell)
temperature_1m <- RClimacell::climacell_temperature(
api_key = Sys.getenv('CLIMACELL_API'),
timestep = '1m',
lat = 41.878876,
long = -87.635918,
start_time = Sys.time() - lubridate::hours(5),
end_time = NULL)
dplyr::glimpse(temperature_1m) #> Rows: 661
#> Columns: 5
#> $ start_time <dttm> 2021-03-22 15:20:00, 2021-03-22 15:21:00, 2021-03-22 15:2…
#> $ temp_c <dbl> 14.44, 14.44, 14.44, 14.44, 14.44, 14.44, 14.55, 14.66, 14…
#> $ temp_feel_c <dbl> 12.63, 12.62, 12.62, 12.62, 12.62, 12.63, 12.66, 12.70, 12…
#> $ dewpoint <dbl> 1.60, 1.53, 1.46, 1.39, 1.32, 1.26, 1.36, 1.46, 1.56, 1.66…
#> $ humidity <dbl> 42.00, 41.80, 41.60, 41.40, 41.20, 41.00, 41.00, 41.00, 41…The climacell_precip() function returns the following variables:
start_time: the time of the reading. This value increments based on the timestep interval chosen (UTC).precipitation_intensity: amount of precipitation that falls over time, covering the ground in a period of time (mm/hr).precipitation_probability: chance of precipitation that at least some minimum quantity of precipitation will occur within a specified forecast period and location (%).precipitation_type_code: types of precipitation often include the character or phase of the precipitation which is falling to ground level (code number returned by API).precipitation_type_desc: long description of the precipitation_type_code.visibility: measure of the distance at which an object or light can be clearly discerned (km).pressure_surface_level: force exerted against a surface by the weight of the air above the surface (at the surface level) (hPa).pressure_sea_level: force exerted against a surface by the weight of the air above the surface (at the mean sea level) (hPA).cloud_cover: fraction of the sky obscured by clouds when observed from a particular location (%)cloud_base: lowest altitude of the visible portion of a cloud (above ground level) (km)cloud_ceiling: highest altitude of the visible portion of a cloud (above ground level) (km)solar_ghi: amount of shortwave radiation received from above by a surface horizontal to the ground (W/m^2)weather_code: code number that conveys the most prominent weather condition (code number returned by API)weather_desc: long description of the weather_codeDepending on the actual weather forecasts and conditions, not all of the variables will have values. If any column has an NA value, it simply means that the API did not return a value for that specific variable for that specific start time.
library(dplyr)
library(RClimacell)
precip_1h <- RClimacell::climacell_precip(
api_key = Sys.getenv('CLIMACELL_API'),
timestep = '1h',
lat = 41.878876,
long = -87.635918,
start_time = Sys.time() - lubridate::hours(5),
end_time = NULL)
dplyr::glimpse(precip_1h) #> Rows: 113
#> Columns: 14
#> $ start_time <dttm> 2021-03-22 15:20:00, 2021-03-22 16:20:00, 2…
#> $ precipitation_intensity <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,…
#> $ precipitation_probability <dbl> 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,…
#> $ precipitation_type_code <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,…
#> $ precipitation_type_desc <chr> "Rain", "Rain", "Rain", "Rain", "Rain", "Rai…
#> $ visibility <dbl> 10, 10, 10, 10, 10, 10, 16, 16, 16, 16, 16, …
#> $ pressure_surface_level <dbl> 1000.86, 999.67, 999.29, 998.89, 998.39, 998…
#> $ pressure_sea_level <dbl> 1018.22, 1018.07, 1016.67, 1016.24, 1015.52,…
#> $ cloud_cover <dbl> 33.31, 33.31, 83.31, 33.31, 66.69, 0.00, 7.8…
#> $ cloud_base <dbl> NA, NA, NA, NA, NA, NA, NA, NA, 1.57, 1.06, …
#> $ cloud_ceiling <dbl> NA, NA, NA, NA, NA, NA, NA, NA, 9.59, 9.22, …
#> $ solar_ghi <dbl> 354.13, 453.50, 126.88, 526.69, 252.81, 632.…
#> $ weather_code <dbl> 1100, 1100, 1001, 1100, 1102, 1000, 1000, 11…
#> $ weather_desc <chr> "Mostly Clear", "Mostly Clear", "Cloudy", "M…The climacell_wind() function returns the following variables:
start_time: the time of the reading. This value increments based on the timestep interval chosen (UTC).wind_speed: atmospheric quantity caused by air moving from high to low pressure, usually due to changes in temperature (at 10m) (m/s).wind_gust: maximum brief increase in the speed of the wind, usually less than 20 seconds (at 10m) (m/s).wind_direction: direction from which it originates, measured in degrees clockwise from due north (at 10m) (degrees)Depending on the actual weather forecasts and conditions, not all of the variables will have values. If any column has an NA value, it simply means that the API did not return a value for that specific variable for that specific start time.
library(dplyr)
library(RClimacell)
wind_1m <- RClimacell::climacell_wind(
api_key = Sys.getenv('CLIMACELL_API'),
timestep = '1m',
lat = 41.878876,
long = -87.635918,
start_time = Sys.time() - lubridate::hours(5),
end_time = NULL)
dplyr::glimpse(wind_1m)#> Rows: 661
#> Columns: 4
#> $ start_time <dttm> 2021-03-22 15:20:00, 2021-03-22 15:21:00, 2021-03-22 1…
#> $ wind_speed <dbl> 0.89, 0.98, 1.07, 1.16, 1.25, 1.34, 1.29, 1.25, 1.20, 1…
#> $ wind_gust <dbl> 3.13, 3.03, 2.94, 2.85, 2.76, 2.68, 2.72, 2.76, 2.81, 2…
#> $ wind_direction <dbl> 246, 246, 246, 250, 250, 250, 250, 250, 250, 250, 214, …The climacell_celestial() function returns the following variables:
Note that the timestep value for this function can only be ‘1d’.
library(dplyr)
library(RClimacell)
celestial_1d <- RClimacell::climacell_celestial(
api_key = Sys.getenv('CLIMACELL_API'),
timestep = '1d',
lat = 41.878876,
long = -87.635918,
start_time = Sys.time(),
end_time = NULL)
dplyr::glimpse(celestial_1d)#> Rows: 15
#> Columns: 5
#> $ start_time <dttm> 2021-03-22 11:00:00, 2021-03-23 11:00:00, 2021…
#> $ sunrise_time <dttm> 2021-03-22 11:50:00, 2021-03-23 11:48:20, 2021…
#> $ sunset_time <dttm> 2021-03-23 00:05:00, 2021-03-24 00:06:40, 2021…
#> $ moon_phase_code <int> 2, 2, 2, 2, 3, 4, 4, 4, 5, 5, 5, 6, 6, 6, 6
#> $ moon_phase_description <chr> "First Quarter", "First Quarter", "First Quarte…The climacell_core() function returns all of the variables in the aforementioned function calls. Note that the timestep must be equal to ‘1d’ if any of the celestial fields (e.g., moon phase, sunrise time, sunset time) are desired.
library(dplyr)
library(RClimacell)
core_1m <- RClimacell::climacell_core(
api_key = Sys.getenv('CLIMACELL_API'),
timestep = '1d',
lat = 41.878876,
long = -87.635918,
start_time = Sys.time(),
end_time = NULL)
dplyr::glimpse(core_1m)#> Rows: 661
#> Columns: 21
#> $ start_time <dttm> 2021-03-22 15:20:00, 2021-03-22 15:21:00, 2…
#> $ temp_c <dbl> 14.44, 14.44, 14.44, 14.44, 14.44, 14.44, 14…
#> $ temp_feel_c <dbl> 12.63, 12.62, 12.62, 12.62, 12.62, 12.63, 12…
#> $ weather_code <dbl> 1100, 1100, 1100, 1100, 1100, 1100, 1100, 11…
#> $ weather_desc <chr> "Mostly Clear", "Mostly Clear", "Mostly Clea…
#> $ dewpoint <dbl> 1.60, 1.53, 1.46, 1.39, 1.32, 1.26, 1.36, 1.…
#> $ humidity <dbl> 42.00, 41.80, 41.60, 41.40, 41.20, 41.00, 41…
#> $ wind_speed <dbl> 0.89, 0.98, 1.07, 1.16, 1.25, 1.34, 1.29, 1.…
#> $ wind_direction <dbl> 246, 246, 246, 250, 250, 250, 250, 250, NA, …
#> $ wind_gust <dbl> 3.13, 3.03, 2.94, 2.85, 2.76, 2.68, 2.72, 2.…
#> $ solar_ghi <dbl> 354.13, 354.12, 354.12, 354.12, 354.12, 354.…
#> $ precipitation_type_code <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,…
#> $ precipitation_type_desc <chr> "Rain", "Rain", "Rain", "Rain", "Rain", "Rai…
#> $ precipitation_probability <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,…
#> $ precipitation_intensity <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,…
#> $ cloud_cover <dbl> 33.31, 33.31, 33.31, 33.31, 33.31, 33.31, 33…
#> $ cloud_base <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
#> $ cloud_ceiling <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
#> $ visibility <dbl> 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, 10, …
#> $ pressure_surface_level <dbl> 1000.86, 1000.83, 1000.81, 1000.78, 1000.76,…
#> $ pressure_sea_level <dbl> 1018.22, 1018.21, 1018.21, 1018.21, 1018.21,…Using a timestep of ‘1d’ results in the following:
#> Rows: 15
#> Columns: 25
#> $ start_time <dttm> 2021-03-22 11:00:00, 2021-03-23 11:00:00, 2…
#> $ temp_c <dbl> 18.72, 12.37, 14.18, 7.26, 2.57, 4.03, 3.46,…
#> $ temp_feel_c <dbl> 18.72, 12.37, 14.18, 7.26, -0.81, 1.18, -0.5…
#> $ weather_code <dbl> 1102, 4200, 4000, 5001, 5001, 5100, 5001, 40…
#> $ weather_desc <chr> "Mostly Cloudy", "Light Rain", "Drizzle", "F…
#> $ dewpoint <dbl> 5.20, 10.49, 10.07, 4.94, -1.81, 3.36, 2.56,…
#> $ humidity <dbl> 62.11, 96.98, 97.27, 92.32, 74.93, 94.92, 94…
#> $ wind_speed <dbl> 6.46, 9.77, 10.72, 9.75, 7.94, 6.92, 9.87, 1…
#> $ wind_direction <dbl> 192.44, 143.24, 224.78, 61.08, 148.06, 71.76…
#> $ wind_gust <dbl> 8.74, 13.92, 15.36, 12.24, 9.84, 10.74, 12.8…
#> $ solar_ghi <dbl> 527.65, 459.38, 552.39, 557.51, 651.40, 137.…
#> $ precipitation_type_code <dbl> 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 1, 1, 2, 2, 2
#> $ precipitation_type_desc <chr> "Rain", "Rain", "Rain", "Snow", "Snow", "Sno…
#> $ precipitation_probability <dbl> 0, 75, 25, 55, 20, 35, 30, 0, 5, 5, 55, 55, …
#> $ precipitation_intensity <dbl> 0.0000, 2.7397, 0.3605, 0.4792, 0.0222, 0.57…
#> $ cloud_cover <dbl> 100.00, 100.00, 100.00, 100.00, 100.00, 100.…
#> $ cloud_base <dbl> 7.92, 2.35, 5.70, 5.86, 1.09, 2.18, 0.91, 4.…
#> $ cloud_ceiling <dbl> 9.59, 8.88, 7.31, 8.26, 1.26, 3.35, 2.21, 2.…
#> $ visibility <dbl> 16.00, 16.00, 16.00, 24.14, 24.14, 24.14, 24…
#> $ pressure_surface_level <dbl> 1001.39, 996.92, 990.88, 992.93, 1001.49, 99…
#> $ pressure_sea_level <dbl> 1014.64, 1003.36, 1003.40, 1011.24, 1015.15,…
#> $ sunrise_time <dttm> 2021-03-22 11:50:00, 2021-03-23 11:48:20, 20…
#> $ sunset_time <dttm> 2021-03-23 00:05:00, 2021-03-24 00:06:40, 2…
#> $ moon_phase_code <dbl> 2, 2, 2, 2, 3, 4, 4, 4, 5, 5, 5, 6, 6, 6, 6
#> $ moon_phase_description <chr> "First Quarter", "First Quarter", "First Qu…