---
title: "datagovsgR"
output: 
  rmarkdown::html_vignette:

vignette: >
  %\VignetteIndexEntry{datagovsgR-vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(datagovsgR)
library(dplyr)
```

## Description of `datagovsgR`

The goal of this package is to create API wrappers for the APIs found on the GovTech. GovTech is the Singapore department focused on data and technology, which currently has a list of API tools for developers to leverage on, found on their website. These developer API tools are publicly accessible, containing tools such as realtime weather readings, carpark availability and locations of available taxis. The API wrappers are listed below.

<br>

## Carpark Availability

This functions calls upon the carpark availability API from data.gov.sg and processes the returning page, returning a dataframe containing the carpark id, type, last update, total lots, and current lots. A date-time has to be specified, otherwise the default is set to return the current date-time.

```{r}
carpark_availability(date = "2019-06-05T10:10:10") %>% head()
```

<br>

## PM 2.5

This functions calls upon the PM2.5 API from data.gov.sg and returns a data frame of the different measures of PM2.5 across 5 different areas in Singapore. This data provided by the API is updated hourly from NEA. There are 2 functions, the `pm25` which returns the data for a given date-time, and `pm25_summary` which returns the data summary for a given date.

```{r}
pm25(date_time = "2018-01-04T09:16:17")
```

```{r}
pm25_summary(date = "2018-01-04") %>% head()
```

<br>

## PoullutantStandardIndex (PSI)

This functions calls upon the PSI API from data.gov.sg and returns a data frame of the different measures of the PSI across 5 different areas in Singapores and the overall measure for the given data-time. This data provided by the API is updated hourly.  There are 2 functions, the `psi` which returns the data for a given date-time, and `psi_summary` which returns the data summary for a given date.

```{r}
psi(date = "2019-11-08T17:30:00") %>% head()
```

```{r}
psi_summary(date = "2018-01-04") %>% head()
```

<br>

## Taxi Availability

This functions calls upon the taxi availability API from data.gov.sg and returns a data frame of the locations of all availible taxis in longitude and latitude values. A date-time has to be specified, otherwise the default is set to return the current date-time.

```{r}
taxi_availability(date = "2019-08-07T09:30:00") %>% head()
```

<br>

## Weather Forecast

This functions calls upon the weather forecast API from data.gov.sg and returns a data frame containing different metrics of the forecast. 2-hour, 24-hour and 4-day forecasts are availible. It then returns a dataframe containing the forecast which is dependent on the date-time and parameter of forecast. This data provided by the API is updated half-hourly. A date-time has to be specified, otherwise the default is set to return the current date-time.

A 2-hour forecast returns the general forecast for each area in Singapore for the next 2-hours; a 24-hour forecast returns the general forecast for the next day along with the weather metrics; a 4-day forecast returns the general forecast for each of the next four days.

```{r}
weather_forecast(date = "2019-11-08T17:30:00", forecast = "2-hour") %>% head()
```

```{r}
weather_forecast(date = "2018-01-04T09:16:17", forecast = "4-day")
```

<br>

## Weather Reading

This functions calls upon the weather reading API from data.gov.sg and returns a list containing the air temperature, rainfall, relative humidity, wind direction and speed across Singapore. Data is updated every 5 minutes for the rainfall API, and every half minute for the other 4 API from NEA. A date-time has to be specified, otherwise the default is set to return the current date-time. Do note that this API takes slighlty longer than the other APIs in the package as 5 APIs are wrapped within this function.

The `simplify` parameter is `FALSE` on default, returning a list of each of the 5 metrics. Otherwise, `simplify = TRUE` would return a data frame where all 5 metrics are joined according to weather stations, but return several NAs, as most weather stations collect rainfall data only.

```{r}
weather_reading(date = "2019-11-08T17:30:00")
```

***









