Usage

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:

Arguments

All of the high level wrapper functions consist of the following 5 arguments:

API Key

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

Latitude & Longitude

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.

Timestep

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

Start & End Times

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.

Usage

Detailed information on any of the variables returned by the functions can be found on the CORE Layers page.

Temperature

The climacell_temperature() function returns the following variables:

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…

Precipitation

The climacell_precip() function returns the following variables:

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)

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…

Wind

The climacell_wind() function returns the following variables:

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, …

Celestial

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…

Core

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…