AgWeather API blueprint:
FORMAT: 1A

# UW-Madison Agricultural Weather Service API


# Group Degree Days

## index [/degree_days]

### List degree days for location [GET /degree_days{?lat,long,start_date,end_date,base,upper,method,units}]

+ Parameters
    + lat: `45.0` (number) - north latitude
    + long: `-90.0` (number) - west longitude
    + start_date: `2020-01-01` (string, optional) - the start date (default: first of year)
    + end_date: `2020-10-10` (string, optional) - end date (default: current date)
    + base: `50` (number, optional) - base temperature, Fahrenheit
    + upper: `86` (number, optional) - upper temperature limit, Fahrenheit
    + method: `sine` (string, optional) - degree day calculation method
    + units: `F` (string, optional) - temperature units (f/F or c/C)

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + status (string)
        + info (object)
            + lat (number) - latitude of the request
            + long (number) - longitude of the request
            + start_date (string) - start date of the request
            + end_date (string) - end date of the request
            + days_requested (number) - number of days requested
            + days_returned (number) - number of days of data returned
            + base (number) - degree days base temp
            + upper (number) - degree days upper cutoff temp
            + method (string) - degree days calculation method
            + units (string) - temperature units
            + min_value (number, nullable) - min daily degree days
            + max_value (number, nullable) - max daily degree days
            + total (number) - total degree days
        + data (array)
            + (object, optional)
                + date (string) - observation date
                + min_temp (number) - daily low temp
                + max_temp (number) - daily high temp
                + value (number) - daily degree day accumulation
                + cumulative_value (number) - cumulative degree days


### Download as csv [GET /degree_days.csv{?lat,long,args}]

+ Parameters
    + lat: `45.0` (number) - north latitude
    + long: `-90.0` (number) - west longitude
    + args (optional) - other params

+ Response 200 (text/csv)


## Degree Day Info [GET /degree_days/info]

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + dd_methods (array)
        + lat_range (array)
        + long_range (array)
        + date_range (array)
        + expected_days (number)
        + actual_days (number)
        + missing_days (array)
        + compute_time (number)


# Group Evapotranspirations

## index [/evapotranspirations]

### List evapotranspiration data for point and date range [GET /evapotranspirations{?lat,long,start_date,end_date}]

+ Parameters
    + lat: `45.0` (number) - north latitude
    + long: `-90.0` (number) - west longitude
    + start_date: `2020-01-01` (string) - start date
    + end_date: `2020-10-10` (string, optional) - end date

+ Response 200 (application/json; charset=utf-8)
    + Attributes (`et/insol/precip index data`)


### Download csv [GET /evapotranspirations.csv{?lat,long,start_date,end_date}]

+ Parameters
    + lat: `45.0` (number) - north latitude
    + long: `-90.0` (number) - west longitude
    + start_date: `2020-01-01` (string) - start date
    + end_date: `2020-10-10` (string, optional) - end date

+ Response 200 (text/csv)


## show [/evapotranspirations/]

### Get evapotranspiration map image url [GET /evapotranspirations/{date}]

Retrieve the ET map for a given date.

+ Parameters
    + date: `2020-01-01` (string) - the desired date

+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + map: `url/for/map.png` (string)


### Show insolation mapimage in browser [GET /evapotranspirations/{date}.png]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (text/html; charset=utf-8)


## Get all evapotranspirations for date [GET /evapotranspirations/all_for_date{?date}]

Retrieve all ET data for the specified date.

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (application/json; charset=utf-8)
    + Attributes (`et/insol/precip all_for_date data`)


## Download csv [GET /evapotranspirations/all_for_date.csv{?date}]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (text/csv)


## Evapotranspiration database info [GET /evapotranspirations/info]

Get parameter ranges available in the database

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + table_cols (array) - column names in database
        + lat_range (array) - min, max
        + long_range (array) - min, max
        + value_range (array) - min, max
        + date_range (array) - min, max
        + actual_days (number) - days in database
        + missing_days (array)
        + compute_time (number)


# Group Insolations

## index [/insolations]

### Get insolation data for point and date range [GET /insolations{?lat,long,start_date,end_date}]

+ Parameters
    + lat: `45.0` (number)
    + long: `-90.0` (number)
    + start_date: `2021-01-01`
    + end_date: `2021-10-10`

+ Response 200 (application/json; charset=utf-8)
    + Attributes (`et/insol/precip index data`)

### Download csv [GET /insolations.csv{?lat,long,start_date,end_date}]

+ Parameters
    + lat: `45.0` (number)
    + long: `-90.0` (number)
    + start_date: `2021-01-01`
    + end_date: `2021-10-10`

+ Response 200 (text/csv)


## show [/insolations/show]

### Get insolation map image url [GET /insolations/{date}]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + map: `path/to/map.png` (string)


### Show insolation map image in browser [GET /insolations/{date}.png]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (text/html; charset=utf-8)


## all_for_date [/insolations/all_for_date]

### Get all insolations for date [GET /insolations/all_for_date{?date}]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (application/json; charset=utf-8)
    + Attributes (`et/insol/precip all_for_date data`)


### Get all insolations for date [GET /insolations/all_for_date.csv{?date}]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (text/csv)


## Insolation database info [GET /insolations/info]

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + table_cols (array) - column names in database
        + lat_range (array) - min, max
        + long_range (array) - min, max
        + value_range (array) - min, max
        + date_range (array) - min, max
        + actual_days (number) - days in database
        + missing_days (array)
        + compute_time (number)


# Group Precipitations

## index [/precips]

### Get precip data for point and date range [GET /precips{?lat,long,start_date,end_date}]

+ Parameters
    + lat: `45.0` (number)
    + long: `-90.0` (number)
    + start_date: `2021-01-01`
    + end_date: `2021-10-10`

+ Response 200 (application/json; charset=utf-8)
    + Attributes (`et/insol/precip index data`)

### Download csv [GET /precips.csv{?lat,long,start_date,end_date}]

+ Parameters
    + lat: `45.0` (number)
    + long: `-90.0` (number)
    + start_date: `2021-01-01`
    + end_date: `2021-10-10`

+ Response 200 (text/csv)


## show [/precips/show]

### Get precip map image url [GET /precips/{date}]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + map: `path/to/map.png` (string)


### Show precip map image in browser [GET /precips/{date}.png]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (text/html; charset=utf-8)


## all_for_date [/precips/all_for_date]

### Get all precips for date [GET /precips/all_for_date{?date}]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (application/json; charset=utf-8)
    + Attributes (`et/insol/precip all_for_date data`)


### Get all precips for date [GET /precips/all_for_date.csv{?date}]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (text/csv)


## Precipitation database info [GET /precips/info]

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + table_cols (array) - column names in database
        + lat_range (array) - min, max
        + long_range (array) - min, max
        + value_range (array) - min, max
        + date_range (array) - min, max
        + actual_days (number) - days in database
        + missing_days (array)
        + compute_time (number)


# Group Weather

## index [/weather]

### Get weather data [GET /weather{?lat,long,start_date,end_date,units}]

Returns weather data for location and date range

+ Parameters
    + lat: `45.0` (number) - north latitude
    + long: `-90.0` (number) - west longitude
    + start_date: `2020-01-01` (string) - start date
    + end_date: `2020-10-10` (string) - end date
    + units: `C` (string) - C or F

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + status (string)
        + info (object)
            + lat (number)
            + long (number)
            + start_date (string)
            + end_date (string)
            + units (string)
            + days_requested (number)
            + days_returned (number)
            + compute_time (number)
        + data (array)
            + (object, optional)
                + date (string)
                + min_temp (number)
                + max_temp (number)
                + avg_temp (number)
                + dew_point (number)
                + pressure (number)
                + hours_rh_over_90 (number)
                + avg_temp_rh_over_90 (number)


### Download csv [GET /weather.csv{?lat,long,start_date,end_date}]

+ Parameters
    + lat: `45.0` (number) - north latitude
    + long: `-90.0` (number) - west longitude
    + start_date: `2020-01-01` (string) - start date
    + end_date: `2020-10-10` (string) - end date

+ Response 200 (text/csv)


## show [/weather/show]

### Get weather map image url [GET /weather/{date}]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + map: `path/to/map.png` (string)

### Show weather map image in browser [GET /weather/{date}.png]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (text/html; charset=utf-8)


## all_for_date [/weather/all_for_date]

### Get all insolations for date [GET /weather/all_for_date{?date,units}]

+ Parameters
    + date: `2020-01-01` (string)
    + units: `C` (string) - C or F

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + status (string)
        + info (object)
            + date (string)
            + lat_range (array)
            + long_range (array)
            + points (number)
            + units (string)
            + compute_time (number)
        + data (array)
            + (object, optional)
                + date (string)
                + min_temp (number)
                + max_temp (number)
                + avg_temp (number)
                + dew_point (number)
                + pressure (number)
                + hours_rh_over_90 (number)
                + avg_temp_rh_over_90 (number)

### Get all insolations for date [GET /weather/all_for_date.csv{?date}]

+ Parameters
    + date: `2020-01-01` (string)

+ Response 200 (text/csv)


## Weather database info [GET /weather/info]

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + table_cols (array) - column names in database
        + lat_range (array) - min, max
        + long_range (array) - min, max
        + date_range (array) - min, max
        + actual_days (number) - days in database
        + missing_days (array)
        + compute_time (number)


# Group Pest Forecasts

## index [/pest_forecasts]

### Get pest forecast data for grid [GET /pest_forecasts{?pest,start_date,end_date,lat_range,long_range}]

Returns pest forecast data for entire grid for pest and date range

+ Parameters
    + pest: potato_blight_dsv (string) - column name of pest data
    + start_date: `2020-01-01` (string, optional) - defaults to 7 days ago
    + end_date: `2020-10-10` (string, optional) - defaults to today
    + lat_range: `45,50` (string, optional) - restrict latitude range
    + long_range: `-90,-85` (string, optional) - restrict longitude range

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + info (object)
            + pest (string)
            + start_date (string)
            + end_date (string)
            + lat_range (array)
            + long_range (array)
            + grid_points (number)
            + min_value (number, nullable)
            + max_value (number, nullable)
            + days_requested (number)
            + days_returned (number)
            + compute_time (number)
        + data (array)
            + (object)
                + lat (string)
                + long (string)
                + total (number)
                + avg (number)
                + freeze (boolean)


### Download csv [GET /pest_forecasts.csv{?pest,start_date,end_date,lat_range,long_range}]

Returns pest forecast data for entire grid for pest and date range

+ Parameters
    + pest: potato_blight_dsv (string) - column name of pest data
    + start_date: `2020-01-01` (string, optional) - defaults to 7 days ago
    + end_date: `2020-10-10` (string, optional) - defaults to today
    + lat_range: `45,50` (string, optional) - restrict latitude range
    + long_range: `-90,-85` (string, optional) - restrict longitude range

+ Response 200 (text/csv)


## show [/pest_forecasts/{pest}]

### Get pest or dd map image url [GET /pest_forecasts/{pest}{?start_date,end_date,units}]

Retrieve the pest or dd map for a given date.

+ Parameters
    + pest: `dd_50_none` (string) - the desired pest forecast data column
    + start_date (string, optional)
    + end_date (string, optional)
    + units (string, optional) - either F or C, only matters when pest is a dd model

+ Response 200 (application/json; charset=utf-8)
    + Attributes
        + status (string)
        + params (object)
        + compute_time (number)
        + map: `url/for/map.png` (string)


## custom [/pest_forecasts/custom]

### Get degree day totals for grid [GET /pest_forecasts/custom{?pest,start_date,end_date,lat_range,long_range}]

If pest param is given, returns total degree days from existing degree day model

+ Parameters
    + pest: dd_50_86 (string) - column name of pest data
    + start_date: `2020-01-01` (string, optional) - defaults to 7 days ago
    + end_date: `2020-10-10` (string, optional) - defaults to today
    + lat_range: `45,50` (string, optional) - restrict latitude range
    + long_range: `-90,-85` (string, optional) - restrict longitude range

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + info (object)
            + pest (string)
            + start_date (string)
            + end_date (string)
            + lat_range (array)
            + long_range (array)
            + grid_points (number)
            + min_value (number, nullable)
            + max_value (number, nullable)
            + days_requested (number)
            + days_returned (number)
            + status (string)
            + compute_time (number)
        + data (array)
            + (object, optional)
                + lat (number)
                + long (number)
                + total (number)


### Get degree day totals for grid [GET /pest_forecasts/custom{?start_date,end_date,t_base,t_upper,lat_range,long_range}]

If pest not give, computes new degree day grid from weather and returns totals

+ Parameters
    + start_date: `2020-01-01` (string, optional) - defaults to 7 days ago
    + end_date: `2020-10-10` (string, optional) - defaults to today
    + t_base: 50 (number, optional) - degree day base threshold
    + t_upper: 86 (number, optional) - degree day upper threshold
    + lat_range: `45,50` (string, optional) - restrict latitude range
    + long_range: `-90,-85` (string, optional) - restrict longitude range

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + info (object)
            + pest (string)
            + start_date (string)
            + end_date (string)
            + lat_range (array)
            + long_range (array)
            + grid_points (number)
            + min_value (number, nullable)
            + max_value (number, nullable)
            + days_requested (number)
            + days_returned (number)
            + status (string)
            + compute_time (number)
        + data (array)
            + (object, optional)
                + lat (number)
                + long (number)
                + total (number)


### Download csv [GET /pest_forecasts/custom.csv{?pest,start_date,end_date,lat_range,long_range}]

+ Parameters
    + pest: dd_50_86 (string) - column name of pest data
    + start_date: `2020-01-01` (string, optional) - defaults to 7 days ago
    + end_date: `2020-10-10` (string, optional) - defaults to today
    + lat_range: `45,50` (string, optional) - restrict latitude range
    + long_range: `-90,-85` (string, optional) - restrict longitude range

+ Response 200 (text/csv)


## point_details [/pest_forecasts/point_details]

### Get pest data for grid point in date range [GET /pest_forecasts/point_details{?pest,lat,long,start_date,end_date}]

Returns weather and pest forecast data for grid point in date range

+ Parameters
    + pest: potato_blight_dsv (string)
    + lat: `45` (number)
    + long: `-90` (number)
    + start_date: `2020-01-01` (string)
    + end_date: `2020-10-10` (string)

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + info (object)
            + pest (string)
            + lat (number)
            + long (number)
            + start_date (string)
            + end_date (string)
            + units (object)
            + cumulative_value (number)
            + days_requested (number)
            + days_returned (number)
            + status (string)
            + compute_time (number)
        + data (array)
            + (object)
                + date (string)
                + min_temp (number)
                + max_temp (number)
                + avg_temp (number)
                + avg_temp_hi_rh (number)
                + hours_hi_rh (number)
                + value (number)
                + cumulative_value (number)

### Download csv [GET /pest_forecasts/point_details.csv{?pest,lat,long,start_date,end_date}]

+ Parameters
    + pest: potato_blight_dsv (string)
    + lat: `45` (number)
    + long: `-90` (number)
    + start_date: `2020-01-01` (string)
    + end_date: `2020-10-10` (string)

+ Response 200 (text/csv)


## custom_point_details [/pest_forecasts/custom_point_details]

### Get pest data for grid point in date range [GET /pest_forecasts/custom_point_details{?lat,long,t_base,t_upper,start_date,end_date}]

Returns weather and pest forecast data for grid point in date range

+ Parameters
    + lat: `45` (number) - north latitude
    + long: `-90` (number) - west longitude
    + t_base: 50 (number) - degree day base temperature threshold (F)
    + t_upper: 86 (number) - degree day upper cutoff threshold (F)
    + start_date: `2020-01-01` (string)
    + end_date: `2020-10-10` (string)

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + info (object)
            + lat (number)
            + long (number)
            + start_date (string)
            + end_date (string)
            + t_base (number)
            + t_upper (number)
            + units (object)
            + days_requested (number)
            + days_returned (number)
            + status (string)
            + compute_time (number)
        + data (array)
            + (object)
                + date (string)
                + min_temp (number)
                + max_temp (number)
                + avg_temp (number)
                + value (number) - daily degree day accumulation
                + cumulative_value (number) - cumulative degree days


### Download csv [GET /pest_forecasts/custom_point_details.csv{?lat,long,t_base,t_upper,start_date,end_date}]

Returns weather and pest forecast data for grid point in date range

+ Parameters
    + lat: `45` (number) - north latitude
    + long: `-90` (number) - west longitude
    + t_base: 50 (number) - degree day base temperature threshold (F)
    + t_upper: 86 (number) - degree day upper cutoff threshold (F)
    + start_date: `2020-01-01` (string)
    + end_date: `2020-10-10` (string)

+ Response 200 (text/csv)

## pvy [/pest_forecasts/pvy]

### Get pvy degree day model [GET /pest_forecasts/pvy{?lat,long,end_date}]

Returns total degree days for pvy model plus one week forecast

+ Parameters
    + lat: `45` (number) - north latitude
    + long: `-90` (number) - west longitude
    + end_date: `2020-10-10` (string, optional) - defaults to today

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + info (object)
            + model (string)
            + lat (number)
            + long (number)
            + start_date (string)
            + end_date (string)
            + days_requested (number)
            + days_returned (number)
            + status (string)
            + compute_time (number)
        + current_dds (number, nullable)
        + future_dds (number, nullable)
        + data (array)
            + (object, optional)
                + date (string)
                + dd (number)
                + cum_dd (number)
        + forecast (array)
            + (object, optional)
                + date (string)
                + dd (number)
                + cum_dd (number)


## freeze [/pest_forecasts/freeze]

### Get number of freezing days [GET /pest_forecasts/freeze{?start_date,end_date,lat_range,long_range}]

If pest param is given, returns total degree days from existing degree day model

+ Parameters
    + start_date: `2020-01-01` (string, optional) - defaults to 7 days ago
    + end_date: `2020-10-10` (string, optional) - defaults to today
    + lat_range: `45,50` (string, optional) - restrict latitude range
    + long_range: `-90,-85` (string, optional) - restrict longitude range

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + info (object)
            + start_date (string)
            + end_date (string)
            + lat_range (array)
            + long_range (array)
            + grid_points (number)
            + status (string)
            + compute_time (number)
        + data (array)
            + (object, optional)
                + lat (number)
                + long (number)
                + freeze (number)


## Pest forecast database info [GET /pest_forecasts/info]

+ Response 200 (application/json; charset=utf-8)
    + Attributes (object)
        + pest_names (array) - list available pest names
        + lat_range (array) - min, max
        + long_range (array) - min, max
        + date_range (array) - min, max
        + actual_days (number) - days in database
        + missing_days (array)
        + compute_time (number)


# Data Structures

## `et/insol/precip index data` (object)
    + status (string)
    + info (object)
        + lat (number)
        + long (number)
        + start_date (string)
        + end_date (string)
        + days_requested (number)
        + days_returned (number)
        + min_value (number, nullable)
        + max_value (number, nullable)
        + units (string)
        + compute_time (number)
    + data (array)
        + (object, optional)
            + date (string)
            + value (number)

## `et/insol/precip all_for_date data` (object)
    + date (string)
    + status (string)
    + info (object, optional)
        + date (string)
        + lat_range (array)
        + long_range (array)
        + points (number)
        + min_value (number, nullable)
        + max_value (number, nullable)
        + unit (string)
        + compute_time (number)
    + data (array)
        + (object, optional)
            + lat (number)
            + long (number)
            + value (number)