README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# astropic

The goal of `astropic` is to connect R to the NASA APOD API. The APOD API supports one image at a time. In order to suplly more than that, this package also includes creating time ranges (of less than 1000 days ata time) and some historical data in tibble format.

Thanks to Michael W. Kearney, author of [rtweet](http://rtweet.info), for having a robust package based on connecting to an API. I didn't know much about APIs when I started this project and looking at his source code helped a ton! 

## Installation

You can install the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("eringrand/astropic")
```
## API Key
To start, you'll need a NASA API key. If you do not have one, you can get one [here](https://api.nasa.gov/index.html#apply-for-an-api-key). Once you put in your information, a key will be emailed to you.

Save this to your enviorment as `NASA_KEY`. e.g `Sys.setenv(NASA_KEY = "YOURKEYHERE")`.


## Query
The query paramters are described on the [APOD API Github page](https://github.com/nasa/apod-api) as such...

- `date` A string in YYYY-MM-DD format indicating the date of the APOD image (example: 2014-11-03).  Defaults to today's date.  Must be after 1995-06-16, the first day an APOD picture was posted.  There are no images for tomorrow available through this API.
- `hd` A boolean parameter indicating whether or not high-resolution images should be returned. This is present for legacy purposes, it is always ignored by the service and high-resolution urls are returned regardless.
- `count` A positive integer, no greater than 100. If this is specified then `count` randomly chosen images will be returned in a JSON array. Cannot be used in conjunction with `date` or `start_date` and `end_date`.
- `start_date` A string in YYYY-MM-DD format indicating the start of a date range. All images in the range from `start_date` to `end_date` will be returned in a JSON array. Cannot be used with `date`.
- `end_date` A string in YYYY-MM-DD format indicating that end of a date range. If `start_date` is specified without an `end_date` then `end_date` defaults to the current date.


## Example

This is a basic example to retrive APOD data. 

### Basic Example
```{r example1, warning=FALSE}
library(astropic)
get_apod() # no inputs will get today's image
```

### Providing a date range

You can also supply a start and end date to get a range of image results back.
```{r}
get_apod(query  = list(start_date = "2018-04-01", end_date = "2018-04-03"))
```
### Count - `n` random images
```{r}
get_apod(query = list(count = 5))
```


### Magic

With a little `magick` you can also save the APOD image to your computer for use later. 
This is a demostration of a picture in APOD I helped to create!
```{r m31, message=FALSE, warning=FALSE}
library(magick)
library(gmp)
library(stringr)
library(dplyr)

save_image <- function(url){
  image <- try(image_read(url), silent = FALSE)
  image_name <- stringr::str_extract(m31$hdurl, "([^\\/]+$)")
  image_loc <- here::here("man/figures/README", image_name)
  if(class(image)[1] != "try-error"){
    image %>%
    image_write(image_loc)
  }
  return(image)
}

m31 <- get_apod(query = list(date = "2009-09-17"))  # only providing a start date will give the image just for that day
pull(m31, explanation)
save_image(m31$hdurl)
```

## Contact
Come find me on twitter @[astroeringand](https://twitter.com/astroeringrand)

## Code of Conduct
Please note that this project is released with a [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md).
By participating in this project you agree to abide by its terms.