Title: | NASA POWER API Client |
---|---|
Description: | An API client for NASA POWER global meteorology, surface solar energy and climatology data API. POWER (Prediction Of Worldwide Energy Resources) data are freely available for download with varying spatial resolutions dependent on the original data and with several temporal resolutions depending on the POWER parameter and community. This work is funded through the NASA Earth Science Directorate Applied Science Program. For more on the data themselves, the methodologies used in creating, a web- based data viewer and web access, please see <https://power.larc.nasa.gov/>. |
Authors: | Adam H. Sparks [aut, cre] |
Maintainer: | Adam H. Sparks <[email protected]> |
License: | MIT + file LICENSE |
Version: | 4.2.1 |
Built: | 2024-08-30 00:48:41 UTC |
Source: | https://github.com/ropensci/nasapower |
Get POWER global meteorology and surface solar energy
climatology data and return a tidy data frame tibble::tibble()
object. All options offered by the official POWER API
are supported. Requests are formed to submit one request per point.
There is no need to make synchronous requests for multiple parameters for
a single point or regional request. See section on “Rate Limiting”
for more.
get_power( community = c("ag", "re", "sb"), pars, temporal_api = c("daily", "monthly", "hourly", "climatology"), lonlat, dates = NULL, site_elevation = NULL, wind_elevation = NULL, wind_surface = NULL, time_standard = c("LST", "UTC") )
get_power( community = c("ag", "re", "sb"), pars, temporal_api = c("daily", "monthly", "hourly", "climatology"), lonlat, dates = NULL, site_elevation = NULL, wind_elevation = NULL, wind_surface = NULL, time_standard = c("LST", "UTC") )
community |
A case-intensive character vector providing community name: “AG”, “RE” or “SB”. See argument details for more. |
pars |
case-intensive character vector of solar, meteorological or
climatology parameters to download. When requesting a single point of x, y
coordinates, a maximum of twenty (20) |
temporal_api |
A case-intensive character vector providing the temporal API end-point for data being queried, supported values are “hourly”, “daily”, “monthly” or “climatology”. Defaults to “daily”. See argument details for more. |
lonlat |
A numeric vector of geographic coordinates for a cell or region entered as x, y (longitude, latitude) coordinates. See argument details for more. |
dates |
A character vector of start and end dates in that order, |
site_elevation |
A user-supplied value for elevation at a single point
in metres. If provided this will return a corrected atmospheric pressure
value adjusted to the elevation provided. Only used with |
wind_elevation |
A user-supplied value for elevation at a single point
in metres. Wind Elevation values in Meters are required to be between 10m
and 300m. Only used with |
wind_surface |
A user-supplied wind surface for which the corrected
wind-speed is to be supplied. See |
time_standard |
POWER provides two different time standards:
|
A data frame as a POWER.Info
class, an extension of the
tibble::tibble, object of POWER data including location, dates
(not including “climatology”) and requested parameters. A decorative
header of metadata is included in this object.
There are three valid values, one must be supplied. This will affect the units of the parameter and the temporal display of time series data.
Provides access to the Agroclimatology Archive, which contains industry-friendly parameters formatted for input to crop models.
Provides access to the Sustainable Buildings Archive, which contains industry-friendly parameters for the buildings community to include parameters in multi-year monthly averages.
Provides access to the Renewable Energy Archive, which contains parameters specifically tailored to assist in the design of solar and wind powered renewable energy systems.
temporal_api
There are four valid values.
The hourly average of pars
by hour, day, month and year,
the time zone is LST by default.
The daily average of pars
by day, month and year.
The monthly average of pars
by month and year.
Provide parameters as 22-year climatologies (solar) and 30-year climatologies (meteorology); the period climatology and monthly average, maximum, and/or minimum values.
lonlat
To get a specific cell, 1/2 x 1/2 degree, supply a
length-two numeric vector giving the decimal degree longitude and latitude
in that order for data to download,
e.g., lonlat = c(-179.5, -89.5)
.
To get a region, supply a length-four numeric
vector as lower left (lon, lat) and upper right (lon, lat) coordinates,
e.g., lonlat = c(xmin, ymin, xmax, ymax)
in that order for a
given region, e.g., a bounding box for the south western corner of
Australia: lonlat = c(112.5, -55.5, 115.5, -50.5)
. *Maximum area
processed is 4.5 x 4.5 degrees (100 points).
To get global coverage for “climatology”,
supply “global” while also specifying “climatology” for the
temporal_api
.
dates
if one date only is provided, it
will be treated as both the start date and the end date and only a single
day's values will be returned, e.g., dates = "1983-01-01"
. When
temporal_api
is set to “MONTHLY”, use only two year values (YYYY),
e.g. dates = c(1983, 2010)
. This argument should not be used when
temporal_api
is set to “climatology” and will be ignored if set.
wind_surface
There are 17 surfaces that may be used for corrected wind-speed values using the following equation:
Valid surface types are described here.
35-m broadleaf-evergreen trees (70% coverage)
20-m broadleaf-deciduous trees (75% coverage)
20-m broadleaf and needleleaf trees (75% coverage)
17-m needleleaf-evergreen trees (75% coverage)
14-m needleleaf-deciduous trees (50% coverage)
Savanna:18-m broadleaf trees (30%) & groundcover
0.6-m perennial groundcover (100%)
0.5-m broadleaf shrubs (variable %) & groundcover
0.5-m broadleaf shrubs (10%) with bare soil
Tundra: 0.6-m trees/shrubs (variable %) & groundcover
Rough bare soil
Crop: 20-m broadleaf-deciduous trees (10%) & wheat
Rough glacial snow/ice
Smooth sea ice
Open water
Airport: flat ice/snow
Airport: flat rough grass
The POWER API endpoints limit
queries to prevent server 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 to
create self-limiting functions that will respect the rate limits that the
API has in place. It is considered best practice to check the
POWER website for the
latest rate limits as they differ between temporal APIs and may
change over time as the project matures.
The associated metadata shown in the decorative header are not saved if the data are exported to a file format other than a native R data format, e.g., .Rdata, .rda or .rds.
Adam H. Sparks [email protected]
https://power.larc.nasa.gov/docs/methodology/ https://power.larc.nasa.gov
# Fetch daily "AG" community temperature, relative humidity and # precipitation for January 1 1985 at Kingsthorpe, Queensland, Australia ag_d <- get_power( community = "AG", lonlat = c(151.81, -27.48), pars = c("RH2M", "T2M", "PRECTOTCORR"), dates = "1985-01-01", temporal_api = "daily" ) ag_d # Fetch single point climatology for air temperature ag_c_point <- get_power( community = "AG", pars = "T2M", c(151.81, -27.48), temporal_api = "climatology" ) ag_c_point # Fetch interannual solar cooking parameters for a given region sse_i <- get_power( community = "RE", lonlat = c(112.5, -55.5, 115.5, -50.5), dates = c("1984", "1985"), temporal_api = "monthly", pars = c("CLRSKY_SFC_SW_DWN", "ALLSKY_SFC_SW_DWN") ) sse_i
# Fetch daily "AG" community temperature, relative humidity and # precipitation for January 1 1985 at Kingsthorpe, Queensland, Australia ag_d <- get_power( community = "AG", lonlat = c(151.81, -27.48), pars = c("RH2M", "T2M", "PRECTOTCORR"), dates = "1985-01-01", temporal_api = "daily" ) ag_d # Fetch single point climatology for air temperature ag_c_point <- get_power( community = "AG", pars = "T2M", c(151.81, -27.48), temporal_api = "climatology" ) ag_c_point # Fetch interannual solar cooking parameters for a given region sse_i <- get_power( community = "RE", lonlat = c(112.5, -55.5, 115.5, -50.5), dates = c("1984", "1985"), temporal_api = "monthly", pars = c("CLRSKY_SFC_SW_DWN", "ALLSKY_SFC_SW_DWN") ) sse_i
Queries the POWER API returning detailed information on
available parameter groupings grouped by community followed by temporal
API or if global = TRUE
, grouped by climatology, then by the
available types of parameters.
query_groupings(global = FALSE)
query_groupings(global = FALSE)
global |
Boolean; should the query return global parameter groupings and
attribute information? Defaults to |
A list object of information on parameter groupings in the POWER API.
Adam H. Sparks, [email protected]
# fetch groupings for parameters query_groupings() # fetch groupings for global parameters query_groupings(global = TRUE)
# fetch groupings for parameters query_groupings() # fetch groupings for global parameters query_groupings(global = TRUE)
Queries the POWER API returning detailed information on
available parameters. For a list of all available parameters, use
parameters
query_parameters( community = NULL, pars = NULL, temporal_api = NULL, metadata = FALSE )
query_parameters( community = NULL, pars = NULL, temporal_api = NULL, metadata = FALSE )
community |
An optional character vector providing community name: “ag”, “sb” or “re”. |
pars |
An optional character string of a single solar, meteorological or climatology parameter to query. If none is provided, all are returned. |
temporal_api |
An optional character vector indicating the temporal API end-point for data being queried, supported values are “hourly”, “daily”, “monthly” or “climatology”. |
metadata |
|
A list object of information for the requested parameter(s) (if requested), community(ies) and temporal API(s).
temporal_api
There are four valid values.
The hourly average of pars
by hour, day, month and year.
The daily average of pars
by day, month and year.
The monthly average of pars
by month and year.
Provide parameters as 22-year climatologies (solar) and 30-year climatologies (meteorology); the period climatology and monthly average, maximum, and/or minimum values.
Adam H. Sparks, [email protected]
# fetch the complete set of attribute information for "T2M". query_parameters(pars = "T2M") # fetch complete temporal and community specific attribute information # for "T2M" in the "ag" community for the "hourly" temporal API. query_parameters(pars = "T2M", community = "ag", temporal_api = "hourly") # fetch complete temporal and community specific attribute information # for all parameters in the "ag" community for the "hourly" temporal API. query_parameters(community = "ag", temporal_api = "hourly")
# fetch the complete set of attribute information for "T2M". query_parameters(pars = "T2M") # fetch complete temporal and community specific attribute information # for "T2M" in the "ag" community for the "hourly" temporal API. query_parameters(pars = "T2M", community = "ag", temporal_api = "hourly") # fetch complete temporal and community specific attribute information # for all parameters in the "ag" community for the "hourly" temporal API. query_parameters(community = "ag", temporal_api = "hourly")
Queries the POWER API returning detailed information on all (or just one) wind elevation surface alias and attribute information.
query_surfaces(surface_alias = NULL)
query_surfaces(surface_alias = NULL)
surface_alias |
An optional character vector providing a wind surface alias available from the POWER API. All values are returned if this value is not provided. |
A list object of information for the requested wind surface(s).
Adam H. Sparks, [email protected]
# fetch all wind surface information query_surfaces() # fetch surface information for `airportgrass` query_surfaces(surface_alias = "airportgrass")
# fetch all wind surface information query_surfaces() # fetch surface information for `airportgrass` query_surfaces(surface_alias = "airportgrass")