In aWhereAPI/aWhere-R-Library: API calls for aWhere API

knitr::opts_chunk$set(echo = TRUE)

aWhere API Package Vignette

For customers that use R in their statistical modeling work, the aWhereAPI R package helps get you up and running with minimal integration effort. This vignette demonstrates the basic use of the aWhereAPI functions, which simplify the authentication and query construction processes. This package is also particularly helpful for users with limited knowledge of APIs and HTTP syntax.

For additional information or detail, please refer to the complete documentation.

Note: aWhereAPI functions will only return metric units

Installation

Note: You will need to install R and have a working knowledge of its interface prior to installing and using this package.

Note: You will need to have the devtools library installed in R to install the package. Consult devtools documentation if necessary.

Automatically Install

This package can be installed directly from GitHub with the following command:

devtools::install_github("aWhereAPI/aWhere-R-Library")

Manually Install

1. Download this Github repo and keep the aWhere-R-Library-master folder somewhere useful on your computer, such as your Desktop or My Documents.

2. Set the Working Path in R to the location that contains the aWhere-R-Library-master folder. If you placed it on your Desktop the working directory would be something like C:\Users\USERNAME\Desktop. In R, this command is:

   • setwd("C:\Users\USERNAME\Desktop")

3. Run library(devtools) and install("aWhere-R-Library-master") to install and add the library to your environment.

Load the library

library(aWhereAPI)

API Credentials

To get aWhere API keys go to aWhere Developer Community or contact your aWhere Account Executive.

Use credentials directly for token generation

One-time generation of a token can be done with the get_token() function. The resulting token will be automatically stored in your environment for use in API calls (tokens are active for one hour).

get_token("JFKL24JF290FJSKAFDF","jf0afsd9af0a")

Load credentials from a saved file for automatic token generation

Alternatively, the load_credentials() function accesses a text file saved on your computer with your API Key on the first line, and your Secret on the second. This function invokes get_token() so no further work is needed to generate additional access tokens while making calls.

load_credentials("C:/aWhere/credentials/credentials.txt")

___________

API Functions

The Fields & Plantings API

This API provides an interface for customers to register their field locations and information about their plantings in the aWhere Platform. The ID for each field or planting can then be used for quick reference in other functions in the weather data APIs.

---

create_field()

create_field("field_test",40.828200,-100.579500,"farmA")

---

get_fields()

Running this function without any inputs will return a complete list of fields associated with your credentials. If a user wants information relating to a specific field only, they can pass the field ID to the function.

get_fields("field_test")

---

update_field()

At this time only the name or farm ID of a field can be changed after you have created the field. Field IDs and coordinates cannot be changed. This example will change the farm ID of field_test to "TestFarmA" only if the farm ID is currently "farmA":

update_field("field_test", "farmId", "farmA", "farmId", "TestFarmA")

get_fields("field_test")

The function as constructed allows you to use the value of the first named variable (whether farm ID or field name) as the condition for replacing the second named variable.

---

create_planting()

Each field associated with your aWhere API account can be associated with multiple different planting records, specific to a crop and/or growing season. A planting record is only required when using the aWhere API to run models.

Requires both a previously-created field ID and specific information relating to the planting that occurred on that field. This example shows the simplest possible way to create a planting, though a number of other optional parameters are allowed. When complete, the auto-generated planting ID is returned.

pid <- create_planting("field_test", "corn", "2016-07-01")

---

get_planting()

Similar to get_fields(), this function retrieves information about previously-created plantings. This example returns all plantings associated with field_test.

get_planting("field_test")

---

delete_planting()

delete_planting("field_test", pid)

---

The auto-generated planting ID must be supplied as well as the field ID.

___________

Functions relating to the Weather APIs

All weather data requests are requested point by point. The API does not yet have the capacity to download regional data in a single call. The batch jobs system is most useful for those wishing to request a large amount of data (e.g., many hundreds or thousands of points).

---

Daily Observed Weather

By default, you can request up to 30 months of daily historical data, counting back from the present date. For data beyond that, use the Norms API or speak with your aWhere representative for access to more of the daily data archive. The function daily_observed_fields provides the simplest method for retrieving historical data.

daily_observed_fields("field_test", day_start = "2015-07-01", day_end = "2015-07-07")

Users also have the option of using the alternative function daily_observed_latlng to retrieve historical data for a given pair of coordinates.

daily_observed_latlng(latitude = 39.8282, longitude = -98.5795, day_start = "2015-07-01", day_end = "2015-07-07")

---

Forecast

Forecasts are available from the current date plus up to the next 8 days, at multiple temporal resolutions - in 1, 2, 3, 4, 6, 8, 12, or 24-hour summary blocks.

forecasts_fields("field_test", as.character(Sys.Date() + 1), block_size = 4)

forecasts_fields("field_test", day_start = as.character(Sys.Date() + 1), day_end = as.character(Sys.Date() + 3), block_size = 12)

As with daily observed historical data, forecast data can also be called based on latitude, longitude pairs.

forecasts_latlng(latitude = 39.8282, longitude = -98.5795, day_start = as.character(Sys.Date() + 1), block_size = 24)

---

Long Term Norms

The weather norms API allows you to offload the calculation of multi-year averages (minimum 3 years). This eliminates much of the need to download years and years of daily data just to calculate averages. The results also include the standard deviation for each average.

weather_norms_fields(field_id = "field_test", monthday_start = "07-01", monthday_end = "07-07", year_start = 2010, year_end = 2015)

---

Current Conditions

The Current Conditions API returns a snapshot of the weather at a geographic point using the nearest available station. While the data is QA'd before delivery, this service does not do the same advanced processing or interpolation as Daily Observed data.

current_conditions_fields("field_test", "metar-mesonet")

___________

Agronomic Data

Agronomic data can enrich your analysis by providing insight into the agronomic status of a field or crop. aWhere provides derived values like GDD (using a variety of different equations) PET (using the Penman-Monteith Equation), P/PET, and accumulated precipitation, accumulated GDD, accumulated PET, and P/PET over a range of days. The long-term norms for each value can also be queried.

---

Agronomic Values

Calculations can be customized in a number of different ways, consult the API Documentation for more information.

agronomic_values_fields("field_test", day_start = "2016-07-01", day_end = "2016-07-07", accumulation_start_date = "2016-06-01", gdd_method = "modifiedstandard", gdd_base_temp = 10, gdd_min_boundary = 10, gdd_max_boundary = 30)

---

Agronomic Norms

The Agronomic Norms API returns the long-term normals for the agronomic values on any given set of days across any range of years for which we have data. The same customizable parameters for changing the calculation of agronomic values are also available in the norms.

agronomic_norms_fields("field_test", month_day_start = "07-01", month_day_end = "07-07", year_start = 2010, year_end = 2015, gdd_method = "modifiedstandard")

Questions, comments, or requests about this vignette should be directed to [e-mail]

aWhereAPI/aWhere-R-Library documentation built on Nov. 5, 2021, 3:35 a.m.