---
title: "nasapower"
author: "Adam H. Sparks"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{nasapower}
  %\VignetteEngine{knitr::rmarkdown_notangle}
  %\VignetteEncoding{UTF-8}
---



## Introduction

{nasapower} aims to make it quick and easy to automate downloading NASA [POWER](https://power.larc.nasa.gov) global meteorology, surface solar energy and climatology data  data in your R session as a tidy data frame for analysis and use in modelling or other purposes using `get_power()`.
POWER (Prediction Of Worldwide Energy Resource) data are freely available for download through a web interface with a spatial resolution of 0.5 x 0.625 degree latitude and longitude for meteorology and  1 x 1 degree latitude and longitude for solar parameters with various temporal resolutions depending on the POWER parameter and community.

## Using get_power() to fetch POWER data

The `get_power()` function has eight possible arguments and returns a data frame with a metadata header in the current R session.

### Example fetching daily data for a single point

Fetch daily "AG" community temperature, relative humidity and precipitation for January 1985 for Kingsthorpe, Queensland, Australia.


``` r
library("nasapower")
daily_single_ag <- get_power(
  community = "ag",
  lonlat = c(151.81, -27.48),
  pars = c("RH2M", "T2M", "PRECTOTCORR"),
  dates = c("1985-01-01", "1985-01-31"),
  temporal_api = "daily"
)

daily_single_ag
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> 
#> ── NASA/POWER Source Native Resolution Daily Data  ──────────────────────────────────────────────────────────────────────────────────────────────────────────
#> Dates (month/day/year): 01/01/1985 through 01/31/1985 in LST
#> Location: latitude -27.48 longitude 151.81
#> elevation from MERRA-2: Average for 0.5 x 0.625 degree lat/lon region = 442.77 meters
#> The value for missing source data that cannot be computed or is outside of the sources availability range: NA
#> parameter(s):
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> Parameters:
#> RH2M MERRA-2 Relative Humidity at 2 Meters (%) ; T2M MERRA-2 Temperature at 2 Meters (C) ; PRECTOTCORR MERRA-2 Precipitation Corrected (mm/day)
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> # Tibble (class tbl_df) 10 x 31:
#> # (Showing rows 1 - 20 out of 31)
#>   │LON  │LAT  │YEAR │MM   │DD   │DOY  │YYYYMMDD  │RH2M │T2M  │PRECTOTCORR
#>   │<dbl>│<dbl>│<dbl>│<int>│<int>│<int>│<oth>     │<dbl>│<dbl>│<dbl>      
#>  1│  152│  -27│ 1985│    1│    1│    1│1985-01-01│   55│   25│       0.90
#>  2│  152│  -27│ 1985│    1│    2│    2│1985-01-02│   42│   29│       0.49
#>  3│  152│  -27│ 1985│    1│    3│    3│1985-01-03│   43│   27│       0.01
#>  4│  152│  -27│ 1985│    1│    4│    4│1985-01-04│   49│   24│       0.05
#>  5│  152│  -27│ 1985│    1│    5│    5│1985-01-05│   55│   26│       1.33
#>  6│  152│  -27│ 1985│    1│    6│    6│1985-01-06│   60│   27│       4.88
#>  7│  152│  -27│ 1985│    1│    7│    7│1985-01-07│   63│   27│      10.72
#>  8│  152│  -27│ 1985│    1│    8│    8│1985-01-08│   71│   25│       9.99
#>  9│  152│  -27│ 1985│    1│    9│    9│1985-01-09│   60│   26│       2.45
#> 10│  152│  -27│ 1985│    1│   10│   10│1985-01-10│   45│   27│       0.48
#> 11│  152│  -27│ 1985│    1│   11│   11│1985-01-11│   43│   26│       0.25
#> 12│  152│  -27│ 1985│    1│   12│   12│1985-01-12│   56│   23│       0.23
#> 13│  152│  -27│ 1985│    1│   13│   13│1985-01-13│   55│   23│       0.00
#> 14│  152│  -27│ 1985│    1│   14│   14│1985-01-14│   62│   22│       0.03
#> 15│  152│  -27│ 1985│    1│   15│   15│1985-01-15│   61│   23│       0.09
#> 16│  152│  -27│ 1985│    1│   16│   16│1985-01-16│   59│   23│       0.06
#> 17│  152│  -27│ 1985│    1│   17│   17│1985-01-17│   54│   26│       0.11
#> 18│  152│  -27│ 1985│    1│   18│   18│1985-01-18│   60│   26│       8.64
#> 19│  152│  -27│ 1985│    1│   19│   19│1985-01-19│   57│   22│       0.63
#> 20│  152│  -27│ 1985│    1│   20│   20│1985-01-20│   59│   22│       0.36
```

### Example fetching daily data for an area

Fetch daily "ag" community relative humidity for south east Queensland region.


``` r
daily_region_ag <- get_power(
  community = "ag",
  lonlat = c(150.5, -28.5, 153.5, -25.5),
  pars = "RH2M",
  dates = c("1985-01-01", "1985-01-02"),
  temporal_api = "daily"
)

daily_region_ag
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> 
#> ── NASA/POWER Source Native Resolution Daily Data  ──────────────────────────────────────────────────────────────────────────────────────────────────────────
#> Dates (month/day/year): 01/01/1985 through 01/02/1985 in LST
#> Location: Regional
#> elevation from MERRA-2: Average for 0.5 x 0.625 degree lat/lon region = na meters
#> The value for missing source data that cannot be computed or is outside of the sources availability range: NA
#> parameter(s):
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> Parameters:
#> RH2M MERRA-2 Relative Humidity at 2 Meters (%)
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> # Tibble (class tbl_df) 8 x 70:
#> # (Showing rows 1 - 20 out of 70)
#>   │LAT  │LON  │YEAR │MM   │DD   │DOY  │YYYYMMDD  │RH2M 
#>   │<dbl>│<dbl>│<dbl>│<int>│<int>│<int>│<oth>     │<dbl>
#>  1│  -28│  151│ 1985│    1│    1│    1│1985-01-01│   42
#>  2│  -28│  151│ 1985│    1│    1│    1│1985-01-01│   42
#>  3│  -28│  152│ 1985│    1│    1│    1│1985-01-01│   54
#>  4│  -28│  152│ 1985│    1│    1│    1│1985-01-01│   62
#>  5│  -28│  153│ 1985│    1│    1│    1│1985-01-01│   66
#>  6│  -28│  151│ 1985│    1│    1│    1│1985-01-01│   45
#>  7│  -28│  151│ 1985│    1│    1│    1│1985-01-01│   47
#>  8│  -28│  152│ 1985│    1│    1│    1│1985-01-01│   55
#>  9│  -28│  152│ 1985│    1│    1│    1│1985-01-01│   58
#> 10│  -28│  153│ 1985│    1│    1│    1│1985-01-01│   62
#> 11│  -28│  151│ 1985│    1│    1│    1│1985-01-01│   46
#> 12│  -28│  151│ 1985│    1│    1│    1│1985-01-01│   49
#> 13│  -28│  152│ 1985│    1│    1│    1│1985-01-01│   55
#> 14│  -28│  152│ 1985│    1│    1│    1│1985-01-01│   58
#> 15│  -28│  153│ 1985│    1│    1│    1│1985-01-01│   66
#> 16│  -27│  151│ 1985│    1│    1│    1│1985-01-01│   48
#> 17│  -27│  151│ 1985│    1│    1│    1│1985-01-01│   50
#> 18│  -27│  152│ 1985│    1│    1│    1│1985-01-01│   57
#> 19│  -27│  152│ 1985│    1│    1│    1│1985-01-01│   63
#> 20│  -27│  153│ 1985│    1│    1│    1│1985-01-01│   73
```

### Example fetching interannual data for an area

Fetch interannual solar cooking parameters for south east Queensland region and create a single data.


``` r
interannual_clrsky <- get_power(
  community = "re",
  lonlat = c(150.5, -28.5, 153.5, -25.5),
  dates = c("1984", "1985"),
  temporal_api = "monthly",
  pars = "CLRSKY_SFC_SW_DWN"
)

interannual_allsky <- get_power(
  community = "re",
  lonlat = c(150.5, -28.5, 153.5, -25.5),
  dates = c("1984", "1985"),
  temporal_api = "monthly",
  pars = "ALLSKY_SFC_SW_DWN"
)

interannual_list <- list(interannual_clrsky, interannual_allsky)

interannual_re <- do.call("rbind", interannual_list)

interannual_re
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> 
#> ── NASA/POWER Source Native Resolution Monthly and Annual  ──────────────────────────────────────────────────────────────────────────────────────────────────
#> Dates (month/day/year): 01/01/1984 through 12/31/1985 in LST
#> Location: Regional
#> Elevation from MERRA-2: Average for 0.5 x 0.625 degree lat/lon region = na meters
#> The value for missing source data that cannot be computed or is outside of the sources availability range: NA
#> Parameter(s):
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> Parameters:
#> CLRSKY_SFC_SW_DWN CERES SYN1deg Clear Sky Surface Shortwave Downward Irradiance (kW-hr/m^2/day)
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> # Tibble (class tbl_df) 17 x 64:
#> # (Showing rows 1 - 20 out of 64)
#>   │PARAMETER        │YEAR │LAT  │LON  │JAN  │FEB  │MAR  │APR  │MAY  │JUN  │JUL  │AUG  │SEP  │OCT  │NOV  │DEC  │ANN  
#>   │<chr>            │<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>
#>  1│CLRSKY_SFC_SW_DWN│ 1984│  -26│  150│  8.5│  8.0│  7.0│  5.8│  4.8│  4.3│  4.6│  5.5│  6.8│  7.7│  8.6│  8.9│  6.7
#>  2│CLRSKY_SFC_SW_DWN│ 1984│  -26│  152│  8.4│  7.9│  7.0│  5.7│  4.7│  4.2│  4.6│  5.5│  6.8│  7.6│  8.5│  8.9│  6.6
#>  3│CLRSKY_SFC_SW_DWN│ 1984│  -26│  152│  8.4│  7.9│  6.9│  5.7│  4.7│  4.2│  4.5│  5.3│  6.6│  7.5│  8.4│  8.7│  6.6
#>  4│CLRSKY_SFC_SW_DWN│ 1984│  -26│  154│  8.3│  7.8│  6.8│  5.6│  4.6│  4.1│  4.3│  5.2│  6.4│  7.4│  8.2│  8.4│  6.4
#>  5│CLRSKY_SFC_SW_DWN│ 1984│  -26│  150│  8.5│  8.0│  7.0│  5.7│  4.7│  4.2│  4.5│  5.5│  6.8│  7.8│  8.6│  8.9│  6.7
#>  6│CLRSKY_SFC_SW_DWN│ 1984│  -26│  152│  8.6│  8.0│  7.0│  5.7│  4.7│  4.2│  4.5│  5.4│  6.8│  7.7│  8.6│  9.0│  6.7
#>  7│CLRSKY_SFC_SW_DWN│ 1984│  -26│  152│  8.4│  8.0│  6.9│  5.6│  4.6│  4.1│  4.4│  5.4│  6.7│  7.6│  8.5│  8.9│  6.6
#>  8│CLRSKY_SFC_SW_DWN│ 1984│  -26│  154│  8.3│  7.8│  6.8│  5.5│  4.5│  4.0│  4.2│  5.2│  6.4│  7.4│  8.4│  8.7│  6.4
#>  9│CLRSKY_SFC_SW_DWN│ 1984│  -28│  150│  8.6│  8.0│  7.0│  5.6│  4.6│  4.0│  4.3│  5.4│  6.8│  7.8│  8.8│  8.9│  6.7
#> 10│CLRSKY_SFC_SW_DWN│ 1984│  -28│  152│  8.5│  8.0│  6.9│  5.6│  4.6│  4.0│  4.3│  5.3│  6.7│  7.7│  8.6│  8.9│  6.6
#> 11│CLRSKY_SFC_SW_DWN│ 1984│  -28│  152│  8.5│  7.9│  6.8│  5.5│  4.5│  4.0│  4.2│  5.2│  6.6│  7.6│  8.5│  8.8│  6.5
#> 12│CLRSKY_SFC_SW_DWN│ 1984│  -28│  154│  8.3│  7.8│  6.7│  5.5│  4.4│  3.9│  4.1│  5.1│  6.3│  7.5│  8.4│  8.5│  6.4
#> 13│CLRSKY_SFC_SW_DWN│ 1984│  -28│  150│  8.6│  8.0│  6.9│  5.6│  4.5│  3.9│  4.2│  5.2│  6.7│  7.7│  8.7│  9.0│  6.6
#> 14│CLRSKY_SFC_SW_DWN│ 1984│  -28│  152│  8.6│  8.0│  6.9│  5.6│  4.5│  3.9│  4.3│  5.3│  6.7│  7.7│  8.7│  9.0│  6.6
#> 15│CLRSKY_SFC_SW_DWN│ 1984│  -28│  152│  8.5│  7.9│  6.8│  5.5│  4.5│  3.9│  4.2│  5.2│  6.7│  7.6│  8.6│  9.0│  6.5
#> 16│CLRSKY_SFC_SW_DWN│ 1984│  -28│  154│  8.4│  7.8│  6.7│  5.4│  4.3│  3.8│  4.0│  5.0│  6.4│  7.5│  8.4│  9.0│  6.4
#> 17│CLRSKY_SFC_SW_DWN│ 1985│  -26│  150│  9.1│  8.3│  7.2│  6.0│  4.8│  4.3│  4.5│  5.4│  6.9│  7.9│  8.6│  8.9│  6.8
#> 18│CLRSKY_SFC_SW_DWN│ 1985│  -26│  152│  9.1│  8.3│  7.1│  5.9│  4.7│  4.3│  4.5│  5.4│  6.8│  7.8│  8.5│  8.9│  6.8
#> 19│CLRSKY_SFC_SW_DWN│ 1985│  -26│  152│  9.0│  8.1│  6.9│  5.8│  4.7│  4.2│  4.5│  5.3│  6.7│  7.6│  8.4│  8.7│  6.6
#> 20│CLRSKY_SFC_SW_DWN│ 1985│  -26│  154│  8.4│  7.8│  6.8│  5.7│  4.6│  4.2│  4.4│  5.2│  6.5│  7.5│  8.1│  8.5│  6.5
```

### Example fetching climatology data

Climatology data can be retrieved for point or regional areas as demonstrated previously.
Change the `temporal_api` value to "climatology" to get these data.

Fetch "ag" climatology for temperature and relative humidity for Kingsthorpe, Queensland, Australia.


``` r
climatology_ag <- get_power(
  community = "ag",
  pars = c("T2M", "RH2M"),
  lonlat = c(151.81, -27.48),
  temporal_api = "climatology"
)

climatology_ag
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> 
#> ── NASA/POWER Source Native Resolution Climatology in LST ───────────────────────────────────────────────────────────────────────────────────────────────────
#> 20-year Meteorological and Solar Monthly & Annual Climatologies (January 2001 - December 2020)
#> Location: Latitude -27.48 Longitude 151.81
#> Elevation from MERRA-2: Average for 0.5 x 0.625 degree lat/lon region = 442.77 meters
#> The value for missing source data that cannot be computed or is outside of the sources availability range: NA
#> Parameter(s):
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> Parameters:
#> RH2M MERRA-2 Relative Humidity at 2 Meters (%) ; T2M MERRA-2 Temperature at 2 Meters (C) ; Message(s): ; The requested parameters are retrieved from a
#> pre-computed climatological period (January 2001 - December 2020)
#> ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> # Tibble (class tbl_df) 16 x 2:
#>  │LON  │LAT  │PARAMETER│JAN  │FEB  │MAR  │APR  │MAY  │JUN  │JUL  │AUG  │SEP  │OCT  │NOV  │DEC  │ANN  
#>  │<dbl>│<dbl>│<chr>    │<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>│<dbl>
#> 1│  152│  -27│RH2M     │   65│   70│   71│   70│   69│   75│   70│   63│   60│   59│   60│   63│   66
#> 2│  152│  -27│T2M      │   25│   24│   22│   19│   15│   13│   12│   13│   17│   20│   22│   24│   19
```

_Note_ the associated metadata in the data frame header are not saved if the data are exported to a file format other than an R data format, _e.g._, .Rdata, .rda or .rds.

## Interrogating the API for available parameters

The POWER API offers functionality to get detailed information on any parameter offered or all parameters that are offered for a given community and temporal API.
This can be used to find available parameter names and definitions for each community and temporal API.

Fetch the complete available information for the temperature at 2 metres above the Earth's surface, T2M.


``` r
query_parameters(pars = "T2M")
#> $T2M
#> $T2M$temporal
#>                                                                               HOURLY
#> 1                                                            Temperature at 2 Meters
#> 2 The average air (dry bulb) temperature at 2 meters above the surface of the earth.
#> 3                                                                         AG, RE, SB
#> 4                                                                              FALSE
#>                                                                                DAILY
#> 1                                                            Temperature at 2 Meters
#> 2 The average air (dry bulb) temperature at 2 meters above the surface of the earth.
#> 3                                                                         AG, RE, SB
#> 4                                                                              FALSE
#>                                                                              MONTHLY
#> 1                                                            Temperature at 2 Meters
#> 2 The average air (dry bulb) temperature at 2 meters above the surface of the earth.
#> 3                                                                         AG, RE, SB
#> 4                                                                              FALSE
#>                                                                          CLIMATOLOGY
#> 1                                                            Temperature at 2 Meters
#> 2 The average air (dry bulb) temperature at 2 meters above the surface of the earth.
#> 3                                                                         AG, RE, SB
#> 4                                                                              FALSE
#> 
#> $T2M$type
#> [1] "METEOROLOGY"
```

Fetch complete temporal and community specific attribute information for "T2M" in the "ag" community for the "hourly" temporal API.


``` r
query_parameters(pars = "T2M",
                 community = "ag",
                 temporal_api = "hourly")
#> $T2M
#> $T2M$type
#> [1] "METEOROLOGY"
#> 
#> $T2M$temporal
#> [1] "HOURLY"
#> 
#> $T2M$source
#> [1] "SOURCE"
#> 
#> $T2M$community
#> [1] "AG"
#> 
#> $T2M$calculated
#> [1] FALSE
#> 
#> $T2M$inputs
#> NULL
#> 
#> $T2M$units
#> [1] "C"
#> 
#> $T2M$name
#> [1] "Temperature at 2 Meters"
#> 
#> $T2M$definition
#> [1] "The average air (dry bulb) temperature at 2 meters above the surface of the earth."
```

## A Note on API Throttling

The POWER API endpoints limit queries to prevent overloads due to repetitive and rapid requests.
If you find that the API is throttling your queries, I suggest that you investigate the use of `limit_rate()` from [_ratelimitr_](https://cran.r-project.org/package=ratelimitr) to create self-limiting functions that will respect the rate limits that the API has in place.
It is best to check the [POWER website](https://power.larc.nasa.gov/docs/services/api/#rate-limiting) for the latest rate limits as they differ between temporal APIs and may change over time as the project matures.

## References

<https://power.larc.nasa.gov>

<https://power.larc.nasa.gov/docs/methodology/>
