---
title: "Introduction"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{cc1_intro}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup, echo=FALSE}
library(RClimacell)
```

The {RClimacell} R package provides a high level wrapper around the Climacell version 4 API using the [Timeline Interface](https://docs.climacell.co/reference/timeline-overview). Currently, the {RClimacell} package only provides access to the [Core](https://docs.climacell.co/reference/data-layers-core) data fields using the [Timeline Interface](https://docs.climacell.co/reference/timeline-overview). 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](https://docs.climacell.co/reference/data-layers-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](https://www.climacell.co/weather-api/) 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](https://docs.climacell.co/reference/data-layers-overview).

### 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](https://en.wikipedia.org/wiki/ISO_8601).

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