---
title: "bomrang"
author: "Adam H Sparks, Jonathan Carroll, Dean Marchiori, Mark Padgham and Hugh Parsonage"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{bomrang}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---





## Introduction

bomrang provides functions for interacting with 
[Australian Bureau of Meteorology (BOM) Weather Data
Services](http://www.bom.gov.au/catalogue/data-feeds.shtml) forecasts. BOM
serves several types of data data as XML, JSON and SHTML files.
This package fetches these files, parses them and return a data frame.
Satellite and radar imagery files are also made available to the public via
anonymous FTP. bomrang provides functionality to query, fetch and create 
`raster::stack()` objects of the GeoTIFF imagery.

## Using bomrang

Several functions are provided by bomrang to retrieve Australian Bureau of
Meteorology (BOM) data. A family of functions retrieve weather data and return
data frames; `get_precis_forecast()`, which retrieves the précis (short)
forecast; `get_current_weather()`, which fetches the current weather from a
given station; `get_ag_bulletin()`, which retrieves the agriculture
bulletin; `get_weather_bulletin()` which fetches the 0900 and 1500 weather
bulletins; `get_coastal_forecast()` which fetches coastal waters forecasts for
each state and `get_historical()` which fetches historical daily temperature
min/max, rainfall, or solar exposure data. A second family of functions retrieve 
information pertaining to satellite and radar imagery, `get_available_imagery()`
and the imagery itself, `_imagery()` for satellite, and
`get_available_radar()` and `get_radar_imagery()`  for radar images. The last
group functions provides internal functionality for bomrang itself;
`update_forecast_towns()`, which updates an internal database of forecast
locations distributed with the package, `sweep_for_stations()` which returns the
nearest weather stations to a point in Australia and, `manage_cache()` that
provides facilities for managing cached satellite imagery.

## Using get_current_weather()

`get_current_weather()` takes one of two arguments: `station_name` and `latlon`,
returning the current weather observations (and the observations of the last 72
hours) for the given location.

If `station_name` is used, the weather observations for the last 72 hours are
returned for that station. If the string provided is ambiguous, the function
returns an observation for one of the possible stations and emits a warning to
offer unambiguous station names. 

If `latlon` is used, the observations returned are from the station nearest to
that latitude-longitude coordinate. `latlon` values are entered as decimal
degrees, _e.g._ `latlon = c(-34, 151)` for Sydney. The function also emits a
message, to tell the user which station was used.

### Results

The table returned will have different fields depending on the station that is
selected. 

### Example

Following is an example fetching the current weather for Melbourne.


```r
Melbourne_weather <- get_current_weather("Melbourne (Olympic Park)")
```

## Using get_precis_forecast()

This function only takes one argument, `state`. The `state` parameter allows the
user to select the forecast for just one state or a national forecast. States or
territories are specified using the official postal codes or full name with
fuzzy matching performed via `agrep()`

- **ACT** - Australian Capital Territory

- **NSW** - New South Wales

- **NT** - Northern Territory

- **QLD** - Queensland

- **SA** - South Australia

- **TAS** - Tasmania

- **VIC** - Victoria

- **WA** - Western Australia

- **AUS** - Australia, returns national forecast including all states, NT and
ACT.

### Results

The function, `get_precis_forecast()`, will return a data frame of the weather
forecast for the daily forecast for selected towns. See Appendix 1 for a full
description of the fields and values.

### Example

Following is an example fetching the forecast for Queensland.


```r
(QLD_forecast <- get_precis_forecast(state = "QLD"))
#>      index product_id state         town       aac       lat      lon
#>   1:     0   IDQ11295   QLD     Brisbane QLD_PT001 -27.48080 153.0389
#>   2:     1   IDQ11295   QLD     Brisbane QLD_PT001 -27.48080 153.0389
#>   3:     2   IDQ11295   QLD     Brisbane QLD_PT001 -27.48080 153.0389
#>   4:     3   IDQ11295   QLD     Brisbane QLD_PT001 -27.48080 153.0389
#>   5:     4   IDQ11295   QLD     Brisbane QLD_PT001 -27.48080 153.0389
#>  ---                                                                 
#> 787:     2   IDQ11295   QLD Port Douglas QLD_PT254 -16.48681 145.4635
#> 788:     3   IDQ11295   QLD Port Douglas QLD_PT254 -16.48681 145.4635
#> 789:     4   IDQ11295   QLD Port Douglas QLD_PT254 -16.48681 145.4635
#> 790:     5   IDQ11295   QLD Port Douglas QLD_PT254 -16.48681 145.4635
#> 791:     6   IDQ11295   QLD Port Douglas QLD_PT254 -16.48681 145.4635
#>      elev    start_time_local end_time_local utc_offset
#>   1:  8.1 2020-01-20 05:00:00     2020-01-21      10:00
#>   2:  8.1 2020-01-21 00:00:00     2020-01-22      10:00
#>   3:  8.1 2020-01-22 00:00:00     2020-01-23      10:00
#>   4:  8.1 2020-01-23 00:00:00     2020-01-24      10:00
#>   5:  8.1 2020-01-24 00:00:00     2020-01-25      10:00
#>  ---                                                   
#> 787: 70.4 2020-01-22 00:00:00     2020-01-23      10:00
#> 788: 70.4 2020-01-23 00:00:00     2020-01-24      10:00
#> 789: 70.4 2020-01-24 00:00:00     2020-01-25      10:00
#> 790: 70.4 2020-01-25 00:00:00     2020-01-26      10:00
#> 791: 70.4 2020-01-26 00:00:00     2020-01-27      10:00
#>           start_time_utc        end_time_utc minimum_temperature
#>   1: 2020-01-19 19:00:00 2020-01-20 14:00:00                  NA
#>   2: 2020-01-20 14:00:00 2020-01-21 14:00:00                  25
#>   3: 2020-01-21 14:00:00 2020-01-22 14:00:00                  25
#>   4: 2020-01-22 14:00:00 2020-01-23 14:00:00                  25
#>   5: 2020-01-23 14:00:00 2020-01-24 14:00:00                  25
#>  ---                                                            
#> 787: 2020-01-21 14:00:00 2020-01-22 14:00:00                  26
#> 788: 2020-01-22 14:00:00 2020-01-23 14:00:00                  25
#> 789: 2020-01-23 14:00:00 2020-01-24 14:00:00                  25
#> 790: 2020-01-24 14:00:00 2020-01-25 14:00:00                  25
#> 791: 2020-01-25 14:00:00 2020-01-26 14:00:00                  25
#>      maximum_temperature lower_precipitation_limit
#>   1:                  33                        15
#>   2:                  35                         0
#>   3:                  34                         0
#>   4:                  34                         0
#>   5:                  34                         0
#>  ---                                              
#> 787:                  32                         2
#> 788:                  32                         0
#> 789:                  32                         0
#> 790:                  33                         0
#> 791:                  33                         0
#>      upper_precipitation_limit                         precis
#>   1:                      30.0       Showers. Possible storm.
#>   2:                       3.0 Shower or two. Possible storm.
#>   3:                       0.4                 Partly cloudy.
#>   4:                       0.4                 Partly cloudy.
#>   5:                       0.4                 Partly cloudy.
#>  ---                                                         
#> 787:                      10.0 Shower or two. Possible storm.
#> 788:                       6.0               Possible shower.
#> 789:                       2.0                 Partly cloudy.
#> 790:                       1.0                 Partly cloudy.
#> 791:                       5.0               Possible shower.
#>      probability_of_precipitation
#>   1:                           80
#>   2:                           60
#>   3:                           30
#>   4:                           30
#>   5:                           30
#>  ---                             
#> 787:                           60
#> 788:                           40
#> 789:                           30
#> 790:                           30
#> 791:                           40
```


## Using get_ag_bulletin()

`get_ag_bulletin()` only takes one argument, `state`. The `state` parameter
allows the user to select the bulletin for just one state or a national
forecast. States or territories are specified using the official postal codes or
full name with fuzzy matching performed via `agrep()`.

- **NSW** - New South Wales

- **NT** - Northern Territory

- **QLD** - Queensland

- **SA** - South Australia

- **TAS** - Tasmania

- **VIC** - Victoria

- **WA** - Western Australia

- **AUS** - Australia, returns bulletin for all states and NT.

### Results

The function, `get_ag_bulletin()`, will return a data frame of the agriculture
bulletin for selected stations. See Appendix 3 for a full list and description
of the fields and values.

### Example

Following is an example fetching the ag bulletin for Queensland.


```r
(QLD_bulletin <- get_ag_bulletin(state = "QLD"))
#>     product_id state dist                             name   wmo
#>  1:   IDQ60604   QLD   27                       WEIPA AERO 94170
#>  2:   IDQ60604   QLD   29                   MOUNT ISA AERO 94332
#>  3:   IDQ60604   QLD   30             RICHMOND POST OFFICE 94340
#>  4:   IDQ60604   QLD   30               GEORGETOWN AIRPORT 94274
#>  5:   IDQ60604   QLD   31                      CAIRNS AERO 94287
#>  6:   IDQ60604   QLD   31        WALKAMIN RESEARCH STATION 95284
#>  7:   IDQ60604   QLD   31                  MAREEBA AIRPORT 95286
#>  8:   IDQ60604   QLD   32          SOUTH JOHNSTONE EXP STN 95292
#>  9:   IDQ60604   QLD   32                  TOWNSVILLE AERO 94294
#> 10:   IDQ60604   QLD   32                 INGHAM COMPOSITE 95291
#> 11:   IDQ60604   QLD   33             AYR DPI RESEARCH STN 95295
#> 12:   IDQ60604   QLD   33         COLLINSVILLE POST OFFICE 94360
#> 13:   IDQ60604   QLD   33                       MACKAY M.O 94367
#> 14:   IDQ60604   QLD   35                TAMBO POST OFFICE 94355
#> 15:   IDQ60604   QLD   35                  EMERALD AIRPORT 94363
#> 16:   IDQ60604   QLD   36                   LONGREACH AERO 94346
#> 17:   IDQ60604   QLD   38                   BOULIA AIRPORT 94333
#> 18:   IDQ60604   QLD   38               BIRDSVILLE AIRPORT 95482
#> 19:   IDQ60604   QLD   39                 ROCKHAMPTON AERO 94374
#> 20:   IDQ60604   QLD   39                 THANGOOL AIRPORT 94376
#> 21:   IDQ60604   QLD   39                   BUNDABERG AERO 94387
#> 22:   IDQ60604   QLD   40  UNIVERSITY OF QUEENSLAND GATTON 94562
#> 23:   IDQ60604   QLD   40                    BRISBANE AERO 94578
#> 24:   IDQ60604   QLD   40 LOGAN CITY WATER TREATMENT PLANT 95581
#> 25:   IDQ60604   QLD   41                       OAKEY AERO 94552
#> 26:   IDQ60604   QLD   41                    DALBY AIRPORT 94542
#> 27:   IDQ60604   QLD   41                          WARWICK 94555
#> 28:   IDQ60604   QLD   43             MITCHELL POST OFFICE 94514
#> 29:   IDQ60604   QLD   43                     ROMA AIRPORT 94515
#> 30:   IDQ60604   QLD   43                ST GEORGE AIRPORT 94517
#> 31:   IDQ60604   QLD   44                 CHARLEVILLE AERO 94510
#> 32:   IDQ60604   QLD   45             THARGOMINDAH AIRPORT 95492
#>     product_id state dist                             name   wmo
#>      site              station      obs_time_local
#>  1: 27045                Weipa 2020-01-20 09:00:00
#>  2: 29127            Mount Isa 2020-01-20 09:00:00
#>  3: 30045             Richmond 2020-01-20 09:00:00
#>  4: 30124   Georgetown Airport 2020-01-20 09:00:00
#>  5: 31011               Cairns 2020-01-20 09:00:00
#>  6: 31108             Walkamin 2020-01-20 09:00:00
#>  7: 31210              Mareeba 2020-01-20 09:00:00
#>  8: 32037      South Johnstone 2020-01-20 09:00:00
#>  9: 32040           Townsville 2020-01-20 09:00:00
#> 10: 32078               Ingham 2020-01-20 09:00:00
#> 11: 33002                  Ayr 2020-01-20 09:00:00
#> 12: 33013         Collinsville 2020-01-20 09:00:00
#> 13: 33119               Mackay 2020-01-20 09:00:00
#> 14: 35069                Tambo 2020-01-20 09:00:00
#> 15: 35264              Emerald 2020-01-20 09:00:00
#> 16: 36031            Longreach 2020-01-20 09:00:00
#> 17: 38003               Boulia 2020-01-20 09:00:00
#> 18: 38026           Birdsville 2020-01-20 09:00:00
#> 19: 39083          Rockhampton 2020-01-20 09:00:00
#> 20: 39089             Thangool 2020-01-20 09:00:00
#> 21: 39128            Bundaberg 2020-01-20 09:00:00
#> 22: 40082               Gatton 2020-01-20 09:00:00
#> 23: 40842     Brisbane Airport 2020-01-20 09:00:00
#> 24: 40854           Logan City 2020-01-20 09:00:00
#> 25: 41359                Oakey 2020-01-20 09:00:00
#> 26: 41522                Dalby 2020-01-20 09:00:00
#> 27: 41525              Warwick 2020-01-20 09:00:00
#> 28: 43020             Mitchell 2020-01-20 09:00:00
#> 29: 43091                 Roma 2020-01-20 09:00:00
#> 30: 43109            St George 2020-01-20 09:00:00
#> 31: 44021          Charleville 2020-01-20 09:00:00
#> 32: 45025 Thargomindah Airport 2020-01-20 09:00:00
#>      site              station      obs_time_local
#>            obs_time_utc time_zone      lat      lon  elev bar_ht
#>  1: 2020-01-19 23:00:00       EST -12.6778 141.9208  18.0   18.6
#>  2: 2020-01-19 23:00:00       EST -20.6778 139.4875 340.3  341.0
#>  3: 2020-01-19 23:00:00       EST -20.7289 143.1425 211.1  214.5
#>  4: 2020-01-19 23:00:00       EST -18.3039 143.5306 301.8  302.5
#>  5: 2020-01-19 23:00:00       EST -16.8736 145.7458   2.2    8.3
#>  6: 2020-01-19 23:00:00       EST -17.1347 145.4281 594.0     NA
#>  7: 2020-01-19 23:00:00       EST -17.0704 145.4293 471.9  473.1
#>  8: 2020-01-19 23:00:00       EST -17.6053 145.9972  18.3   18.6
#>  9: 2020-01-19 23:00:00       EST -19.2483 146.7661   4.3    9.1
#> 10: 2020-01-19 23:00:00       EST -18.6494 146.1769  11.8   12.5
#> 11: 2020-01-19 23:00:00       EST -19.6169 147.3758  17.0     NA
#> 12: 2020-01-19 23:00:00       EST -20.5533 147.8464 196.0     NA
#> 13: 2020-01-19 23:00:00       EST -21.1172 149.2169  30.3   36.3
#> 14: 2020-01-19 23:00:00       EST -24.8819 146.2564 395.1  397.4
#> 15: 2020-01-19 23:00:00       EST -23.5694 148.1756 189.4  190.1
#> 16: 2020-01-19 23:00:00       EST -23.4397 144.2828 192.2  192.5
#> 17: 2020-01-19 23:00:00       EST -22.9117 139.9039 161.8  158.3
#> 18: 2020-01-19 23:00:00       EST -25.8975 139.3472  46.6   47.0
#> 19: 2020-01-19 23:00:00       EST -23.3753 150.4775  10.4   15.1
#> 20: 2020-01-19 23:00:00       EST -24.4935 150.5709 193.1  193.8
#> 21: 2020-01-19 23:00:00       EST -24.9069 152.3230  30.8   31.5
#> 22: 2020-01-19 23:00:00       EST -27.5436 152.3375  89.0     NA
#> 23: 2020-01-19 23:00:00       EST -27.3917 153.1292   4.5    9.5
#> 24: 2020-01-19 23:00:00       EST -27.6839 153.1947  14.0     NA
#> 25: 2020-01-19 23:00:00       EST -27.4034 151.7413 405.7  407.1
#> 26: 2020-01-19 23:00:00       EST -27.1605 151.2634 343.9  344.4
#> 27: 2020-01-19 23:00:00       EST -28.2061 152.1003 475.4  475.8
#> 28: 2020-01-19 23:00:00       EST -26.4888 147.9777 336.5  338.0
#> 29: 2020-01-19 23:00:00       EST -26.5477 148.7710 307.4  307.8
#> 30: 2020-01-19 23:00:00       EST -28.0489 148.5942 198.5  199.1
#> 31: 2020-01-19 23:00:00       EST -26.4139 146.2558 301.6  303.3
#> 32: 2020-01-19 23:00:00       EST -27.9867 143.8150 130.9  131.4
#>            obs_time_utc time_zone      lat      lon  elev bar_ht
#>     start  end    r   tn   tx  twd   ev   tg  sn solr   t5  t10  t20
#>  1:  1972 2018 34.6 23.2 33.2  3.8   NA   NA  NA 25.7   NA   NA   NA
#>  2:  1966 2018  0.0 28.7 43.2 12.1   NA   NA  NA 26.8   NA   NA   NA
#>  3:  1889 2018  0.0 28.0 43.5 13.0 15.6   NA  NA 28.1   NA   NA   NA
#>  4:  2004 2018  0.0 26.3 40.2  5.7   NA   NA  NA 27.5   NA   NA   NA
#>  5:  1941 2018 11.8 24.3 34.9  4.9   NA   NA  NA 28.7   NA   NA   NA
#>  6:  1965 2018 19.0 20.5 37.5  4.4  5.4 21.0  NA 27.8   NA 28.0 30.0
#>  7:  2000 2018  4.4 22.0 38.4  4.3   NA   NA  NA 28.2 28.9   NA 30.6
#>  8:  1920 2018  2.6 22.9 35.7  3.1   NA   NA  NA 27.0 30.6 30.8 31.7
#>  9:  1940 2018  0.0 28.6 35.1  4.7   NA   NA  NA 29.7   NA   NA   NA
#> 10:  1968 2018   NA 24.6 41.1  2.0   NA   NA  NA 29.6   NA   NA   NA
#> 11:  1951 2018  0.0 26.1 35.8  4.9   NA   NA  NA 29.2 35.2 33.3 34.0
#> 12:  1939 2018  0.0 25.8 37.2  4.5  9.6   NA  NA 23.2   NA   NA   NA
#> 13:  1959 2018  0.0 26.9 34.0  4.4   NA   NA  NA 29.5   NA   NA   NA
#> 14:  1877 2018  0.0 27.2 38.0 12.2  8.8 22.9  NA 20.8   NA   NA   NA
#> 15:  1981 2018  0.0 27.0 39.0  8.9   NA   NA  NA 24.9 37.0 33.9 33.8
#> 16:  1949 2018   NA   NA   NA 13.7   NA   NA  NA 26.0   NA 33.5 34.8
#> 17:  1886 2018  0.0 25.8 39.0 12.0 20.0 24.8  NA 26.7   NA   NA   NA
#> 18:  2000 2018  0.0 23.7 38.8 11.2   NA   NA  NA 24.0   NA   NA   NA
#> 19:  1939 2018  0.0 25.3 39.1  5.9   NA   NA  NA 26.2   NA   NA   NA
#> 20:  1929 2018  0.0 25.4 37.5  7.2   NA   NA  NA 28.6   NA   NA   NA
#> 21:  1942 2018 16.8 25.2 30.0  5.1   NA   NA  NA 24.2 26.9 27.1 27.6
#> 22:  1897 2018  0.2 22.6 32.6  5.0   NA   NA  NA 22.2 30.3 27.9 28.5
#> 23:  1992 2018  0.2 25.5 29.5  3.6   NA 20.2 8.8 25.8 28.0 27.0 27.0
#> 24:  1992 2018  0.0 25.6 30.7  3.5   NA   NA  NA 23.7   NA   NA   NA
#> 25:  1970 2018  0.0 22.3 31.6  5.2   NA   NA  NA 26.4   NA   NA   NA
#> 26:  1992 2018  0.0 22.7 33.2  6.2   NA   NA  NA 28.8 25.7   NA 26.6
#> 27:  1994 2018  0.0 19.3 29.7  6.2   NA   NA  NA 20.7 26.4 25.8 26.3
#> 28:  1884 2018  0.0 27.0 37.0 13.2   NA 25.9  NA 23.5   NA   NA   NA
#> 29:  1985 2018  0.0 27.3 38.0 12.3   NA   NA  NA 28.4   NA   NA   NA
#> 30:  1997 2018  0.0 27.1 37.7 14.2   NA   NA  NA 28.5 36.6 33.2 32.1
#> 31:  1942 2018  0.0 24.6 37.9 15.0   NA   NA  NA 22.3   NA   NA   NA
#> 32:  1999 2018  0.0 24.5 39.3 11.3   NA   NA  NA 28.2   NA   NA   NA
#>     start  end    r   tn   tx  twd   ev   tg  sn solr   t5  t10  t20
#>      t50  t1m  wr
#>  1:   NA   NA  NA
#>  2:   NA   NA  NA
#>  3:   NA   NA  NA
#>  4:   NA   NA  NA
#>  5:   NA   NA  NA
#>  6:   NA   NA  86
#>  7:   NA 30.4 213
#>  8: 30.8 29.2  NA
#>  9:   NA   NA  NA
#> 10:   NA   NA  NA
#> 11: 34.5 32.9  NA
#> 12:   NA   NA  NA
#> 13:   NA   NA  NA
#> 14:   NA   NA  NA
#> 15: 33.6   NA  NA
#> 16: 34.4 33.4  NA
#> 17:   NA   NA  NA
#> 18:   NA   NA  NA
#> 19:   NA   NA  NA
#> 20:   NA   NA  NA
#> 21: 27.8 29.0  NA
#> 22: 27.4   NA 148
#> 23: 28.0 27.0 395
#> 24:   NA   NA  NA
#> 25:   NA   NA  NA
#> 26:   NA 26.4 201
#> 27: 26.6 27.1  NA
#> 28:   NA   NA  NA
#> 29:   NA   NA  NA
#> 30: 33.1 33.1  88
#> 31:   NA   NA  NA
#> 32:   NA   NA  NA
#>      t50  t1m  wr
```

## Using get_weather_bulletin()

This function takes two arguments, `state` for the desired state; and `morning`
if `TRUE`, return the 9am bulletin for the nominated state; otherwise return the
3pm bulletin. States or territories are specified using the official postal
codes.

-   **ACT**  Australian Capital Territory (will return NSW)

-   **NSW** - New South Wales

-   **NT** - Northern Territory

-   **QLD** - Queensland

-   **SA** - South Australia

-   **TAS** - Tasmania

-   **VIC** - Victoria

-   **WA** - Western Australia

### Results

The function `get_weather_bulletin()` will return a data frame of BOM data for
the requested state(s) or territory.

### Example

Following is an example fetching the 9AM bulletin for Queensland.


```r
(qld_weather <- get_weather_bulletin(state = "QLD", morning = TRUE))
#>            stations cld8ths wind_dir wind_speed_kmh temp_c_dry
#>   1:     Coconut Is      NA     <NA>             NA         31
#>   2:        Coen Ap      NA      WNW             17         30
#>   3:        Horn Is       8        W             24         31
#>   4: Lockhart River      NA      WNW             28         32
#>   5:    Palmerville      NA      WSW             13         30
#>  ---                                                          
#> 133:         Hobart      NA      NNE             11         19
#> 134:       Adelaide      NA       SW              7         18
#> 135:       Perth Ap      NA        E             35         18
#> 136:         Darwin       5        W             13         31
#> 137:  Alice Springs       7        N             19         26
#>      temp_c_dew temp_c_max temp_c_min temp_c_gr barhpa rain_mm
#>   1:         NA         33         30        NA   1009      NA
#>   2:         25         36         26        NA   1008      NA
#>   3:         25         33         27        NA   1009     7.0
#>   4:         25         38         28        NA   1007   207.0
#>   5:         25         36         24        NA   1007      NA
#>  ---                                                          
#> 133:          9         NA         NA        NA   1014      NA
#> 134:         12         NA         NA        NA   1010      NA
#> 135:         10         NA         NA        NA   1017      NA
#> 136:         25         34         29        27   1009     0.2
#> 137:         17         40         26        NA   1007      NA
#>              weather seastate
#>   1:            <NA>     <NA>
#>   2:            <NA>     <NA>
#>   3:            <NA>     <NA>
#>   4:            <NA>     <NA>
#>   5:            <NA>     <NA>
#>  ---                         
#> 133:            <NA>     <NA>
#> 134:            <NA>     <NA>
#> 135:            <NA>     <NA>
#> 136: Distant precip.     <NA>
#> 137:            <NA>     <NA>
```

Following is an example fetching the 3PM bulletin for Queensland.


```r
(qld_weather <- get_weather_bulletin(state = "QLD"))
#>            stations cld8ths wind_dir wind_speed_kmh temp_c_dry
#>   1:     Coconut Is      NA     <NA>             NA         31
#>   2:        Coen Ap      NA      WNW             17         30
#>   3:        Horn Is       8        W             24         31
#>   4: Lockhart River      NA      WNW             28         32
#>   5:    Palmerville      NA      WSW             13         30
#>  ---                                                          
#> 133:         Hobart      NA      NNE             11         19
#> 134:       Adelaide      NA       SW              7         18
#> 135:       Perth Ap      NA        E             35         18
#> 136:         Darwin       5        W             13         31
#> 137:  Alice Springs       7        N             19         26
#>      temp_c_dew temp_c_max temp_c_min temp_c_gr barhpa rain_mm
#>   1:         NA         33         30        NA   1009      NA
#>   2:         25         36         26        NA   1008      NA
#>   3:         25         33         27        NA   1009     7.0
#>   4:         25         38         28        NA   1007   207.0
#>   5:         25         36         24        NA   1007      NA
#>  ---                                                          
#> 133:          9         NA         NA        NA   1014      NA
#> 134:         12         NA         NA        NA   1010      NA
#> 135:         10         NA         NA        NA   1017      NA
#> 136:         25         34         29        27   1009     0.2
#> 137:         17         40         26        NA   1007      NA
#>              weather seastate
#>   1:            <NA>     <NA>
#>   2:            <NA>     <NA>
#>   3:            <NA>     <NA>
#>   4:            <NA>     <NA>
#>   5:            <NA>     <NA>
#>  ---                         
#> 133:            <NA>     <NA>
#> 134:            <NA>     <NA>
#> 135:            <NA>     <NA>
#> 136: Distant precip.     <NA>
#> 137:            <NA>     <NA>
```


## Using get_coastal_forecast()

This function only takes one argument, `state`. The `state` parameter allows the
user to select the forecast for just one state or a national forecast. States or
territories are specified using the official postal codes or full name with
fuzzy matching performed via `agrep()`

- **ACT** - Australian Capital Territory

- **NSW** - New South Wales

- **NT** - Northern Territory

- **QLD** - Queensland

- **SA** - South Australia

- **TAS** - Tasmania

- **VIC** - Victoria

- **WA** - Western Australia

- **AUS** - Australia, returns national forecast including all states, NT and
ACT.

### Results

The function, `get_coastal_forecast()`, will return a data frame of the coastal
waters forecast for marine zones in each state. See Appendix 6 for a full
description of the fields and values.

### Example

Following is an example fetching the forecast for Queensland.


```r
(QLD_coastal_forecast <- get_coastal_forecast(state = "QLD"))
#>     index product_id    type state_code
#>  1:  <NA>   IDQ11290    <NA>        QLD
#>  2:  <NA>   IDQ11290    <NA>        QLD
#>  3:  <NA>   IDQ11290    <NA>        QLD
#>  4:  <NA>   IDQ11290    <NA>        QLD
#>  5:     0   IDQ11290    <NA>        QLD
#>  6:     1   IDQ11290    <NA>        QLD
#>  7:     2   IDQ11290    <NA>        QLD
#>  8:     0   IDQ11290    <NA>        QLD
#>  9:     1   IDQ11290    <NA>        QLD
#> 10:     2   IDQ11290    <NA>        QLD
#> 11:     0   IDQ11290 Coastal        QLD
#> 12:     1   IDQ11290 Coastal        QLD
#> 13:     2   IDQ11290 Coastal        QLD
#> 14:     0   IDQ11290    <NA>        QLD
#> 15:     1   IDQ11290    <NA>        QLD
#> 16:     2   IDQ11290    <NA>        QLD
#> 17:     0   IDQ11290    <NA>        QLD
#> 18:     1   IDQ11290    <NA>        QLD
#> 19:     2   IDQ11290    <NA>        QLD
#> 20:     0   IDQ11290    <NA>        QLD
#> 21:     1   IDQ11290    <NA>        QLD
#> 22:     2   IDQ11290    <NA>        QLD
#> 23:     0   IDQ11290    <NA>        QLD
#> 24:     1   IDQ11290    <NA>        QLD
#> 25:     2   IDQ11290    <NA>        QLD
#> 26:     0   IDQ11290    <NA>        QLD
#> 27:     1   IDQ11290    <NA>        QLD
#> 28:     2   IDQ11290    <NA>        QLD
#> 29:     0   IDQ11290    <NA>        QLD
#> 30:     1   IDQ11290    <NA>        QLD
#> 31:     2   IDQ11290    <NA>        QLD
#> 32:     0   IDQ11290   Local        QLD
#> 33:     1   IDQ11290   Local        QLD
#> 34:     2   IDQ11290   Local        QLD
#> 35:     0   IDQ11290    <NA>        QLD
#> 36:     1   IDQ11290    <NA>        QLD
#> 37:     2   IDQ11290    <NA>        QLD
#> 38:     0   IDQ11290    <NA>        QLD
#> 39:     1   IDQ11290    <NA>        QLD
#> 40:     2   IDQ11290    <NA>        QLD
#> 41:     0   IDQ11290   Local        QLD
#> 42:     1   IDQ11290   Local        QLD
#> 43:     2   IDQ11290   Local        QLD
#> 44:     0   IDQ11290    <NA>        QLD
#> 45:     1   IDQ11290    <NA>        QLD
#>                                                          dist_name
#>  1:                                                     Queensland
#>  2:                                 Queensland Gulf of Carpentaria
#>  3:                                               North Queensland
#>  4:                                               South Queensland
#>  5: South East Gulf of Carpentaria: QLD-NT Border to Cape Keerweer
#>  6: South East Gulf of Carpentaria: QLD-NT Border to Cape Keerweer
#>  7: South East Gulf of Carpentaria: QLD-NT Border to Cape Keerweer
#>  8:   North East Gulf of Carpentaria: Cape Keerweer to Crab Island
#>  9:   North East Gulf of Carpentaria: Cape Keerweer to Crab Island
#> 10:   North East Gulf of Carpentaria: Cape Keerweer to Crab Island
#> 11:                                                  Torres Strait
#> 12:                                                  Torres Strait
#> 13:                                                  Torres Strait
#> 14:                  Peninsula Coast: Sharp Point to Cape Melville
#> 15:                  Peninsula Coast: Sharp Point to Cape Melville
#> 16:                  Peninsula Coast: Sharp Point to Cape Melville
#> 17:              Cooktown Coast: Cape Melville to Cape Tribulation
#> 18:              Cooktown Coast: Cape Melville to Cape Tribulation
#> 19:              Cooktown Coast: Cape Melville to Cape Tribulation
#> 20:                     Cairns Coast: Cape Tribulation to Cardwell
#> 21:                     Cairns Coast: Cape Tribulation to Cardwell
#> 22:                     Cairns Coast: Cape Tribulation to Cardwell
#> 23:                            Townsville Coast: Cardwell to Bowen
#> 24:                            Townsville Coast: Cardwell to Bowen
#> 25:                            Townsville Coast: Cardwell to Bowen
#> 26:                             Mackay Coast: Bowen to St Lawrence
#> 27:                             Mackay Coast: Bowen to St Lawrence
#> 28:                             Mackay Coast: Bowen to St Lawrence
#> 29:                Capricornia Coast: St Lawrence to Burnett Heads
#> 30:                Capricornia Coast: St Lawrence to Burnett Heads
#> 31:                Capricornia Coast: St Lawrence to Burnett Heads
#> 32:                                                     Hervey Bay
#> 33:                                                     Hervey Bay
#> 34:                                                     Hervey Bay
#> 35:         Fraser Island Coast: Sandy Cape to Double Island Point
#> 36:         Fraser Island Coast: Sandy Cape to Double Island Point
#> 37:         Fraser Island Coast: Sandy Cape to Double Island Point
#> 38:     Sunshine Coast Waters: Double Island Point to Cape Moreton
#> 39:     Sunshine Coast Waters: Double Island Point to Cape Moreton
#> 40:     Sunshine Coast Waters: Double Island Point to Cape Moreton
#> 41:                                                    Moreton Bay
#> 42:                                                    Moreton Bay
#> 43:                                                    Moreton Bay
#> 44:                Gold Coast Waters: Cape Moreton to Point Danger
#> 45:                Gold Coast Waters: Cape Moreton to Point Danger
#>     pt_1_name pt_2_name       aac    start_time_local
#>  1:      <NA>      <NA> QLD_FA001 2020-01-20 04:45:32
#>  2:      <NA>      <NA> QLD_FA002 2020-01-20 05:00:00
#>  3:      <NA>      <NA> QLD_FA003 2020-01-20 05:00:00
#>  4:      <NA>      <NA> QLD_FA004 2020-01-20 05:00:00
#>  5:      <NA>      <NA> QLD_MW001 2020-01-20 05:00:00
#>  6:      <NA>      <NA> QLD_MW001 2020-01-21 00:00:00
#>  7:      <NA>      <NA> QLD_MW001 2020-01-22 00:00:00
#>  8:      <NA>      <NA> QLD_MW002 2020-01-20 05:00:00
#>  9:      <NA>      <NA> QLD_MW002 2020-01-21 00:00:00
#> 10:      <NA>      <NA> QLD_MW002 2020-01-22 00:00:00
#> 11:      <NA>      <NA> QLD_MW003 2020-01-20 05:00:00
#> 12:      <NA>      <NA> QLD_MW003 2020-01-21 00:00:00
#> 13:      <NA>      <NA> QLD_MW003 2020-01-22 00:00:00
#> 14:      <NA>      <NA> QLD_MW004 2020-01-20 05:00:00
#> 15:      <NA>      <NA> QLD_MW004 2020-01-21 00:00:00
#> 16:      <NA>      <NA> QLD_MW004 2020-01-22 00:00:00
#> 17:      <NA>      <NA> QLD_MW005 2020-01-20 05:00:00
#> 18:      <NA>      <NA> QLD_MW005 2020-01-21 00:00:00
#> 19:      <NA>      <NA> QLD_MW005 2020-01-22 00:00:00
#> 20:      <NA>      <NA> QLD_MW006 2020-01-20 05:00:00
#> 21:      <NA>      <NA> QLD_MW006 2020-01-21 00:00:00
#> 22:      <NA>      <NA> QLD_MW006 2020-01-22 00:00:00
#> 23:      <NA>      <NA> QLD_MW007 2020-01-20 05:00:00
#> 24:      <NA>      <NA> QLD_MW007 2020-01-21 00:00:00
#> 25:      <NA>      <NA> QLD_MW007 2020-01-22 00:00:00
#> 26:      <NA>      <NA> QLD_MW008 2020-01-20 05:00:00
#> 27:      <NA>      <NA> QLD_MW008 2020-01-21 00:00:00
#> 28:      <NA>      <NA> QLD_MW008 2020-01-22 00:00:00
#> 29:      <NA>      <NA> QLD_MW009 2020-01-20 05:00:00
#> 30:      <NA>      <NA> QLD_MW009 2020-01-21 00:00:00
#> 31:      <NA>      <NA> QLD_MW009 2020-01-22 00:00:00
#> 32:      <NA>      <NA> QLD_MW010 2020-01-20 05:00:00
#> 33:      <NA>      <NA> QLD_MW010 2020-01-21 00:00:00
#> 34:      <NA>      <NA> QLD_MW010 2020-01-22 00:00:00
#> 35:      <NA>      <NA> QLD_MW011 2020-01-20 05:00:00
#> 36:      <NA>      <NA> QLD_MW011 2020-01-21 00:00:00
#> 37:      <NA>      <NA> QLD_MW011 2020-01-22 00:00:00
#> 38:      <NA>      <NA> QLD_MW012 2020-01-20 05:00:00
#> 39:      <NA>      <NA> QLD_MW012 2020-01-21 00:00:00
#> 40:      <NA>      <NA> QLD_MW012 2020-01-22 00:00:00
#> 41:      <NA>      <NA> QLD_MW013 2020-01-20 05:00:00
#> 42:      <NA>      <NA> QLD_MW013 2020-01-21 00:00:00
#> 43:      <NA>      <NA> QLD_MW013 2020-01-22 00:00:00
#> 44:      <NA>      <NA> QLD_MW014 2020-01-20 05:00:00
#> 45:      <NA>      <NA> QLD_MW014 2020-01-21 00:00:00
#>          end_time_local utc_offset      start_time_utc
#>  1: 2020-01-20 04:45:32      10:00 2020-01-20 04:45:32
#>  2: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#>  3: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#>  4: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#>  5: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#>  6: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#>  7: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#>  8: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#>  9: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 10: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 11: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 12: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 13: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 14: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 15: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 16: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 17: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 18: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 19: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 20: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 21: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 22: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 23: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 24: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 25: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 26: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 27: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 28: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 29: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 30: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 31: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 32: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 33: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 34: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 35: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 36: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 37: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 38: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 39: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 40: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 41: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 42: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#> 43: 2020-01-22 00:00:00      10:00 2020-01-22 00:00:00
#> 44: 2020-01-20 05:00:00      10:00 2020-01-20 05:00:00
#> 45: 2020-01-21 00:00:00      10:00 2020-01-21 00:00:00
#>            end_time_utc
#>  1: 2020-01-20 04:45:32
#>  2: 2020-01-20 05:00:00
#>  3: 2020-01-20 05:00:00
#>  4: 2020-01-20 05:00:00
#>  5: 2020-01-20 05:00:00
#>  6: 2020-01-21 00:00:00
#>  7: 2020-01-22 00:00:00
#>  8: 2020-01-20 05:00:00
#>  9: 2020-01-21 00:00:00
#> 10: 2020-01-22 00:00:00
#> 11: 2020-01-20 05:00:00
#> 12: 2020-01-21 00:00:00
#> 13: 2020-01-22 00:00:00
#> 14: 2020-01-20 05:00:00
#> 15: 2020-01-21 00:00:00
#> 16: 2020-01-22 00:00:00
#> 17: 2020-01-20 05:00:00
#> 18: 2020-01-21 00:00:00
#> 19: 2020-01-22 00:00:00
#> 20: 2020-01-20 05:00:00
#> 21: 2020-01-21 00:00:00
#> 22: 2020-01-22 00:00:00
#> 23: 2020-01-20 05:00:00
#> 24: 2020-01-21 00:00:00
#> 25: 2020-01-22 00:00:00
#> 26: 2020-01-20 05:00:00
#> 27: 2020-01-21 00:00:00
#> 28: 2020-01-22 00:00:00
#> 29: 2020-01-20 05:00:00
#> 30: 2020-01-21 00:00:00
#> 31: 2020-01-22 00:00:00
#> 32: 2020-01-20 05:00:00
#> 33: 2020-01-21 00:00:00
#> 34: 2020-01-22 00:00:00
#> 35: 2020-01-20 05:00:00
#> 36: 2020-01-21 00:00:00
#> 37: 2020-01-22 00:00:00
#> 38: 2020-01-20 05:00:00
#> 39: 2020-01-21 00:00:00
#> 40: 2020-01-22 00:00:00
#> 41: 2020-01-20 05:00:00
#> 42: 2020-01-21 00:00:00
#> 43: 2020-01-22 00:00:00
#> 44: 2020-01-20 05:00:00
#> 45: 2020-01-21 00:00:00
#>                                                                                                             forecast_seas
#>  1:                                                                                                                  <NA>
#>  2:                                                                                                                  <NA>
#>  3:                                                                                                                  <NA>
#>  4:                                                                                                                  <NA>
#>  5:                                                           1 to 2 metres, decreasing to 1 to 1.5 metres around midday.
#>  6:                                                              1 to 1.5 metres, decreasing below 1 metre around midday.
#>  7:                                                                                                        Below 1 metre.
#>  8:                                                            1 to 2 metres, decreasing to 1 metre during the afternoon.
#>  9:                                                          1 to 1.5 metres, decreasing to 1 metre during the afternoon.
#> 10:                                                                                                       Around 1 metre.
#> 11:                                                                                                      1 to 1.5 metres.
#> 12:                                                      Around 1 metre, increasing to 1 to 1.5 metres west of Cape York.
#> 13:                                                                                                       Around 1 metre.
#> 14:                                                        Below 1 metre inshore, increasing to 1 to 1.5 metres offshore.
#> 15:                                                                                                       Around 1 metre.
#> 16:                                                                                                        Below 1 metre.
#> 17:                                                                Below 1 metre, increasing to 1 to 1.5 metres offshore.
#> 18:                                                         1 to 1.5 metres, decreasing below 1 metre during the morning.
#> 19:                                                                                                        Below 1 metre.
#> 20:                                                                                                        Below 1 metre.
#> 21:                                                                                                        Below 1 metre.
#> 22:                                                                                                     Below 0.5 metres.
#> 23:                                                                                                        Below 1 metre.
#> 24:                                                                                                        Below 1 metre.
#> 25:                                                                                                        Below 1 metre.
#> 26:                                                    Below 1 metre, reaching up to 1 metre offshore during the morning.
#> 27:                                                                                                        Below 1 metre.
#> 28:                                                                                                     Below 0.5 metres.
#> 29:                                           Around 1 metre, increasing to 1 to 1.5 metres inshore during the afternoon.
#> 30:                                                                                                       Around 1 metre.
#> 31:                                                                                                        Below 1 metre.
#> 32:                                                                                                       Around 1 metre.
#> 33:                                                                                                       Around 1 metre.
#> 34:                                                                                                        Below 1 metre.
#> 35:                                                                                                       Around 1 metre.
#> 36:                                                                                                       Around 1 metre.
#> 37:                                                                                                       Around 1 metre.
#> 38:   1 to 1.5 metres, decreasing to 1 metre during the morning, then increasing to 1 to 1.5 metres during the afternoon.
#> 39:                                                                                                      1 to 1.5 metres.
#> 40:                     1 to 1.5 metres, increasing to 1.5 to 2 metres offshore south of Maroochydore during the evening.
#> 41: Below 1 metre, reaching 1 metre in the northern bay, increasing to 1 to 1.5 metres in the far north by early evening.
#> 42:                                                                                                       Around 1 metre.
#> 43:                                    Around 1 metre, increasing to 1 to 1.5 metres in the far north during the evening.
#> 44:                                                                                                      1 to 1.5 metres.
#> 45:                                                                                                      1 to 1.5 metres.
#>                                                                                                                  forecast_weather
#>  1:                                                                                                                          <NA>
#>  2:                                                                                                                          <NA>
#>  3:                                                                                                                          <NA>
#>  4:                                                                                                                          <NA>
#>  5: Partly cloudy. 50% chance of showers in the morning and afternoon. The chance of a thunderstorm in the morning and afternoon.
#>  6:                                                                                  Partly cloudy. The chance of a thunderstorm.
#>  7:                                                           Partly cloudy. 50% chance of showers. The chance of a thunderstorm.
#>  8:                                                            Partly cloudy. The chance of a thunderstorm from the late morning.
#>  9:                                                           Partly cloudy. 60% chance of showers. The chance of a thunderstorm.
#> 10:                                                           Partly cloudy. 70% chance of showers. The chance of a thunderstorm.
#> 11:                                                           Partly cloudy. 50% chance of showers. The chance of a thunderstorm.
#> 12:                                                           Partly cloudy. 60% chance of showers. The chance of a thunderstorm.
#> 13:                                                           Partly cloudy. 70% chance of showers. The chance of a thunderstorm.
#> 14:                                                     Partly cloudy. The chance of a thunderstorm in the morning and afternoon.
#> 15:                                                                                  Partly cloudy. The chance of a thunderstorm.
#> 16:                                                           Partly cloudy. 50% chance of showers. The chance of a thunderstorm.
#> 17:                                                     Partly cloudy. The chance of a thunderstorm in the morning and afternoon.
#> 18:                                                                                  Partly cloudy. The chance of a thunderstorm.
#> 19:                                                                                  Partly cloudy. The chance of a thunderstorm.
#> 20:                                                                                   Mostly sunny. The chance of a thunderstorm.
#> 21:                                                           Partly cloudy. 50% chance of showers. The chance of a thunderstorm.
#> 22:                                                           Partly cloudy. 50% chance of showers. The chance of a thunderstorm.
#> 23:                                                                                  Partly cloudy. The chance of a thunderstorm.
#> 24:                                                                                  Partly cloudy. The chance of a thunderstorm.
#> 25:                                                                   Partly cloudy. The chance of a thunderstorm in the morning.
#> 26:                                              Mostly sunny. The chance of a thunderstorm inshore in the morning and afternoon.
#> 27:                                                                                                                Partly cloudy.
#> 28:                                                                                                                 Mostly sunny.
#> 29:                                     Mostly sunny day. The chance of a thunderstorm inshore in the late afternoon and evening.
#> 30:                                                                                                                 Mostly sunny.
#> 31:                                                                                                                 Mostly sunny.
#> 32:                                                            Partly cloudy. The chance of a thunderstorm from the late morning.
#> 33:                                                                                                                Partly cloudy.
#> 34:                                                                                                                Partly cloudy.
#> 35:                                 Mostly sunny morning. The chance of a thunderstorm inshore during this afternoon and evening.
#> 36:                                                                                                                 Mostly sunny.
#> 37:                                                                                                                 Mostly sunny.
#> 38:                                                  Mostly sunny. The chance of a thunderstorm during the morning and afternoon.
#> 39:                                              Mostly sunny. The chance of a thunderstorm inshore in the afternoon and evening.
#> 40:                                                                 Partly cloudy. The chance of a thunderstorm in the afternoon.
#> 41:  Partly cloudy. 80% chance of showers during this afternoon and evening. The chance of a thunderstorm from late this morning.
#> 42:                              Partly cloudy. 30% chance of showers. The chance of a thunderstorm in the morning and afternoon.
#> 43:                                                                 Partly cloudy. The chance of a thunderstorm in the afternoon.
#> 44:                           Mostly sunny. 50% chance of showers. The chance of a thunderstorm during the morning and afternoon.
#> 45:                                     Mostly sunny day. The chance of a thunderstorm inshore in the late afternoon and evening.
#>                                                                                                                                                                                                                                                                                   forecast_winds
#>  1:                                                                                                                                                                                                                                                                                         <NA>
#>  2:                                                                                                                                                                                                                                                                                         <NA>
#>  3:                                                                                                                                                                                                                                                                                         <NA>
#>  4:                                                                                                                                                                                                                                                                                         <NA>
#>  5:                                                                  West to northwesterly 15 to 20 knots, reaching up to 25 knots early in the morning. Winds south of Mornington Island tending southerly 10 to 15 knots in the morning, then tending north to northwesterly in the afternoon.
#>  6:                                                                                                                                                                                                     Northwesterly 10 to 15 knots, reaching 15 to 20 knots north of Kowanyama in the morning.
#>  7:                                                                                                                                                                                                                                                       North to northwesterly 10 to 15 knots.
#>  8:                                                                                                                                                                                                         West to northwesterly 15 to 20 knots, decreasing to 10 to 15 knots in the afternoon.
#>  9:                                                                                                                                                                                             West to northwesterly 15 to 20 knots, easing to 10 to 15 knots during the morning and afternoon.
#> 10:                                                                                                                                                                                                             West to northwesterly 10 to 15 knots, reaching up to 20 knots offshore at times.
#> 11:                                                                                                                                                                                                        West to northwesterly 15 to 20 knots, tending west to southwesterly in the afternoon.
#> 12:                                                                                                                                                                                                                                                                     Westerly 15 to 20 knots.
#> 13:                                                                                                                                                                                                      West to northwesterly 10 to 15 knots, reaching up to 20 knots inshore in the afternoon.
#> 14:                                                                                                  West to northwesterly 10 to 15 knots, increasing to 15 to 20 knots offshore. Winds tending north to northwesterly in the early afternoon then tending west to northwesterly in the evening.
#> 15:                                                                                                                                  West to northwesterly 10 to 15 knots turning north to northwesterly during the day. Winds north of Cape Grenville reaching up to 20 knots in the afternoon.
#> 16:                                                                                                                                                                                                    West to northwesterly 10 to 15 knots tending northeast to northwesterly in the afternoon.
#> 17:                                                                                                                                                                                                                 West to northwesterly 10 to 15 knots, increasing to 15 to 20 knots offshore.
#> 18: West to northwesterly 10 to 15 knots, reaching up to 20 knots offshore in the early morning. Inshore winds tending north to northeasterly 10 to 15 knots with afternoon sea breezes. Winds south of Cooktown becoming variable about 10 knots in the evening as a trough stalls in the area.
#> 19:                                                                                                                                           Variable about 10 knots becoming east to northeasterly in the middle of the day. Inshore winds reaching 10 to 15 knots with afternoon sea breezes.
#> 20:                                                                                                                                                                                      Variable about 10 knots in the morning, tending north to northeasterly 10 to 15 knots in the afternoon.
#> 21:                                                                                                                 Variable about 10 knots becoming easterly 10 to 15 knots in the middle of the day as a trough moves northwards. Winds becoming variable about 10 knots again in the evening.
#> 22:                                                                                                                                         Variable below 10 knots becoming easterly about 10 knots in the middle of the day. Inshore winds reaching 10 to 15 knots with afternoon sea breezes.
#> 23:                                                                                                                                                                                                          North to northeasterly 10 to 15 knots, decreasing to about 10 knots in the evening.
#> 24:                                                                                                                                                                                                                                                                Northeasterly 10 to 15 knots.
#> 25:                                                                                                                                                                                                    Northeasterly about 10 knots, reaching 10 to 15 knots inshore with afternoon sea breezes.
#> 26:                                        North to northeasterly 10 to 15 knots, reaching 15 to 20 knots south of Mackay in the early morning. Winds tending north to northwesterly about 10 knots in the morning, then tending north to northeasterly 10 to 15 knots in the middle of the day.
#> 27:                                                                                                                                                                                 North to northeasterly 10 to 15 knots, reaching up to 20 knots inshore south of Sarina in the early morning.
#> 28:                                                                                                                                                                                      North to northeasterly about 10 knots, increasing to 10 to 15 knots inshore with afternoon sea breezes.
#> 29:                                                                                                                                                                                                                    Northerly 10 to 15 knots, reaching 15 to 20 knots inshore in the evening.
#> 30:                                                                                                                                                                   Northerly 10 to 15 knots. Inshore winds north of Rundle Island locally reaching up to 20 knots with afternoon sea breezes.
#> 31:                                                                                                                                                                                      North to northeasterly about 10 knots, increasing to 10 to 15 knots inshore with afternoon sea breezes.
#> 32:                                                                                                                                                                                                                                                                    Northerly 10 to 15 knots.
#> 33:                                                                                                                                                                                                                                                                    Northerly 10 to 15 knots.
#> 34:                                                                                                                                                                                                                  Northerly about 10 knots increasing to 10 to 15 knots during the afternoon.
#> 35:                                                                                                                                                                                                                                                                    Northerly 10 to 15 knots.
#> 36:                                                                                                                                                                                                           Northerly 10 to 15 knots, reaching up to 20 knots south of Eurong in the afternoon
#> 37:                                                                                                                                                                                           Northerly 10 to 15 knots. Offshore winds south of Eurong reaching up to 20 knots in the afternoon.
#> 38:                                                                                                                                                              Northerly 15 to 20 knots, briefly easing to 10 to 15 knots during the morning, then increasing to 15 to 20 knots around midday.
#> 39:                                                                                                                                                                  Northerly 15 to 20 knots easing to 10 to 15 knots in the early morning, then increasing to 15 to 20 knots in the afternoon.
#> 40:                                                                                                                               Northerly 15 to 20 knots easing to 10 to 15 knots in the early morning. Winds increasing to 15 to 20 knots in the afternoon, reaching up to 25 knots offshore.
#> 41:                                                                                                                                North to northwesterly 15 to 20 knots, briefly easing to 10 to 15 knots during the morning, then tending north to northeasterly 15 to 20 knots around midday.
#> 42:                                                                                                                                                                                                                                                                    Northerly 15 to 20 knots.
#> 43:                                                                                                                                                                           Northerly 15 to 20 knots easing to 10 to 15 knots before dawn, then increasing to 15 to 20 knots in the afternoon.
#> 44:                                                                                                                                                                                                                                                       North to northeasterly 15 to 20 knots.
#> 45:                                                                                                                                                                                                                                                                    Northerly 15 to 20 knots.
#>                                                                                                                 forecast_swell1
#>  1:                                                                                                                        <NA>
#>  2:                                                                                                                        <NA>
#>  3:                                                                                                                        <NA>
#>  4:                                                                                                                        <NA>
#>  5:                                                                                              Northwesterly 1 to 1.5 metres.
#>  6:                                                                                               Northwesterly around 1 metre.
#>  7:                                                                                       North to northwesterly below 1 metre.
#>  8:                                                                                               Northwesterly around 1 metre.
#>  9:                                                                                               Northwesterly around 1 metre.
#> 10:                                                                                               Northwesterly around 1 metre.
#> 11:                                                                                                     Westerly below 1 metre.
#> 12:                                                                                                     Westerly below 1 metre.
#> 13:                                                                                        West to southwesterly below 1 metre.
#> 14:                                                                                                    Northerly below 1 metre.
#> 15:                                                                                   Northeast to southeasterly below 1 metre.
#> 16:                                                                                   Northeast to southeasterly below 1 metre.
#> 17:                                                                                  Northerly around 1 metre outside the reef.
#> 18:                                                                                   Northeast to southeasterly below 1 metre.
#> 19:                                                                                                     Easterly below 1 metre.
#> 20:                                                                                  Northerly around 1 metre outside the reef.
#> 21:                                                                 Northwest to northeasterly around 1 metre outside the reef.
#> 22:                                                                                                     Easterly below 1 metre.
#> 23:                                                                             North to northwesterly around 1 metre offshore.
#> 24:                                                                              Northeasterly around 1 metre outside the reef.
#> 25:                                                                                        East to northeasterly below 1 metre.
#> 26:                                                                                                     Easterly below 1 metre.
#> 27:                                                                                        East to northeasterly below 1 metre.
#> 28:                                                                                        East to northeasterly below 1 metre.
#> 29:                                                     Easterly below 1 metre inshore, increasing to 1 to 1.5 metres offshore.
#> 30:                                                     Easterly below 1 metre inshore, increasing to 1 to 1.5 metres offshore.
#> 31:                                                      Easterly below 1 metre inshore, increasing to around 1 metre offshore.
#> 32:                                                                            Northeasterly below 1 metre in the northern bay.
#> 33:                                                                   North to northeasterly below 1 metre in the northern bay.
#> 34:                                                                   North to northeasterly below 1 metre in the northern bay.
#> 35:                                                                                                        Easterly 1.5 metres.
#> 36:                                                    Easterly around 1 metre inshore, increasing to 1 to 1.5 metres offshore.
#> 37:                                                                                                    Easterly around 1 metre.
#> 38:                                                                                                   Easterly 1 to 1.5 metres.
#> 39:                                                    Easterly around 1 metre inshore, increasing to 1 to 1.5 metres offshore.
#> 40:                                                                                                    Easterly around 1 metre.
#> 41:                                                                                                                        <NA>
#> 42:                                                                                                                        <NA>
#> 43:                                                                                                                        <NA>
#> 44:                                                                                                        Easterly 1.5 metres.
#> 45:                                                    Easterly 1 to 1.5 metres, decreasing to around 1 metre by early evening.
#>     forecast_swell2 forecast_caution marine_forecast
#>  1:            <NA>             <NA>            <NA>
#>  2:            <NA>             <NA>            <NA>
#>  3:            <NA>             <NA>            <NA>
#>  4:            <NA>             <NA>            <NA>
#>  5:            <NA>             <NA>            <NA>
#>  6:            <NA>             <NA>            <NA>
#>  7:            <NA>             <NA>            <NA>
#>  8:            <NA>             <NA>            <NA>
#>  9:            <NA>             <NA>            <NA>
#> 10:            <NA>             <NA>            <NA>
#> 11:            <NA>             <NA>            <NA>
#> 12:            <NA>             <NA>            <NA>
#> 13:            <NA>             <NA>            <NA>
#> 14:            <NA>             <NA>            <NA>
#> 15:            <NA>             <NA>            <NA>
#> 16:            <NA>             <NA>            <NA>
#> 17:            <NA>             <NA>            <NA>
#> 18:            <NA>             <NA>            <NA>
#> 19:            <NA>             <NA>            <NA>
#> 20:            <NA>             <NA>            <NA>
#> 21:            <NA>             <NA>            <NA>
#> 22:            <NA>             <NA>            <NA>
#> 23:            <NA>             <NA>            <NA>
#> 24:            <NA>             <NA>            <NA>
#> 25:            <NA>             <NA>            <NA>
#> 26:            <NA>             <NA>            <NA>
#> 27:            <NA>             <NA>            <NA>
#> 28:            <NA>             <NA>            <NA>
#> 29:            <NA>             <NA>            <NA>
#> 30:            <NA>             <NA>            <NA>
#> 31:            <NA>             <NA>            <NA>
#> 32:            <NA>             <NA>            <NA>
#> 33:            <NA>             <NA>            <NA>
#> 34:            <NA>             <NA>            <NA>
#> 35:            <NA>             <NA>            <NA>
#> 36:            <NA>             <NA>            <NA>
#> 37:            <NA>             <NA>            <NA>
#> 38:            <NA>             <NA>            <NA>
#> 39:            <NA>             <NA>            <NA>
#> 40:            <NA>             <NA>            <NA>
#> 41:            <NA>             <NA>            <NA>
#> 42:            <NA>             <NA>            <NA>
#> 43:            <NA>             <NA>            <NA>
#> 44:            <NA>             <NA>            <NA>
#> 45:            <NA>             <NA>            <NA>
#>     tropical_system_location forecast_waves
#>  1:                       NA             NA
#>  2:                       NA             NA
#>  3:                       NA             NA
#>  4:                       NA             NA
#>  5:                       NA             NA
#>  6:                       NA             NA
#>  7:                       NA             NA
#>  8:                       NA             NA
#>  9:                       NA             NA
#> 10:                       NA             NA
#> 11:                       NA             NA
#> 12:                       NA             NA
#> 13:                       NA             NA
#> 14:                       NA             NA
#> 15:                       NA             NA
#> 16:                       NA             NA
#> 17:                       NA             NA
#> 18:                       NA             NA
#> 19:                       NA             NA
#> 20:                       NA             NA
#> 21:                       NA             NA
#> 22:                       NA             NA
#> 23:                       NA             NA
#> 24:                       NA             NA
#> 25:                       NA             NA
#> 26:                       NA             NA
#> 27:                       NA             NA
#> 28:                       NA             NA
#> 29:                       NA             NA
#> 30:                       NA             NA
#> 31:                       NA             NA
#> 32:                       NA             NA
#> 33:                       NA             NA
#> 34:                       NA             NA
#> 35:                       NA             NA
#> 36:                       NA             NA
#> 37:                       NA             NA
#> 38:                       NA             NA
#> 39:                       NA             NA
#> 40:                       NA             NA
#> 41:                       NA             NA
#> 42:                       NA             NA
#> 43:                       NA             NA
#> 44:                       NA             NA
#> 45:                       NA             NA
#>  [ reached getOption("max.print") -- omitted 5 rows ]
```


## Using get_historical()

`get_historical()` takes either of two arguments: `stationid` and `latlon`, as 
well as a type of observation (`"rain"`, `"min"` (temperature), `"max"`
(temperature), or `"solar"`), returning the historical daily weather
observations of that type for the given location. An optional fourth argument,
`meta` returns a `list()` object of two data frames when set to `TRUE`. The
first table, `"meta"`, will include metadata on the station and data. The second
table, `"historical_data"`, will be as discussed in *Results* below.

If `latlon` is used, the observations returned are from the station nearest to
that latitude-longitude coordinate. `latlon` values are entered as decimal
degrees, _e.g._ -34, 151 for Sydney. The function also emits a message, to
tell the user which station was used.

### Results

The table returned may have different fields depending on the station that is
selected. The time period over which observations are available will be highly
dependent on the station requested. Some stations may only have a decade or less
of data (e.g. max temperature at `070351 (CANBERRA AIRPORT)` has ~3,700+
observations back to 2008) while others may have very extensive records (e.g.
rainfall at `ADELAIDE (WEST TERRACE / NGAYIRDAPIRA)` has ~65,000+ observations
back to 1839, three years after the city was founded.)

The optional metadata table will always have the following fields 
  
  - **site**: BOM station ID
  
  - **name**: BOM station name.
  
  - **lat**: Latitude in decimal degrees.
  
  - **lon**: Longitude in decimal degrees.
  
  - **start**: Date observations start.
  
  - **end**: Date observations end.
  
  - **years**: Available number of years data.
  
  - **percent**: Percent complete.
  
  - **AWS**: Automated weather station?
  
  - **type**: Measurement types available for the station.

### Example

Following is an example fetching the historical daily temperature minimum
observations for the station closest to 35.2809°S, 149.1300°E (Canberra).


```r
(Canberra_mintemps <- get_historical(latlon = c(-35.2809, 149.1300),
                                     type = "min"))
#> Closest station: 070351 (CANBERRA AIRPORT)
#> Data saved as /var/folders/yv/4xy6zs3x5qsgj96389nkjvtw0000gn/T//RtmpVoC8GU/IDCJAC0011_070351_1800_Data.csv
#>   --- Australian Bureau of Meteorology (BOM) Data Resource ---
#>   (Original Request Parameters)
#>   Station:		CANBERRA AIRPORT [070351] 
#>   Location:		lat: -35.3088, lon: 149.2004
#>   Measurement / Origin:	Min / Historical
#>   Timespan:		2008-09-01 -- 2020-01-01 [11.4 years]
#>   ---------------------------------------------------------------  
#>       product_code station_number year month day min_temperature
#>    1:   IDCJAC0011          70351 2008     1   1              NA
#>    2:   IDCJAC0011          70351 2008     1   2              NA
#>    3:   IDCJAC0011          70351 2008     1   3              NA
#>    4:   IDCJAC0011          70351 2008     1   4              NA
#>    5:   IDCJAC0011          70351 2008     1   5              NA
#>   ---                                                           
#> 4399:   IDCJAC0011          70351 2020     1  16            15.9
#> 4400:   IDCJAC0011          70351 2020     1  17            16.5
#> 4401:   IDCJAC0011          70351 2020     1  18            17.1
#> 4402:   IDCJAC0011          70351 2020     1  19            13.6
#> 4403:   IDCJAC0011          70351 2020     1  20            16.0
#>       accum_days_min quality
#>    1:             NA        
#>    2:             NA        
#>    3:             NA        
#>    4:             NA        
#>    5:             NA        
#>   ---                       
#> 4399:              1       N
#> 4400:              1       N
#> 4401:              1       N
#> 4402:              1       N
#> 4403:              1       N
```

## Using sweep_for_stations()

`sweep_for_stations()` only takes one argument, `latlon`, a length-2 numeric
vector. By default, this is Canberra (approximately).

### Results

This function will search for weather stations and return a data frame of all
weather stations (in this package) sorted by distance from `latlon`, ascending.
The fields in the data frame are:

**name** - station name

**lat** - latitude (decimal degrees)

**lon** - longitude (decimal degrees)

**distance** - distance from provided `latlon` value (kilometres).

### Example  

Following is an example sweeping for stations starting with Canberra.


```r
# Show only the first ten stations in the list
head(sweep_for_stations(latlon = c(-35.3, 149.2)), 10)
#>       site dist                              name start  end      lat
#>  1: 070351   70                  CANBERRA AIRPORT  2008 2020 -35.3088
#>  2: 070339   70 TUGGERANONG (ISABELLA PLAINS) AWS  1996 2020 -35.4184
#>  3: 070349   70                  MOUNT GININI AWS  2004 2020 -35.5293
#>  4: 070341   70 CAPTAINS FLAT (COWANGERONG RADAR)  2002 2020 -35.6614
#>  5: 069132   69          BRAIDWOOD RACECOURSE AWS  1985 2020 -35.4253
#>  6: 073007   73                    BURRINJUCK DAM  1908 2020 -34.9997
#>  7: 070330   70              GOULBURN AIRPORT AWS  1988 2020 -34.8085
#>  8: 070263   70                     GOULBURN TAFE  1971 2020 -34.7495
#>  9: 069128   69                       NERRIGA AWS  2013 2020 -35.1103
#> 10: 069049   69                 NERRIGA COMPOSITE  1898 2020 -35.1165
#>          lon state  elev bar_ht   wmo state_code
#>  1: 149.2004   ACT 577.1  577.6 94926       <NA>
#>  2: 149.0937   ACT 586.7  587.5 94925       <NA>
#>  3: 148.7721   ACT 760.0     NA 95925       <NA>
#>  4: 149.5122   NSW 358.0     NA 99089          N
#>  5: 149.7835   NSW 665.2  666.0 94927          N
#>  6: 148.5984   NSW 390.0     NA 94909          N
#>  7: 149.7311   NSW 640.0  640.8 95716          N
#>  8: 149.7034   NSW 670.0     NA 94716          N
#>  9: 150.0826   NSW 622.0  625.6 94943          N
#> 10: 150.0847   NSW 630.0     NA 94942          N
#>                                                        url   distance
#>  1: http://www.bom.gov.au/fwo/IDN60903/IDN60903.94926.json  0.9791884
#>  2: http://www.bom.gov.au/fwo/IDN60903/IDN60903.94925.json 16.3172787
#>  3: http://www.bom.gov.au/fwo/IDN60903/IDN60903.95925.json 46.4084466
#>  4: http://www.bom.gov.au/fwo/IDN60801/IDN60801.99089.json 49.1327086
#>  5: http://www.bom.gov.au/fwo/IDN60801/IDN60801.94927.json 54.7153470
#>  6: http://www.bom.gov.au/fwo/IDN60801/IDN60801.94909.json 64.0835316
#>  7: http://www.bom.gov.au/fwo/IDN60801/IDN60801.95716.json 72.9652110
#>  8: http://www.bom.gov.au/fwo/IDN60801/IDN60801.94716.json 76.4731323
#>  9: http://www.bom.gov.au/fwo/IDN60801/IDN60801.94943.json 82.9176026
#> 10: http://www.bom.gov.au/fwo/IDN60801/IDN60801.94942.json 82.9268575
```


## Using sweep_for_forecast_towns()

`sweep_for_forecast_towns()` only takes one argument, `latlon`, a length-2
numeric vector. By default, this is Canberra (approximately).

### Results

This function will search for weather stations and return a data frame of all
weather stations (in this package) sorted by distance from `latlon`, ascending.
The fields in the data frame are:

**name** - forecast town

**lat** - latitude (decimal degrees)

**lon** - longitude (decimal degrees)

**distance** - distance from provided `latlon` value (kilometres).

### Example  

Following is an example sweeping for forecast towns starting with Canberra.


```r
# Show only the first ten towns in the list
head(sweep_for_forecast_towns(latlon = c(-35.3, 149.2)), 10)
#>           aac              town      lon       lat   elev  distance
#>  1: NSW_PT027          Canberra 149.2003 -35.30880  577.6  0.978894
#>  2: NSW_PT235        Queanbeyan 149.2346 -35.34850  612.0  6.239984
#>  3: NSW_PT329 Portable RFSACT03 149.3162 -35.31110  719.0 10.616459
#>  4: NSW_PT281      Woden Valley 149.0845 -35.34844  610.0 11.778605
#>  5: NSW_PT254         Belconnen 149.0677 -35.23538  570.0 13.997058
#>  6: NSW_PT267         Gungahlin 149.1376 -35.18473  621.5 14.015011
#>  7: NSW_PT146       Tuggeranong 149.0953 -35.41860  586.7 16.250020
#>  8: NSW_PT327 Portable RFSACT01 148.9301 -35.45950  834.0 30.220844
#>  9: NSW_PT328 Portable RFSACT02 148.8485 -35.10660  749.0 38.502293
#> 10: NSW_PT093      Mount Ginini 148.7725 -35.52930 1760.0 46.374833
```

## Using the update functions

bomrang uses internal databases of station location data from BOM to provide
location and other metadata, _e.g._ elevation, station names, WMO codes, etc. to
make the process of querying for weather data faster. These databases are
created and packaged with bomrang for distribution and are updated with new
releases. Users have the option of updating these databases after installing
bomrang. While this option gives the users the ability to keep the databases
up-to-date and gives bomrang's authors flexibility in maintaining it, this
also means that reproducibility may be affected since the same version of
bomrang may have different databases on different machines. If reproducibility
is necessary, care should be taken to ensure that the version of the databases
is the same across different machines.

The databases consist of three files, used by bomrang, `AAC_codes.rda`, 
`JSONurl_latlon_by_station_name.rda` and `stations_site_list.rda`. These files
can be located on your local system by using the following command, 


```r
paste0(.libPaths(), "/bomrang/extdata")[1]
```

unless you have specified another location for library installations and
installed bomrang there, in which case it would still be in `bomrang/extdata`.

### Using update_forecast_towns()

`update_forecast_towns()` downloads the latest précis forecast locations
from the BOM server and updates bomrang's internal database of towns used for
forecast locations. This database is distributed with the package to make the
process faster when fetching the forecast. 

### Example

Following is an example updating the précis forecast locations internal
database.


```r
update_forecast_towns()
```

### Using update_station_locations

`update_station_locations()` downloads the latest station locations and metadata
and updates bomrang's internal databases that support the use of
`get_current_weather()` and `get_ag_bulletin()`. There is no need to use this
unless you know that a station exists in BOM's database that is not available in
the databases distributed with bomrang

### Example

Following is an example updating the précis forecast locations internal
database.


```r
update_station_locations()
```

## Using bomrang to retrieve satellite imagery

bomrang provides functionality to retrieve high-definition GeoTIFF satellite
imagery provided by BOM through public FTP with the following types of imagery
being available: i.)
[Infrared images](http://www.bom.gov.au/australia/satellite/about_images.shtml#ir),
ii.)
[Visible images](http://www.bom.gov.au/australia/satellite/about_images.shtml#vis)
and iii.)
[Clouds/surface composite](http://www.bom.gov.au/australia/satellite/about_images.shtml#cloud).

Valid BOM satellite Product IDs for GeoTIFF files include:

<table>
<tr><th>Product ID</th><th>Description</th><th>Type</th><th>Delete time</th></tr>
<tr><td>IDE00420</td><td>AHI cloud cover only 2km FD GEOS </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00421</td><td>AHI IR (Ch13) greyscale 2km FD GEOS </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00422</td><td>AHI VIS (Ch3) greyscale 2km FD GEOS </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00423</td><td>AHI IR (Ch13) Zehr 2km FD GEOS </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00425</td><td>AHI VIS (true colour) / IR (Ch13 greyscale) composite 1km FD GEOS </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00426</td><td>AHI VIS (true colour) / IR (Ch13 greyscale) composite 2km FD GEOS </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00427</td><td>AHI WV (Ch8) 2km FD GEOS </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00430</td><td>AHI cloud cover only 2km AUS equirect. </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00431</td><td>AHI IR (Ch13) greyscale 2km AUS equirect. </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00432</td><td>AHI VIS (Ch3) greyscale 2km AUS equirect. </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00433</td><td>AHI IR (Ch13) Zehr 2km AUS equirect. </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00435</td><td>AHI VIS (true colour) / IR (Ch13 greyscale) composite 1km AUS equirect. </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00436</td><td>AHI VIS (true colour) / IR (Ch13 greyscale) composite 2km AUS equirect. </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00437</td><td>AHI WV (Ch8) 2km AUS equirect. </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td>IDE00439</td><td>AHI VIS (Ch3) greyscale 0.5km AUS equirect. </td><td>Satellite</td><td style= "text-align: center;">24</td></tr>
<tr><td colspan = 3><strong>Information gathered from Australian Bureau of Meteorology (BOM)</strong></td></tr>
</table>

### Using get_available_imagery()

`get_available_imagery()` only takes one argument, `product_id`, a BOM identifier
for the imagery that you wish to check for available imagery. Using this
function will fetch a listing of BOM GeoTIFF satellite imagery from
[ftp://ftp.bom.gov.au/anon/gen/gms/](ftp://ftp.bom.gov.au/anon/gen/gms/) to
display which files are currently available for download. These files are
available at ten minute update frequency with a 24 hour delete time. 
This function can be used see the most recent files available and then specify
in the `_imagery()` function. If no valid Product ID is supplied,
defaults to all GeoTIFF images currently available.


```r
(avail <- get_available_imagery(product_id = "IDE00425"))
#> 
#> The following files are currently available for download:
#>   [1] "IDE00425.202001182310.tif" "IDE00425.202001182320.tif"
#>   [3] "IDE00425.202001182330.tif" "IDE00425.202001182340.tif"
#>   [5] "IDE00425.202001182350.tif" "IDE00425.202001190000.tif"
#>   [7] "IDE00425.202001190010.tif" "IDE00425.202001190020.tif"
#>   [9] "IDE00425.202001190030.tif" "IDE00425.202001190040.tif"
#>  [11] "IDE00425.202001190050.tif" "IDE00425.202001190100.tif"
#>  [13] "IDE00425.202001190110.tif" "IDE00425.202001190120.tif"
#>  [15] "IDE00425.202001190130.tif" "IDE00425.202001190140.tif"
#>  [17] "IDE00425.202001190150.tif" "IDE00425.202001190200.tif"
#>  [19] "IDE00425.202001190210.tif" "IDE00425.202001190220.tif"
#>  [21] "IDE00425.202001190230.tif" "IDE00425.202001190250.tif"
#>  [23] "IDE00425.202001190300.tif" "IDE00425.202001190310.tif"
#>  [25] "IDE00425.202001190320.tif" "IDE00425.202001190330.tif"
#>  [27] "IDE00425.202001190340.tif" "IDE00425.202001190350.tif"
#>  [29] "IDE00425.202001190400.tif" "IDE00425.202001190410.tif"
#>  [31] "IDE00425.202001190420.tif" "IDE00425.202001190430.tif"
#>  [33] "IDE00425.202001190440.tif" "IDE00425.202001190450.tif"
#>  [35] "IDE00425.202001190500.tif" "IDE00425.202001190510.tif"
#>  [37] "IDE00425.202001190520.tif" "IDE00425.202001190530.tif"
#>  [39] "IDE00425.202001190540.tif" "IDE00425.202001190550.tif"
#>  [41] "IDE00425.202001190600.tif" "IDE00425.202001190610.tif"
#>  [43] "IDE00425.202001190620.tif" "IDE00425.202001190630.tif"
#>  [45] "IDE00425.202001190640.tif" "IDE00425.202001190650.tif"
#>  [47] "IDE00425.202001190700.tif" "IDE00425.202001190710.tif"
#>  [49] "IDE00425.202001190720.tif" "IDE00425.202001190730.tif"
#>  [51] "IDE00425.202001190740.tif" "IDE00425.202001190750.tif"
#>  [53] "IDE00425.202001190800.tif" "IDE00425.202001190810.tif"
#>  [55] "IDE00425.202001190820.tif" "IDE00425.202001190830.tif"
#>  [57] "IDE00425.202001190840.tif" "IDE00425.202001190850.tif"
#>  [59] "IDE00425.202001190900.tif" "IDE00425.202001190910.tif"
#>  [61] "IDE00425.202001190920.tif" "IDE00425.202001190930.tif"
#>  [63] "IDE00425.202001190940.tif" "IDE00425.202001190950.tif"
#>  [65] "IDE00425.202001191000.tif" "IDE00425.202001191010.tif"
#>  [67] "IDE00425.202001191020.tif" "IDE00425.202001191030.tif"
#>  [69] "IDE00425.202001191040.tif" "IDE00425.202001191050.tif"
#>  [71] "IDE00425.202001191100.tif" "IDE00425.202001191110.tif"
#>  [73] "IDE00425.202001191120.tif" "IDE00425.202001191130.tif"
#>  [75] "IDE00425.202001191140.tif" "IDE00425.202001191150.tif"
#>  [77] "IDE00425.202001191200.tif" "IDE00425.202001191210.tif"
#>  [79] "IDE00425.202001191220.tif" "IDE00425.202001191230.tif"
#>  [81] "IDE00425.202001191240.tif" "IDE00425.202001191250.tif"
#>  [83] "IDE00425.202001191300.tif" "IDE00425.202001191310.tif"
#>  [85] "IDE00425.202001191320.tif" "IDE00425.202001191330.tif"
#>  [87] "IDE00425.202001191340.tif" "IDE00425.202001191350.tif"
#>  [89] "IDE00425.202001191400.tif" "IDE00425.202001191410.tif"
#>  [91] "IDE00425.202001191420.tif" "IDE00425.202001191430.tif"
#>  [93] "IDE00425.202001191450.tif" "IDE00425.202001191500.tif"
#>  [95] "IDE00425.202001191510.tif" "IDE00425.202001191520.tif"
#>  [97] "IDE00425.202001191530.tif" "IDE00425.202001191540.tif"
#>  [99] "IDE00425.202001191550.tif" "IDE00425.202001191600.tif"
#> [101] "IDE00425.202001191610.tif" "IDE00425.202001191620.tif"
#> [103] "IDE00425.202001191630.tif" "IDE00425.202001191640.tif"
#> [105] "IDE00425.202001191650.tif" "IDE00425.202001191700.tif"
#> [107] "IDE00425.202001191710.tif" "IDE00425.202001191720.tif"
#> [109] "IDE00425.202001191730.tif" "IDE00425.202001191740.tif"
#> [111] "IDE00425.202001191750.tif" "IDE00425.202001191800.tif"
#> [113] "IDE00425.202001191810.tif" "IDE00425.202001191820.tif"
#> [115] "IDE00425.202001191830.tif" "IDE00425.202001191840.tif"
#> [117] "IDE00425.202001191850.tif" "IDE00425.202001191900.tif"
#> [119] "IDE00425.202001191910.tif" "IDE00425.202001191920.tif"
#> [121] "IDE00425.202001191930.tif" "IDE00425.202001191940.tif"
#> [123] "IDE00425.202001191950.tif" "IDE00425.202001192000.tif"
#> [125] "IDE00425.202001192010.tif" "IDE00425.202001192020.tif"
#> [127] "IDE00425.202001192030.tif" "IDE00425.202001192040.tif"
#> [129] "IDE00425.202001192050.tif" "IDE00425.202001192100.tif"
#> [131] "IDE00425.202001192110.tif" "IDE00425.202001192120.tif"
#> [133] "IDE00425.202001192130.tif" "IDE00425.202001192140.tif"
#> [135] "IDE00425.202001192150.tif" "IDE00425.202001192200.tif"
#> [137] "IDE00425.202001192210.tif" "IDE00425.202001192220.tif"
#> [139] "IDE00425.202001192230.tif" "IDE00425.202001192240.tif"
#> [141] "IDE00425.202001192250.tif" "IDE00425.202001192300.tif"
#> [143] "IDE00425.202001192310.tif" "IDE00425.202001192320.tif"
#> [145] "IDE00425.202001192330.tif" "IDE00425.202001192340.tif"
#>   [1] "IDE00425.202001182310.tif" "IDE00425.202001182320.tif"
#>   [3] "IDE00425.202001182330.tif" "IDE00425.202001182340.tif"
#>   [5] "IDE00425.202001182350.tif" "IDE00425.202001190000.tif"
#>   [7] "IDE00425.202001190010.tif" "IDE00425.202001190020.tif"
#>   [9] "IDE00425.202001190030.tif" "IDE00425.202001190040.tif"
#>  [11] "IDE00425.202001190050.tif" "IDE00425.202001190100.tif"
#>  [13] "IDE00425.202001190110.tif" "IDE00425.202001190120.tif"
#>  [15] "IDE00425.202001190130.tif" "IDE00425.202001190140.tif"
#>  [17] "IDE00425.202001190150.tif" "IDE00425.202001190200.tif"
#>  [19] "IDE00425.202001190210.tif" "IDE00425.202001190220.tif"
#>  [21] "IDE00425.202001190230.tif" "IDE00425.202001190250.tif"
#>  [23] "IDE00425.202001190300.tif" "IDE00425.202001190310.tif"
#>  [25] "IDE00425.202001190320.tif" "IDE00425.202001190330.tif"
#>  [27] "IDE00425.202001190340.tif" "IDE00425.202001190350.tif"
#>  [29] "IDE00425.202001190400.tif" "IDE00425.202001190410.tif"
#>  [31] "IDE00425.202001190420.tif" "IDE00425.202001190430.tif"
#>  [33] "IDE00425.202001190440.tif" "IDE00425.202001190450.tif"
#>  [35] "IDE00425.202001190500.tif" "IDE00425.202001190510.tif"
#>  [37] "IDE00425.202001190520.tif" "IDE00425.202001190530.tif"
#>  [39] "IDE00425.202001190540.tif" "IDE00425.202001190550.tif"
#>  [41] "IDE00425.202001190600.tif" "IDE00425.202001190610.tif"
#>  [43] "IDE00425.202001190620.tif" "IDE00425.202001190630.tif"
#>  [45] "IDE00425.202001190640.tif" "IDE00425.202001190650.tif"
#>  [47] "IDE00425.202001190700.tif" "IDE00425.202001190710.tif"
#>  [49] "IDE00425.202001190720.tif" "IDE00425.202001190730.tif"
#>  [51] "IDE00425.202001190740.tif" "IDE00425.202001190750.tif"
#>  [53] "IDE00425.202001190800.tif" "IDE00425.202001190810.tif"
#>  [55] "IDE00425.202001190820.tif" "IDE00425.202001190830.tif"
#>  [57] "IDE00425.202001190840.tif" "IDE00425.202001190850.tif"
#>  [59] "IDE00425.202001190900.tif" "IDE00425.202001190910.tif"
#>  [61] "IDE00425.202001190920.tif" "IDE00425.202001190930.tif"
#>  [63] "IDE00425.202001190940.tif" "IDE00425.202001190950.tif"
#>  [65] "IDE00425.202001191000.tif" "IDE00425.202001191010.tif"
#>  [67] "IDE00425.202001191020.tif" "IDE00425.202001191030.tif"
#>  [69] "IDE00425.202001191040.tif" "IDE00425.202001191050.tif"
#>  [71] "IDE00425.202001191100.tif" "IDE00425.202001191110.tif"
#>  [73] "IDE00425.202001191120.tif" "IDE00425.202001191130.tif"
#>  [75] "IDE00425.202001191140.tif" "IDE00425.202001191150.tif"
#>  [77] "IDE00425.202001191200.tif" "IDE00425.202001191210.tif"
#>  [79] "IDE00425.202001191220.tif" "IDE00425.202001191230.tif"
#>  [81] "IDE00425.202001191240.tif" "IDE00425.202001191250.tif"
#>  [83] "IDE00425.202001191300.tif" "IDE00425.202001191310.tif"
#>  [85] "IDE00425.202001191320.tif" "IDE00425.202001191330.tif"
#>  [87] "IDE00425.202001191340.tif" "IDE00425.202001191350.tif"
#>  [89] "IDE00425.202001191400.tif" "IDE00425.202001191410.tif"
#>  [91] "IDE00425.202001191420.tif" "IDE00425.202001191430.tif"
#>  [93] "IDE00425.202001191450.tif" "IDE00425.202001191500.tif"
#>  [95] "IDE00425.202001191510.tif" "IDE00425.202001191520.tif"
#>  [97] "IDE00425.202001191530.tif" "IDE00425.202001191540.tif"
#>  [99] "IDE00425.202001191550.tif" "IDE00425.202001191600.tif"
#> [101] "IDE00425.202001191610.tif" "IDE00425.202001191620.tif"
#> [103] "IDE00425.202001191630.tif" "IDE00425.202001191640.tif"
#> [105] "IDE00425.202001191650.tif" "IDE00425.202001191700.tif"
#> [107] "IDE00425.202001191710.tif" "IDE00425.202001191720.tif"
#> [109] "IDE00425.202001191730.tif" "IDE00425.202001191740.tif"
#> [111] "IDE00425.202001191750.tif" "IDE00425.202001191800.tif"
#> [113] "IDE00425.202001191810.tif" "IDE00425.202001191820.tif"
#> [115] "IDE00425.202001191830.tif" "IDE00425.202001191840.tif"
#> [117] "IDE00425.202001191850.tif" "IDE00425.202001191900.tif"
#> [119] "IDE00425.202001191910.tif" "IDE00425.202001191920.tif"
#> [121] "IDE00425.202001191930.tif" "IDE00425.202001191940.tif"
#> [123] "IDE00425.202001191950.tif" "IDE00425.202001192000.tif"
#> [125] "IDE00425.202001192010.tif" "IDE00425.202001192020.tif"
#> [127] "IDE00425.202001192030.tif" "IDE00425.202001192040.tif"
#> [129] "IDE00425.202001192050.tif" "IDE00425.202001192100.tif"
#> [131] "IDE00425.202001192110.tif" "IDE00425.202001192120.tif"
#> [133] "IDE00425.202001192130.tif" "IDE00425.202001192140.tif"
#> [135] "IDE00425.202001192150.tif" "IDE00425.202001192200.tif"
#> [137] "IDE00425.202001192210.tif" "IDE00425.202001192220.tif"
#> [139] "IDE00425.202001192230.tif" "IDE00425.202001192240.tif"
#> [141] "IDE00425.202001192250.tif" "IDE00425.202001192300.tif"
#> [143] "IDE00425.202001192310.tif" "IDE00425.202001192320.tif"
#> [145] "IDE00425.202001192330.tif" "IDE00425.202001192340.tif"
```

### Using get_satellite_imagery()

`get_satellite_imagery()` fetches BOM satellite GeoTIFF imagery, returning a
raster stack object and takes three arguments. Files are available at
ten minute update frequency with a 24 hour delete time. It is suggested to check
file availability first by using `get_available_imagery()`. The arguments
are:

- `product_id`, a character value of the BOM product ID to download.
Alternatively, a vector of values from `get_available_imagery()` may be used
here. This argument is mandatory.

- `scans` a numeric value for the number of scans to download, starting with the
most recent and progressing backwards, *e.g.*, `1` - the most recent single scan
available , `6` - the most recent hour available, `12` - the most recent 2 hours
available, etc. Negating will return the oldest files first. Defaults to 1. This
argument is optional.

- `cache` a logical value that indicates whether or not to store image files
locally for later use?  If `FALSE`, the downloaded files are removed when R
session is closed. To take advantage of cached files in future sessions, set 
`TRUE`. Defaults to `FALSE`. This argument is optional. Cached files may be
managed with the `manage_cache()` function.


```r
# Specify product ID and scans
i <- get_satellite_imagery(product_id = "IDE00425", scans = 1)

# Same, but use "avail" from prior to specify images for download
i <- get_satellite_imagery(product_id = avail, scans = 1)

# Cache image for later use
i <- get_satellite_imagery(product_id = avail, scans = 1, cache = TRUE)

plot(i)
```

<img src="get_satellite_imagery-1.png" title="plot of chunk get_satellite_imagery" alt="plot of chunk get_satellite_imagery" style="display: block; margin: auto;" />

## Using caching for satellite imagery

If you elect to use `cache = TRUE` when downloading imagery, note that the GTiff
files can be quite large and will fill disk space. By using the default
`cache = FALSE` the files will be deleted when the current R session is closed.

Should you chose to use caching, bomrang provided functions to interact with
the cached files:

- List files in the cache, `manage_cache$list()`
  
    - List info for single files,
  
        - `manage_cache$list()[1])`
  
        - `manage_cache$list()[2])`

- List info for all files, `manage_cache$details()`

- Delete files by name in cache, `manage_cache$delete()`

- Delete all files in cache, `manage_cache$delete_all()`

To access the files directly, outside of R, the following command will give you
the location of the directory:

`manage_cache$cache_path_get()`

## Using bomrang to retrieve radar imagery

bomrang provides functionality to retrieve the latest radar imagery provided
by BOM through public FTP. These are the latest snapshots for each radar
locations at various radar ranges _e.g._, 512km, 256km, 128km and 64km for some
stations.

### Using get_available_radar()

`get_available_radar()` fetches the available radar imagery from the BOM FTP and
returns a data frame for reference. This data frame contains the product_id 
which is required when using the `get_radar_imagery()` function. The files
available are the latest `.gif` files of BOM radar imagery which are typically
updated each 6-10 minutes. Only the most recent image is retrieved for each
radar location. There are usually several radar ranges available for each radar
location, such as 512km, 256km, 128km and possibly 64km. The arguments are:

* `radar_id`  which is the BOM radar ID number. This defaults to 'all' which 
will return a data frame of all radar ID's in Australia.


```r
x <- get_available_radar()
head(x)  
#>   product_id LocationID range         Name Longitude  Latitude
#> 1     IDR011         01 512km Broadmeadows  144.9460 -37.69100
#> 2     IDR012         01 256km Broadmeadows  144.9460 -37.69100
#> 3     IDR013         01 128km Broadmeadows  144.9460 -37.69100
#> 4     IDR014         01  64km Broadmeadows  144.9460 -37.69100
#> 5     IDR021         02 512km    Melbourne  144.7554 -37.85525
#> 6     IDR022         02 256km    Melbourne  144.7554 -37.85525
#>   Radar_id                Full_Name IDRnn0name IDRnn1name State
#> 1        1 Melbourne (Broadmeadows)     CampRd     CampRd   VIC
#> 2        1 Melbourne (Broadmeadows)     CampRd     CampRd   VIC
#> 3        1 Melbourne (Broadmeadows)     CampRd     CampRd   VIC
#> 4        1 Melbourne (Broadmeadows)     CampRd     CampRd   VIC
#> 5        2     Melbourne (Laverton)       Melb  Melbourne   VIC
#> 6        2     Melbourne (Laverton)       Melb  Melbourne   VIC
#>      Type Group    Status Archive
#> 1 Doppler   Yes Reg_users  CampRd
#> 2 Doppler   Yes Reg_users  CampRd
#> 3 Doppler   Yes Reg_users  CampRd
#> 4 Doppler   Yes Reg_users  CampRd
#> 5 Doppler   Yes    Public    Melb
#> 6 Doppler   Yes    Public    Melb
```

### Using get_radar_imagery()

`get_radar_imagery()` fetches the latest BOM radar imagery for a given product
ID. The files available are the latest `.gif` files of BOM radar imagery which
are typically updated each 6-10 minutes. Only the most recent image is retrieved
for each radar location. There are usually several radar ranges available for
each radar location, such as 512km, 256km, 128km and possibly 64km. The only
argument is:

* `product_id` the BOM product_id associated with each radar imagery file. 
These can be obtained from the `get_available_radar()` function. This value must
be specified and the function will accept only one at a time.


```r
library(raster)
x <- get_radar_imagery(product_id = "IDR032")
#> file downloaded to:/var/folders/yv/4xy6zs3x5qsgj96389nkjvtw0000gn/T//RtmpVoC8GU/file5fa26a776376.gif

# create a blank raster plot and add the radar layer
r <-
  raster::raster(
  ncol = 564,
  nrow = 524,
  xmn = 0,
  xmx = 524,
  ymn = 0,
  ymx = 564
  )
  values(r) <- NA
  plot(r)
  plot(x, add = TRUE)
```

<img src="get_radar_imagery-1.png" title="plot of chunk get_radar_imagery" alt="plot of chunk get_radar_imagery" style="display: block; margin: auto;" />

# dplyr compatibility

Some returned objects have been classed as `bomrang_tbl` which allow dispatch for 
dplyr methods, _e.g._ `mutate()`, `filter()`, `select()`, `arrange()`, `slice()`,
`rename()`, and `group_by()` while preserving the header information.

For example:


```r
adlmax <- get_historical(stationid = "023000", type = "max")
#> Data saved as /var/folders/yv/4xy6zs3x5qsgj96389nkjvtw0000gn/T//RtmpVoC8GU/IDCJAC0010_023000_1800_Data.csv
adlmax
#>   --- Australian Bureau of Meteorology (BOM) Data Resource ---
#>   (Original Request Parameters)
#>   Station:		ADELAIDE (WEST TERRACE / NGAYIRDAPIRA) [023000] 
#>   Location:		lat: -34.9257, lon: 138.5832
#>   Measurement / Origin:	Max / Historical
#>   Timespan:		1887-01-01 -- 2020-01-01 [94.8 years]
#>   ---------------------------------------------------------------  
#>        product_code station_number year month day max_temperature
#>     1:   IDCJAC0010          23000 1887     1   1              NA
#>     2:   IDCJAC0010          23000 1887     1   2              NA
#>     3:   IDCJAC0010          23000 1887     1   3              NA
#>     4:   IDCJAC0010          23000 1887     1   4              NA
#>     5:   IDCJAC0010          23000 1887     1   5              NA
#>    ---                                                           
#> 48592:   IDCJAC0010          23000 2020     1  15            26.5
#> 48593:   IDCJAC0010          23000 2020     1  16            23.6
#> 48594:   IDCJAC0010          23000 2020     1  17            24.0
#> 48595:   IDCJAC0010          23000 2020     1  18            26.1
#> 48596:   IDCJAC0010          23000 2020     1  19            22.2
#>        accum_days_max quality
#>     1:             NA        
#>     2:             NA        
#>     3:             NA        
#>     4:             NA        
#>     5:             NA        
#>    ---                       
#> 48592:              1       N
#> 48593:              1       N
#> 48594:              1       N
#> 48595:              1       N
#> 48596:              1       N

filter(adlmax, month == 10)
#>   --- Australian Bureau of Meteorology (BOM) Data Resource ---
#>   (Original Request Parameters)
#>   Station:		ADELAIDE (WEST TERRACE / NGAYIRDAPIRA) [023000] 
#>   Location:		lat: -34.9257, lon: 138.5832
#>   Measurement / Origin:	Max / Historical
#>   Timespan:		1887-01-01 -- 2020-01-01 [94.8 years]
#>   ---------------------------------------------------------------  
#>       product_code station_number year month day max_temperature
#>    1:   IDCJAC0010          23000 1887    10   1            17.6
#>    2:   IDCJAC0010          23000 1887    10   2            14.6
#>    3:   IDCJAC0010          23000 1887    10   3            16.7
#>    4:   IDCJAC0010          23000 1887    10   4            18.0
#>    5:   IDCJAC0010          23000 1887    10   5            15.1
#>   ---                                                           
#> 4119:   IDCJAC0010          23000 2019    10  27            19.5
#> 4120:   IDCJAC0010          23000 2019    10  28            25.4
#> 4121:   IDCJAC0010          23000 2019    10  29            32.7
#> 4122:   IDCJAC0010          23000 2019    10  30            35.5
#> 4123:   IDCJAC0010          23000 2019    10  31            37.2
#>       accum_days_max quality
#>    1:              1       Y
#>    2:              1       Y
#>    3:              1       Y
#>    4:              1       Y
#>    5:              1       Y
#>   ---                       
#> 4119:              1       N
#> 4120:              1       N
#> 4121:              1       N
#> 4122:              1       N
#> 4123:              1       N
```

The `magrittr` pipe has also been re-exported, so that too can be used 
to chain together operations


```r
adlmax %>% 
  select(station_number, year:day, max_temperature) %>% 
  filter(month == 10)
#>   --- Australian Bureau of Meteorology (BOM) Data Resource ---
#>   (Original Request Parameters)
#>   Station:		ADELAIDE (WEST TERRACE / NGAYIRDAPIRA) [023000] 
#>   Location:		lat: -34.9257, lon: 138.5832
#>   Measurement / Origin:	Max / Historical
#>   Timespan:		1887-01-01 -- 2020-01-01 [94.8 years]
#>   ---------------------------------------------------------------  
#>       station_number year month day max_temperature
#>    1:          23000 1887    10   1            17.6
#>    2:          23000 1887    10   2            14.6
#>    3:          23000 1887    10   3            16.7
#>    4:          23000 1887    10   4            18.0
#>    5:          23000 1887    10   5            15.1
#>   ---                                              
#> 4119:          23000 2019    10  27            19.5
#> 4120:          23000 2019    10  28            25.4
#> 4121:          23000 2019    10  29            32.7
#> 4122:          23000 2019    10  30            35.5
#> 4123:          23000 2019    10  31            37.2
```

## References

[Australian Bureau of Meteorology (BOM) Weather Data Services](http://www.bom.gov.au/catalogue/data-feeds.shtml)

[Australian Bureau of Meteorology (BOM) FTP Public Products](http://www.bom.gov.au/catalogue/anon-ftp.shtml)

[Australian Bureau of Meteorology (BOM) Weather Data Services Agriculture Bulletins](http://www.bom.gov.au/catalogue/observations/about-agricultural.shtml)

[Australian Bureau of Meteorology (BOM) Weather Data Services Observation of Rainfall](http://www.bom.gov.au/climate/how/observations/rain-measure.shtml)

[Australian Bureau of Meteorology (BOM) High-definition satellite images](http://www.bom.gov.au/australia/satellite/index.shtml)

## Appendix 1 - Output from get_current_weather()

The function `get_current_weather()` will return a data frame that will contain
some or all of the following fields.

### Fields and descriptions

<table>
<tr><th>Field Name</th><th>Description</th></tr>
<tr><td>wmo_id</td><td>wmo station index number, uniquely identifies
station</td></tr>
<tr><td>Name[31]</td><td>Observing station name</td></tr>
<tr><td>Abbr[6]</td><td>An abbreviated name (normally 4 characters) used for the
station</td></tr>
<tr><td>Date</td><td>Date, Year (4 digits), month (2 digits), day (2
digits)</td></tr>
<tr><td>Time</td><td>Time, Hours (2 digits), minutes (2 digits), UTC</td></tr>
<tr><td>Lat</td><td>Latitude, decimal degrees, S -ve, N +ve</td></tr>
<tr><td>Lon</td><td>Longitude, decimal degrees, E +ve, W -ve</td></tr>
<tr><td>Stn_typ</td><td>Station type</td></tr>
<tr><td>Stn_ht_m</td><td>Station height (in metres)</td></tr>
<tr><td>Total_cld</td><td>Total cloud cover in oktas, 9=Sky Obscured by smoke,
fog, ...</td></tr>
<tr><td>Wdir</td><td>Wind direction, degrees true</td></tr>
<tr><td>Wspd_mps</td><td>Wind speed, metres per second</td></tr>
<tr><td>Vis_m</td><td>Visibility, metres</td></tr>
<tr><td>Wx[9]</td><td>Present weather, abbreviated</td></tr>
<tr><td>Pw1</td><td>Past weather (last 3-6 hours), see below</td></tr>
<tr><td>Pw2</td><td>Past weather (Used so more than one variation can be
reported)</td></tr>
<tr><td>Msl_P</td><td>Mean Sea Level Pressure, hPa</td></tr>
<tr><td>Stn_P</td><td>Station level pressure, hPa</td></tr>
<tr><td>P_tend_typ</td><td>Type of the pressure tendency, numerical code, see
below</td></tr>
<tr><td>P_tend_val</td><td>Pressure tendency (change) in last 3 hours,
hPa</td></tr>
<tr><td>Cor_P_tend</td><td>Pressure tendency in last 3 hours corrected for
diurnal variation</td></tr>
<tr><td>T_DB</td><td>Temperature (dry bulb), degrees C</td></tr>
<tr><td>DP</td><td>Dew point, degrees C</td></tr>
<tr><td>Low_cld_amt</td><td>Amount of low cloud, oktas, 9=Sky obscured by fog,
smoke, ...</td></tr>
<tr><td>Low_cld_typ[4]</td><td>Type of low cloud, abbreviation</td></tr>
<tr><td>Cld_base_m</td><td>Base of lowest cloud, m</td></tr>
<tr><td>Cld_dir[4]</td><td>Direction of motion of low cloud, compass
point</td></tr>
<tr><td>Mid_cld_typ[4]</td><td>Type of middle level cloud, abbreviation</td></tr>
<tr><td>Hi_cld_typ[4]</td><td>Type of high cloud, abbreviation</td></tr>
<tr><td>Rf_int_h6</td><td>Interval for which rain is reported in next field,
hours</td></tr>
<tr><td>Rainfall6</td><td>Rainfall, mm, usually at 9 or 3 AM/PM</td></tr>
<tr><td>Rf_int_h4</td><td>Interval for which rain is reported in next field,
hours</td></tr>
<tr><td>Rainfall4</td><td>Rainfall, mm, usually since last
observation</td></tr>
<tr><td>Sea_state[5]</td><td>Sea state, abbreviation</td></tr>
<tr><td>Swl_state[9]</td><td>Swell state, abbreviation</td></tr>
<tr><td>Swl_dir[4]</td><td>Swell direction, abbreviation</td></tr>
<tr><td>Max_T</td><td>Maximum temperature, 24h to 9AM or 6h to 3PM local time,
degree C</td></tr>
<tr><td>Min_T</td><td>Minimum temperature, 24h to 9AM local time, degree
C</td></tr>
<tr><td>Min_grnd_T</td><td>Minimum ground temperature, 24 h to (AM local time,
degree C</td></tr>
<tr><td>Snow_depth_m</td><td>Depth of snow on ground, metres</td></tr>
<tr><td>Low_cld_code</td><td>Code for low level cloud type, see below</td></tr>
<tr><td>Mid_cld_code</td><td>Code for middle level cloud type, see
below</td></tr>
<tr><td>Hi_cld_code</td><td>Code for high level cloud type, see below</td></tr>
<tr><td>Max_T(Int)</td><td>Maximum temperature for international
exchange</td></tr>
<tr><td>Min_T(Int)</td><td>Minimum temperature for international
exchange</td></tr>
<tr><td>Plain_lang[51]</td><td>Plain language comments</td></tr>
</table>

### Codes:

P_tend_typ:

- 0 Increasing, then decreasing, current pressure same or higher  
- 1 Increasing, then steady or increasing more slowly  
- 2 Increasing  
- 3 Decreasing or steady, then increasing, or  
  - Increasing, then increasing more rapidly, current pressure higher  
- 4 Steady  
- 5 Decreasing, then increasing, current pressure lower  
- 6 Decreasing, then steady or decreasing more slowly  
- 7 Decreasing  
-8 Steady or increasing, then then decreasing, current pressure lower, or  
  - Decreasing, then decreasing more rapidly  

### Wx[9] - Present weather

This consists of a two or 3 digit code figure plus (when relevant)
a short, text abbreviation of the weather The abbreviations used (frequently
 together, _e.g._, XXRA for heavy rain, FZDZ for freezing drizzle) include

- BL Blowing (usually of sand or snow)  
- DR Drifting (usually of sand or snow)  
- DZ Drizzle  
- FC Funnel cloud (tornado, water spout)  
- FG Fog  
- FU Smoke    (from the French for smoke)  
- FZ Freezing (usually of rain or fog)  
- GR Hail     (from the French for hail)  
- HZ Haze  
- MI Shallow (can be applied to Fog etc)  
- RE Ice pellets  
- PO Dust devils  
- RA Rain  
- RE Recent (in the last hour, but not at the observation time)  
- SA Sand  
- SG Snow grains  
- SH Showers  
- SN Snow  
- SQ Squall  
- TS Thunderstorm  
- XX Heavy or intense (usually of rain or snow)  

Also, some other abbreviations used include

- lightn  Lightning  
- virga   Virga  
- RIA<5k  Precipitation in the area, less then 5km distant  

### Code figures

(This is a subset of a larger table, not all values of which are used)
wmo international BUFR code table 0 20 003, CREX code table B 20 003

	 00 Clouds not observed
	 01 Cloud decreasing
	 02 State of sky generally unchanging
	 03 Cloud increasing
	 04 Smoke or volcanic ash
	 05 Haze
	 06 Widespread dust suspended in the air, not raised locally at the
	    time of observation
	 07 Dust or sand raised locally by the wind at the time of observation,
	    but no well developed dust devils, sandstorm, or duststorm
	 08 Well developed dust devils, but no sandstorm or duststorm
	 09 Duststorm or sandstorm
	 10 Mist
	 11 Patches of shallow fog
	 12 More or less continuous shallow fog
	 13 Lightning visible, but no thunder heard
	 14 Precipitation in sight, but not reaching the ground or sea (virga)
	 15 Precipitation in sight, reaching the ground, but more than 5km away
	 16 Precipitation in sight, reaching the ground, near but not at the
	    observing station
	 17 Thunderstorm without precipitation
	 18 Squalls
	 19 Funnel clouds (tornado, water spout)
	 20 Recent (within the last hour) drizzle
	 21 Recent (within the last hour) rain, but not freezing rain
	 22 Recent (within the last hour) snow
	 23 Recent (within the last hour) mixed rain and snow or ice pellets
	 24 Recent (within the last hour) freezing drizzle or freezing rain
	 25 Recent (within the last hour) showers of rain
	 26 Recent (within the last hour) showers of snow or mixed rain and snow
	 27 Recent (within the last hour) showers of hail or mixed rain and hail
	 28 Recent (within the last hour) Fog or ice fog
	 29 Recent (within the last hour) thunderstorm
	 30 Slight or moderate duststorm or sandstorm, has decreased in the
	    last hour
	 31 Slight or moderate duststorm or sandstorm, with no appreciable
	    change in the last hour
	 32 Slight or moderate duststorm or sandstorm, has begun or
	    increased in the last hour
	 33 Severe duststorm or sandstorm, has decreased in the last hour
	 34 Severe duststorm or sandstorm, with no appreciable change in the
	    last hour
	 35 Severe duststorm or sandstorm, has begun or increased in the
	    last hour
	 36 Slight or moderate drifting snow, generally below eye level
	 37 Heavy drifting snow,  generally below eye level
	 38 Slight or moderate blowing snow, generally above eye level
	 39 Heavy blowing snow, generally above eye level
	 40 Fog or ice fog at a distance but not at the station
	 41 Patches of fog or ice fog
	 42 Fog or ice fog, sky visible, has become thinner in the last hour
	 43 Fog or ice fog, sky invisible, has become thinner in the last hour
	 44 Fog or ice fog, sky visible, no appreciable change in the last hour
	 45 Fog or ice fog, sky invisible, no appreciable change in the last
	    hour
	 46 Fog or ice fog, sky visible, has become thicker in the last hour
	 47 Fog or ice fog, sky invisible, has become thicker in the last hour
	 48 Fog, depositing rime (freezing fog), sky visible
	 49 Fog, depositing rime (freezing fog), sky invisible
	 50 Slight intermittent drizzle, not freezing
	 51 Continuous slight drizzle, not freezing
	 52 Moderate intermittent drizzle, not freezing
	 53 Continuous moderate drizzle, not freezing
	 54 Heavy intermittent drizzle, not freezing
	 55 Continuous heavy drizzle, not freezing
	 56 Slight freezing drizzle
	 57 Moderate or heavy freezing drizzle
	 58 Slight drizzle and rain (mixed)
	 59 Moderate or heavy drizzle and rain (mixed)
	 60 Slight intermittent rain, not freezing
	 61 Continuous slight rain, not freezing
	 62 Moderate intermittent rain, not freezing
	 63 Continuous moderate rain, not freezing
	 64 Heavy intermittent rain, not freezing
	 65 Continuous heavy rain, not freezing
	 66 Slight freezing rain
	 67 Moderate or heavy freezing rain
	 68 Slight rain and snow or drizzle and snow (mixed)
	 69 Moderate or heavy rain and snow or drizzle and snow (mixed)
	 70 Slight intermittent snow
	 71 Continuous slight snow
	 72 Moderate intermittent snow
	 73 Continuous moderate snow
	 74 Heavy intermittent snow
	 75 Continuous heavy snow
	 76 Diamond dust, with or without fog
	 77 Snow grains, with or without fog
	 78 Isolated star like ice crystals, with or without fog
	 79 Ice pellets
	 80 Slight rain showers or shower
	 81 Moderate or heavy rain shower or showers
	 82 Violent rain shower or showers
	 83 Slight shower or showers of mixed rain and snow
	 84 Moderate or heavy shower or showers of mixed rain and snow
	 85 Slight shower or showers of snow
	 86 Moderate or heavy shower or showers of snow
	 87 Slight shower or showers of snow pellets or small hail, with
	    or without rain or mixed rain and snow
	 88 Moderate or heavy shower or showers of snow pellets or small
	    hail, with or without rain or mixed rain and snow
	 89 Slight shower or showers of hail, with or without rain or 
	    mixed rain and snow, but no thunder
	 90 Moderate or heavy shower or showers of hail, with or without
	    rain or mixed rain and snow, but no thunder
	 91 Slight rain now, with thunder during the last hour
	 92 Moderate or heavy rain now, with thunder during the last hour
	 93 Slight snow, mixed rain and snow, or hail now, with thunder
	    during the last hour
	 94 Moderate or heavy snow, mixed rain and snow, or hail now, with
	    thunder during the last hour
	 95 Slight or moderate thunderstorm with rain or snow but no hail
	 96 Slight or moderate thunderstorm with hail
	 97 Heavy thunderstorm with rain or snow but no hail
	 98 Thunderstorm combined with a sandstorm or duststorm
	 99 Heavy thunderstorm with hail
	100 No significant weather
	101 Cloud decreasing 
	102 State of sky generally unchanging
	103 Cloud increasing
	104 Haze or smoke or suspended dust, visibility >= 1km
	105 Haze or smoke or suspended dust, visibility < 1km
	110 Mist
	111 Diamond dust
	112 Distant lightning
	118 Squalls
	120 Recent (during the last hour) fog
	121 Recent (during the last hour) precipitation
	122 Recent (during the last hour) drizzle, not freezing, or snow grains
	123 Recent (during the last hour) rain, not freezing
	124 Recent (during the last hour) snow
	125 Recent (during the last hour) freezing drizzle or freezing rain
	126 Recent (during the last hour) thunderstorm
	127 Blowing or drifting snow or sand
	128 Blowing or drifting snow or sand, visibility >= 1km
	129 Blowing or drifting snow or sand, visibility < 1km
	130 Fog
	131 Patches of fog or ice fog 
	132 Fog or ice fog, has become thinner in the last hour
	133 Fog or ice fog, no appreciable change in the last hour
	134 Fog or ice fog, has become thicker in the last hour
	135 Fog, depositing rime (freezing fog)
	140 Precipitation
	141 Slight or moderate precipitation
	142 Heavy precipitation
	143 Slight or moderate liquid precipitation
	144 Heavy liquid precipitation
	145 Slight or moderate solid precipitation
	146 Heavy solid precipitation
	147 Slight or moderate freezing precipitation
	148 Heavy freezing precipitation
	150 Drizzle
	151 Slight drizzle, not freezing
	152 Moderate drizzle, not freezing
	153 Heavy drizzle, not freezing
	154 Slight freezing drizzle
	155 Moderate freezing drizzle
	156 Heavy freezing drizzle
	157 Slight drizzle and rain
	158 Moderate or heavy drizzle and rain
	160 Rain
	161 Slight rain, not freezing
	162 Moderate rain, not freezing
	163 Heavy rain, not freezing
	164 Slight freezing rain
	165 Moderate freezing rain
	166 Heavy freezing rain
	167 Slight rain and snow or drizzle and snow
	168 Moderate or heavy rain and snow or drizzle and snow
	170 Snow
	171 Slight snow
	172 Moderate snow
	173 Heavy snow
	174 Slight ice pellets
	175 Moderate ice pellets
	176 Heavy ice pellets
	180 Shower or showers or intermittent precipitation
	181 Slight rain shower or showers or slight intermittent rain
	182 Moderate rain shower or showers or moderate intermittent rain
	183 Heavy rain shower or showers or heavy intermittent rain
	184 Violent rain shower or showers or violent intermittent rain
	185 Slight snow shower or showers or slight intermittent snow
	186 Moderate snow shower or showers or moderate intermittent snow
	187 Heavy snow shower or showers or heavy intermittent snow
	190 Thunderstorm
	191 Slight or moderate thunderstorm without precipitation
	192 Slight or moderate thunderstorm with rain showers and/or snow
	    showers
	193 Slight or moderate thunderstorm with hail
	194 Heavy thunderstorm without precipitation
	195 Heavy thunderstorm with rain showers and/or snow showers
	196 Heavy thunderstorm with hail
	199 Tornado
	508 No significant weather
	509 Data not available
	510 Data should have been reported but wasn't

#### Pw1 and Pw2 - Past weather
        wmo international BUFR code table 0 20 004, CREX code table B 20 004

	If only one type of weather has occurred in the last 3-6 hours,
only Pw1 and Pw2 will be the same. If there has been more than one, Pw1
and Pw2 should be different, with Pw1 reflecting the "more important" past
weather. Code figures 0-9 normally apply to manned stations, 10-19 to
automated weather stations.

	 0 Cloud covering less than 1/2 the sky
	 1 Cloud covering more than 1/2 the sky part of the time
	   and less than 1/2 the sky part of the time
	 2 Cloud covering more than 1/2 the sky
	 3 Sandstorm, dustorm or blowing snow
	 4 Fog, ice fog, or thick haze
	 5 Drizzle
	 6 Rain
	 7 Snow, or mixed rain and snow
	 8 Showers
	 9 Thunderstorm
	10 Nothing significant detected
	11 Reduced visibility
	12 Blowing phenomena (sand, dust, snow, ...) reducing visibility
	13 Fog
	14 Precipitation (rain, snow, hail, ...)
	15 Drizzle
	16 Rain
	17 Snow or ice pellets
	18 Showers or intermittent precipitation
	19 Thunderstorm
	 
#### Low_cld_code:
	(This is a subset of a larger table, not all values of which are used)
	wmo international BUFR code table 0 20 012, CREX code table B 20 012

	30 No low level cloud
	31 Cumulus humilis, or Cumulus fractus (not of bad weather), or both
	32 Cumulus mediocris or congestus, with or without Cumulus humilis
	   or fractus or Stratocumulus, all bases at the same level
	33 Cumulonimbus calvus, with or without Cumulus, Stratocumulus
	   or Stratus
	34 Stratocumulus cumulogenitus
	35 Stratocumulus other than stratocumulus cumulogenitus
	36 Stratus nebulosis or Stratus fractus (not of bad weather), or both
	37 Stratus fractus or Cumulus fractus of bad weather or both (pannus)
	38 Cumulus and Stratocumulus other than stratocumulus cumulogenitus,
	   with bases at different levels
	39 Cumulonimbus capillatus with or without Cumulonimbus calvus
	   Cumulus, Stratocumulus, Stratus or pannus

#### Mid_cld_code:
	(This is a subset of a larger table, not all values of which are used)
	wmo international BUFR code table 0 20 012, CREX code table B 20 012

	20 No middle level cloud
	21 Altostratus translucidus
	22 Altostratus opacus or Nimbostratus
	23 Altocumulus translucidus at a single level
	24 Patches (often lenticular) of Altocumulus translucidus, continually
	   changing and at one or more levels
	25 Altocumulus translucidus in bands, or one or more layers of
	   Altocumulus translucidus or opacus, progressively invading the
	   sky
	26 Altocumulus cumulogenitus or cumulonimbogenitus
	27 Altocumulus translucidus or opacus in two or more layers, or
	   Altocumulus opacus in a single layer, not progressively invading
	   the sky, or Altocumulus with Altostratus or Nimbostratus
	28 Altocumulus castellanus or floccus
	29 Altocumulus of a chaotic sky, usually at several levels

#### Hi_cld_code:
	(This is a subset of a larger table, not all values of which are used)
	wmo international BUFR code table 0 20 012, CREX code table B 20 012

	10 No high level cloud
	11 Cirrus fibratus, sometimes unicus, not progressively invading
	   the sky
	12 Cirrus spissatus in patches or entangled sheaves, which usually
	   do not increase
	13 Cirrus spissatus cumulonimbogenitus
	14 Cirrus unicus or fibratus or both, progressively invading the sky
	15 Cirrus (often in bands) and Cirrostratus or Cirrostratus alone,
	   progressively invading the sky, but continuous cloud less than
	   45 degrees above the horizon.
	16 Cirrus (often in bands) and Cirrostratus or Cirrostratus alone,
	   progressively invading the sky, but continuous cloud more than
	   45 degrees above the horizon without covering the entire sky
	17 Cirrostratus covering the entire sky
	18 Cirrostratus not covering the entire sky and not progressively
	   invading it
	19 Cirrocumulus alone or Cirrocumulus predominant
	
## Appendix 2 - Output from get_precis_forecast()

The function, `get_precis_forecast()`, will return a data frame of the 7 day
short forecast with the following fields:

<table>
<tr><th>Field Name</th><th>Description</th></tr>
<tr><td>index</td><td>Forecast index number, 0 = current day ... 7 day</td></tr>
<tr><td>product_id</td><td>BOM Product ID from which the data are derived</td>
</tr>
<tr><td>state</td><td>State name (postal code abbreviation)</td></tr>
<tr><td>town</td><td>Town name for forecast location</td></tr>
<tr><td>aac</td><td>AMOC Area Code, _e.g._, WA_MW008, a unique identifier for
each location</td></tr>
<tr><td>lat</td><td>Latitude of named location (decimal degrees)</td></tr>
<tr><td>lon</td><td>Longitude of named location (decimal degrees)</td></tr>
<tr><td>elev</td><td>Elevation of named location (metres)</td></tr>
<tr><td>start_time_local</td><td>Start of forecast date and time in local
TZ</td></tr>
<tr><td>end_time_local</td><td>End of forecast date and time in local
TZ</td></tr>
<tr><td>UTC_offset</td><td> Hours offset from difference in hours and minutes
from Coordinated Universal Time (UTC) for `start_time_local` and
`end_time_local`</td></tr>
<tr><td>start_time_utc</td><td>Start of forecast date and time in UTC</td></tr>
<tr><td>end_time_utc</td><td>End of forecast date and time in UTC</td></tr>
<tr><td>maximum_temperature</td><td>Maximum forecast temperature (degrees
Celsius)</td></tr>
<tr><td>minimum_temperature</td><td>Minimum forecast temperature (degrees
Celsius)</td></tr>
<tr><td>lower_precipitation_limit</td><td>Lower forecast precipitation limit
(millimetres)</td></tr>
<tr><td>upper_precipitation_limit</td><td>Upper forecast precipitation limit
(millimetres)</td></tr>
<tr><td>precis</td><td>Précis forecast (a short summary, less than 30
characters)</td></tr>
<tr><td>probability_of_precipitation</td><td>Probability of precipitation
(percent)</td></tr>
</table>

## Appendix 3 - Output from get_ag_bulletin()

The function, `get_ag_bulletin()`, will return a data frame of the agriculture
bulletin with the following fields:

<table>
<tr><th>Field Name</th><th>Description</th></tr>
<tr><td>product_id</td><td>BOM Product ID from which the data are derived</td>
</tr>
<tr><td>state</td><td>State name (postal code abbreviation)</td></tr>
<tr><td>dist</td><td>BOM rainfall district</td></tr>
<tr><td>name</td><td>Full station name (some stations have been retired so
"station" will be same, this is the full designation</td></tr>
<tr><td>wmo</td><td>World Meteorological Organization number (unique ID used
worldwide)</td></tr>
<tr><td>site</td><td>Unique BOM identifier for each station</td></tr>
<tr><td>station</td><td>Station name</td></tr>
<tr><td>obs-time-local</td><td>Observation time</td></tr>
<tr><td>obs-time-utc</td><td>Observation time (time in UTC)</td></tr>
<tr><td>time-zone</td><td>Time zone for observation</td></tr>
<tr><td>lat</td><td>Latitude (decimal degrees)</td></tr>
<tr><td>lon</td><td>Longitude (decimal degrees)</td></tr>
<tr><td>elev_m</td><td>Station elevation (metres)</td></tr>
<tr><td>bar_ht</td><td>Bar height (metres)</td></tr>
<tr><td>station</td><td>BOM station name</td></tr>
<tr><td>start</td><td>Year data collection starts</td></tr>
<tr><td>end</td><td>Year data collection ends (will always be current)</td></tr>
<tr><td>r</td><td>Rain to 9am (millimetres). <em>Trace will be reported as
0.01</em></td></tr>
<tr><td>tn</td><td>Minimum temperature (degrees Celsius)</td></tr>
<tr><td>tx</td><td>Maximum temperature (degrees Celsius)</td></tr>
<tr><td>twd</td><td>Wet bulb depression (degrees Celsius)</td></tr>
<tr><td>ev</td><td>Evaporation (millimetres)</td></tr>
<tr><td>tg</td><td>Terrestrial minimum temperature (degrees Celsius)</td></tr>
<tr><td>sn</td><td>Sunshine (hours)</td></tr>
<tr><td>solr</td><td>Solar Radiation MJ/sq m</td></tr>
<tr><td>t5</td><td>5cm soil temperature (degrees Celsius)</td></tr>
<tr><td>t10</td><td>10cm soil temperature (degrees Celsius)</td></tr>
<tr><td>t20</td><td>20cm soil temperature (degrees Celsius)</td></tr>
<tr><td>t50</td><td>50cm soil temperature (degrees Celsius)</td></tr>
<tr><td>t1m</td><td>1m soil temperature (degrees Celsius)</td></tr>
<tr><td>wr</td><td>Wind run (kilometres)</td></tr>
</table>

## Appendix 4 - Output from get_weather_bulletin()

The function `get_weather_bulletin()` returns a data frame of weather
observations for 0900 or 1500 for a nominated state. Observations
differ between states, but contain some or all of the following fields. All
units are metric (temperatures in Celsius; wind speeds in kilometres per hour;
rainfall amounts in millimetres; pressure in hectoPascals). "AWS" in a station
name denotes observations from an Automatic Weather Station.


<table>
<tr><th>Field Name</th><th>Description</th></tr>
<tr><td>stations</td><td>Name of observing station</td></tr>
<tr><td>cld8ths</td><td>Octas (eights) of cloud (0-8); `NA` indicates sky obscured</td></tr>
<tr><td>wind_dir</td><td>Direction from which wind blows (16 compass directions,
measured at height of 10m)</td></tr>
<tr><td>wind_speed_kmh</td><td</td></tr>
<tr><td>temp / temp_c_dry/_terr</td><td>Ambient dry air temperature measured at height of 1.2 metres</td></tr>
<tr><td>temp_c_dew</td><td>Dew-point temperature measured at height of 1.2 metres</td></tr>
<tr><td>temp_c_max</td><td>Maximum temperature for last 24 hours (0900 bulletin) or 6 hours (1500 bulletin).</td></tr>
<tr><td>temp_c_min</td><td>Minimum temperature for last 24 hours (0900 bulletin only)</td></tr>
<tr><td>temp_c_gr</td><td>Wet bulb temperature measured at height of 1.2 metres</td></tr>
<tr><td>rhpercent</td><td>Relative humidity</td></tr>
<tr><td>barhpa / mslpresshpa</td><td>Barometric pressure</td></tr>
<tr><td>rain_mm</td><td>Total rainfall since previous bulletin (`NA` denotes amount less than 1mm)</td></tr>
<tr><td>days</td><td>If present, denotes number of days since previous bulletin</td></tr>
<tr><td>weather</td><td>Description of current weather</td></tr>
<tr><td>seastate (QLD only)</td><td>See below for description</td></tr>
</table><br>


Seastate is described by a text string formed from the three components of (sea
state, swell, direction). Sea state is denoted "C" (Calm), "SM" (Smooth), "SL"
(Slight), "M" (Moderate), "R" (Rough), "VR" (Very Rough), "H" (High), "VH" (Very
High), or "PH" (Phenomenal). Swell is denoted "LS" (Low Short), "LA" (Low
Average), "LL" (Low Long), "MS" (Moderate Short), "MA" (Mod Average), "ML" (Mod
Long), "HS" (Heavy Short), "HA" (heavy Average), "HL" (Heavy Long), or "C"
(Confused). Direction denotes direction from which the swell is coming.

Names of rainfall and temperature variables for some states include prefixes or
suffixes defining the time period over which observations apply (for example,
"temp_c_6hmax" for maximum temperature between 0980 and 1500, or "temp_c_9ammin"
for minimum temperature observed at 9am yet included in 1500 bulletin).


## Appendix 5 - Output from get_coastal_forecast()

The output of `get_coastal_forecast()` will return a data frame with coastal waters forecast values of each area within the given state with the following fields:  

<table>
<tr><th>Field Name</th><th>Description</th></tr>
<tr><td>index</td><td>Forecast index number.  0 = current day </td></tr>
<tr><td>product_id</td><td>BOM Product ID from which the data are derived</td></tr>
<tr><td>type</td><td>Forecast Region type e.g. Coastal</td></tr>
<tr><td>state_code</td><td>State name (postal code abbreviation)</td></tr>
<tr><td>dist_name</td><td>Name of forecast district</td></tr>
<tr><td>pt_1_name</td><td>Start of forecast district</td></tr>
<tr><td>pt_2_name</td><td>End of forecast district</td></tr>
<tr><td>aac</td><td>AMOC Area Code, _e.g._, WA_MW008, a unique identifier for each location</td></tr>
<tr><td>start_time_local</td><td>Start of forecast date and time in local TZ</td></tr>
<tr><td>end_time_local</td><td>End of forecast date and time in local TZ</td></tr>
<tr><td>UTC_offset</td><td>Hours offset from difference in hours and minutes from Coordinated Universal Time (UTC) for `start_time_local` and `end_time_local`</td></tr>
<tr><td>start_time_utc</td><td>Start of forecast date and time in UTC</td></tr>
<tr><td>end_time_utc</td><td>End of forecast date and time in UTC</td></tr>
<tr><td>forecast_seas</td><td>Forecast sea conditions</td></tr>
<tr><td>forecast_weather</td><td>Forecast weather summary</td></tr>
<tr><td>forecast_winds</td><td>Forecast winds summary</td></tr>
<tr><td>forecast_swell1</td><td>Forecast primary swell summary</td></tr>
<tr><td>forecast_swell2</td><td>Forecast seondary swell summary (not always provided)</td></tr>  
<tr><td>forecast_caution</td><td>Forecast caution issued (not always provided)</td></tr>
<tr><td>marine_forecast</td><td>Additional marine forecast warning information (not always provided)</td></tr>
</table><br>

## Appendix 6 - Map of station locations


```r
if (requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("ggthemes", quietly = TRUE) &&
    requireNamespace("maps", quietly = TRUE) &&
    requireNamespace("mapproj", quietly = TRUE) &&
    requireNamespace("gridExtra", quietly = TRUE) &&
    requireNamespace("grid", quietly = TRUE)) {
  library(ggplot2)
  library(mapproj)
  library(ggthemes)
  library(maps)
  library(data.table)
  library(grid)
  library(gridExtra)
  load(system.file("extdata", "stations_site_list.rda", package = "bomrang"))
  setDT(stations_site_list)
  
  Aust_stations <- 
    stations_site_list[(!(state %in% c("ANT", "null"))) & !grepl("VANUATU|HONIARA", name)]
  
  Aust_map <- map_data("world", region = "Australia")
  
  BOM_stations <- ggplot(Aust_stations, aes(x = lon, y = lat)) + 
    geom_polygon(data = Aust_map, aes(x = long, y = lat, group = group), 
                 color = grey(0.7),
                 fill = NA) +
    geom_point(color = "red",
               size = 0.05) +
    coord_map(ylim = c(-45, -5),
              xlim = c(96, 167)) +
    theme_map() + 
    labs(title = "BOM Station Locations",
         subtitle = "Australia, outlying islands and buoys (excl. Antarctic stations)",
         caption = "Data: Australia Bureau of Meteorology (BOM)\n
         and NaturalEarthdata, http://naturalearthdata.com")
  
  # Using the gridExtra and grid packages add a neatline to the map
  grid.arrange(BOM_stations, ncol = 1)
  grid.rect(width = 0.98, 
            height = 0.98, 
            gp = grid::gpar(lwd = 0.25, 
                            col = "black",
                            fill = NA))
}
```

<img src="station-locations-map-1.png" title="plot of chunk station-locations-map" alt="plot of chunk station-locations-map" style="display: block; margin: auto;" />

## Appendix 7 - Maps of historical data availability

Note that these maps are current as of `Sys.Date()` and may have changed.


```r
library(magrittr)

ncc <- bomrang:::.get_ncc()

ncc <- 
  ncc %>%
  dplyr::mutate(ncc_obs_code = replace(ncc_obs_code,
                                       ncc_obs_code == 136,
                                       "rain")) %>% 
  dplyr::mutate(ncc_obs_code = replace(ncc_obs_code,
                                       ncc_obs_code == 123,
                                       "tmin")) %>%
  dplyr::mutate(ncc_obs_code = replace(ncc_obs_code,
                                       ncc_obs_code == 122,
                                       "tmax")) %>% 
  dplyr::mutate(ncc_obs_code = replace(ncc_obs_code,
                                       ncc_obs_code == 193,
                                       "solar"))
```

### Completeness of historical data for stations


```r
perc_complete <- ggplot(ncc, aes(x = lon, y = lat)) + 
  geom_polygon(data = Aust_map, aes(x = long, y = lat, group = group), 
               color = grey(0.7),
               fill = NA) +
  geom_point(aes(color = percent),
             alpha = 0.5,
             size = 0.05) +
  scale_colour_viridis_c(direction = -1,
                         option = "A") +
  coord_map(ylim = c(-45, -5),
            xlim = c(96, 167)) +
  theme_map() +
  facet_wrap(. ~ ncc_obs_code) +
  labs(title = "BOM Historical Station Data Completeness",
       subtitle = "Australia, outlying islands and buoys (excl. Antarctic stations)",
       caption = "Data: Australia Bureau of Meteorology (BOM)\n
     and NaturalEarthdata, http://naturalearthdata.com")

# Using the gridExtra and grid packages add a neatline to the map
grid.arrange(perc_complete, ncol = 1)
grid.rect(width = 0.98, 
          height = 0.98, 
          gp = grid::gpar(lwd = 0.25, 
                          col = "black",
                          fill = NA))
```

<img src="completeness_map-1.png" title="plot of chunk completeness_map" alt="plot of chunk completeness_map" style="display: block; margin: auto;" />

### Historical data years available for stations


```r
years_available <- ggplot(ncc, aes(x = lon, y = lat)) + 
  geom_polygon(data = Aust_map, aes(x = long, y = lat, group = group), 
               color = grey(0.7),
               fill = NA) +
  geom_point(aes(color = years),
             alpha = 0.5,
             size = 0.05) +
  scale_colour_viridis_c(direction = -1,
                         option = "A") +
  coord_map(ylim = c(-45, -5),
            xlim = c(96, 167)) +
  theme_map() +
  facet_wrap(. ~ ncc_obs_code) +
  labs(title = "BOM Historical Station Data Years Available",
       subtitle = "Australia, outlying islands and buoys (excl. Antarctic stations)",
       caption = "Data: Australia Bureau of Meteorology (BOM)\n
     and NaturalEarthdata, http://naturalearthdata.com")

# Using the gridExtra and grid packages add a neatline to the map
grid.arrange(years_available, ncol = 1)
grid.rect(width = 0.98, 
          height = 0.98, 
          gp = grid::gpar(lwd = 0.25, 
                          col = "black",
                          fill = NA))
```

<img src="years_available-1.png" title="plot of chunk years_available" alt="plot of chunk years_available" style="display: block; margin: auto;" />
