---
title: "eBird Status and Trends Data Products API"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteEncoding{UTF-8}
  %\VignetteIndexEntry{eBird Status and Trends Data Products API}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

<style type="text/css">
.table {
    width: 50%;
}
</style>

```{r setup, include=FALSE}
knitr::opts_chunk$set(warning = FALSE, 
                      message = FALSE,
                      collapse = TRUE,
                      comment = "#>",
                      out.width = "100%",
                      fig.height = 4, 
                      fig.width = 7, 
                      fig.align = "center")
```

The eBird Status and Trends Data Products API is a programmatic interface for downloading eBird Status and Trends Data Products. The `ebirdst` R package provides a convenient interface to this API for R users; however, data users can interact with this API directly. For example, some data users may wish to use the API to access data using bash or Python scripts. This vignette outlines how the API is used. All API requests require an access key, which can be obtained by visiting https://ebird.org/st/request.

## API Endpoints

The eBird Status and Trends Data Products API has two endpoints: one to list available files for a given species and one to download a single file.

### List 

To list available files for a given species use:

```
https://st-download.ebird.org/v1/list-obj/2022/{species_code}?key={access_key}
```

where `species_code` is the 6-letter eBird species code and `access_key` is the user specific access key. The `2022` in the URL refers to the prediction year; these are predictions for 2022. The result will be a list of file objects in JSON format. For example, assuming your access key is `XXXXXXXX`, to list available files for Wood Thrush (species code `woothr`) use:

```
https://st-download.ebird.org/v1/list-obj/2022/woothr?key=XXXXXXXX
```

which will return:

```
["2022/woothr/config.json","2022/woothr/pis/pi_rangewide-ranks.csv","2022/woothr/pis/woothr_n-folds-modeled_27km_2022.tif","2022/woothr/pis/woothr_pi_count_astwbd-c2-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_astwbd-c3-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_eastness-90m-median_27km_2022.tif","2022/woothr/pis/woothr_pi_count_elevation-30m-median_27km_2022.tif","2022/woothr/pis/woothr_pi_count_evi-median_27km_2022.tif","2022/woothr/pis/woothr_pi_count_gsw-c2-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_gsw-c3-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c11-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c14-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c15-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c21-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c22-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c31-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c32-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs2-c25-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs2-c36-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs3-c27-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_mcd12q1-lccs3-c50-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_count_northness-90m-median_27km_2022.tif","2022/woothr/pis/woothr_pi_count_ntl-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_count_road-density-c1_27km_2022.tif","2022/woothr/pis/woothr_pi_count_road-density-c2_27km_2022.tif","2022/woothr/pis/woothr_pi_count_road-density-c3_27km_2022.tif","2022/woothr/pis/woothr_pi_count_road-density-c4_27km_2022.tif","2022/woothr/pis/woothr_pi_count_road-density-c5_27km_2022.tif","2022/woothr/pis/woothr_pi_count_shoreline-chlorophyll-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_count_shoreline-sinuosity-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_count_shoreline-slope-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_count_shoreline-tidal-range-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_count_shoreline-turbidity-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_astwbd-c2-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_astwbd-c3-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_eastness-90m-median_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_elevation-30m-median_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_evi-median_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_gsw-c2-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_gsw-c3-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c11-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c14-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c15-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c21-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c22-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c31-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c32-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs2-c25-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs2-c36-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs3-c27-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs3-c50-pland_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_northness-90m-median_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_ntl-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_road-density-c1_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_road-density-c2_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_road-density-c3_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_road-density-c4_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_road-density-c5_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_shoreline-chlorophyll-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_shoreline-sinuosity-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_shoreline-slope-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_shoreline-tidal-range-mean_27km_2022.tif","2022/woothr/pis/woothr_pi_occurrence_shoreline-turbidity-mean_27km_2022.tif","2022/woothr/ppms/woothr_ppm_abd-poisson-dev_27km_2022.tif","2022/woothr/ppms/woothr_ppm_abd-spearman_27km_2022.tif","2022/woothr/ppms/woothr_ppm_binary-f1_27km_2022.tif","2022/woothr/ppms/woothr_ppm_binary-pr-auc_27km_2022.tif","2022/woothr/ppms/woothr_ppm_count-spearman_27km_2022.tif","2022/woothr/ppms/woothr_ppm_log-abd-pearson_27km_2022.tif","2022/woothr/ppms/woothr_ppm_log-count-pearson_27km_2022.tif","2022/woothr/ppms/woothr_ppm_occ-bernoulli-dev_27km_2022.tif","2022/woothr/ranges/woothr_range_raw_27km_2022.gpkg","2022/woothr/ranges/woothr_range_raw_9km_2022.gpkg","2022/woothr/ranges/woothr_range_smooth_27km_2022.gpkg","2022/woothr/ranges/woothr_range_smooth_9km_2022.gpkg","2022/woothr/regional_stats.csv","2022/woothr/seasonal/band-seasons.csv","2022/woothr/seasonal/woothr_abundance_full-year_max_27km_2022.tif","2022/woothr/seasonal/woothr_abundance_full-year_max_3km_2022.tif","2022/woothr/seasonal/woothr_abundance_full-year_max_9km_2022.tif","2022/woothr/seasonal/woothr_abundance_full-year_mean_27km_2022.tif","2022/woothr/seasonal/woothr_abundance_full-year_mean_3km_2022.tif","2022/woothr/seasonal/woothr_abundance_full-year_mean_9km_2022.tif","2022/woothr/seasonal/woothr_abundance_seasonal_max_27km_2022.tif","2022/woothr/seasonal/woothr_abundance_seasonal_max_3km_2022.tif","2022/woothr/seasonal/woothr_abundance_seasonal_max_9km_2022.tif","2022/woothr/seasonal/woothr_abundance_seasonal_mean_27km_2022.tif","2022/woothr/seasonal/woothr_abundance_seasonal_mean_3km_2022.tif","2022/woothr/seasonal/woothr_abundance_seasonal_mean_9km_2022.tif","2022/woothr/seasonal/woothr_count_full-year_max_27km_2022.tif","2022/woothr/seasonal/woothr_count_full-year_max_3km_2022.tif","2022/woothr/seasonal/woothr_count_full-year_max_9km_2022.tif","2022/woothr/seasonal/woothr_count_full-year_mean_27km_2022.tif","2022/woothr/seasonal/woothr_count_full-year_mean_3km_2022.tif","2022/woothr/seasonal/woothr_count_full-year_mean_9km_2022.tif","2022/woothr/seasonal/woothr_count_seasonal_max_27km_2022.tif","2022/woothr/seasonal/woothr_count_seasonal_max_3km_2022.tif","2022/woothr/seasonal/woothr_count_seasonal_max_9km_2022.tif","2022/woothr/seasonal/woothr_count_seasonal_mean_27km_2022.tif","2022/woothr/seasonal/woothr_count_seasonal_mean_3km_2022.tif","2022/woothr/seasonal/woothr_count_seasonal_mean_9km_2022.tif","2022/woothr/seasonal/woothr_occurrence_full-year_max_27km_2022.tif","2022/woothr/seasonal/woothr_occurrence_full-year_max_3km_2022.tif","2022/woothr/seasonal/woothr_occurrence_full-year_max_9km_2022.tif","2022/woothr/seasonal/woothr_occurrence_full-year_mean_27km_2022.tif","2022/woothr/seasonal/woothr_occurrence_full-year_mean_3km_2022.tif","2022/woothr/seasonal/woothr_occurrence_full-year_mean_9km_2022.tif","2022/woothr/seasonal/woothr_occurrence_seasonal_max_27km_2022.tif","2022/woothr/seasonal/woothr_occurrence_seasonal_max_3km_2022.tif","2022/woothr/seasonal/woothr_occurrence_seasonal_max_9km_2022.tif","2022/woothr/seasonal/woothr_occurrence_seasonal_mean_27km_2022.tif","2022/woothr/seasonal/woothr_occurrence_seasonal_mean_3km_2022.tif","2022/woothr/seasonal/woothr_occurrence_seasonal_mean_9km_2022.tif","2022/woothr/seasonal/woothr_proportion-population_seasonal_mean_27km_2022.tif","2022/woothr/seasonal/woothr_proportion-population_seasonal_mean_3km_2022.tif","2022/woothr/seasonal/woothr_proportion-population_seasonal_mean_9km_2022.tif","2022/woothr/trends/woothr_breeding_ebird-trends_2022.parquet","2022/woothr/trends/woothr_breeding_ebird-trends_folds_2022.parquet","2022/woothr/trends/woothr_breeding_ebird-trends_model-summary.csv","2022/woothr/web_download/seasonal/woothr_abundance_seasonal_breeding_max_2022.tif","2022/woothr/web_download/seasonal/woothr_abundance_seasonal_breeding_mean_2022.tif","2022/woothr/web_download/seasonal/woothr_abundance_seasonal_full-year_max_2022.tif","2022/woothr/web_download/seasonal/woothr_abundance_seasonal_full-year_mean_2022.tif","2022/woothr/web_download/seasonal/woothr_abundance_seasonal_nonbreeding_max_2022.tif","2022/woothr/web_download/seasonal/woothr_abundance_seasonal_nonbreeding_mean_2022.tif","2022/woothr/web_download/seasonal/woothr_abundance_seasonal_postbreeding-migration_max_2022.tif","2022/woothr/web_download/seasonal/woothr_abundance_seasonal_postbreeding-migration_mean_2022.tif","2022/woothr/web_download/seasonal/woothr_abundance_seasonal_prebreeding-migration_max_2022.tif","2022/woothr/web_download/seasonal/woothr_abundance_seasonal_prebreeding-migration_mean_2022.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-01-04.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-01-11.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-01-18.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-01-25.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-02-01.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-02-08.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-02-15.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-02-22.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-03-01.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-03-08.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-03-15.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-03-22.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-03-29.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-04-05.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-04-12.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-04-19.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-04-26.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-05-03.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-05-10.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-05-17.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-05-24.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-05-31.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-06-07.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-06-14.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-06-21.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-06-28.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-07-05.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-07-12.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-07-19.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-07-26.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-08-02.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-08-09.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-08-16.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-08-23.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-08-30.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-09-06.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-09-13.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-09-20.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-09-27.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-10-04.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-10-11.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-10-18.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-10-25.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-11-01.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-11-08.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-11-15.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-11-22.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-11-29.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-12-06.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-12-13.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-12-20.tif","2022/woothr/web_download/weekly/woothr_abundance_median_2022-12-27.tif","2022/woothr/web_download/woothr_ebird-trends_2022.zip","2022/woothr/web_download/woothr_ebird-trends_regional_2022.zip","2022/woothr/web_download/woothr_range_2022.zip","2022/woothr/web_download/woothr_regional_2022.zip","2022/woothr/weekly/band-dates.csv","2022/woothr/weekly/woothr_abundance_lower_27km_2022.tif","2022/woothr/weekly/woothr_abundance_lower_3km_2022.tif","2022/woothr/weekly/woothr_abundance_lower_9km_2022.tif","2022/woothr/weekly/woothr_abundance_median_27km_2022.tif","2022/woothr/weekly/woothr_abundance_median_3km_2022.tif","2022/woothr/weekly/woothr_abundance_median_9km_2022.tif","2022/woothr/weekly/woothr_abundance_upper_27km_2022.tif","2022/woothr/weekly/woothr_abundance_upper_3km_2022.tif","2022/woothr/weekly/woothr_abundance_upper_9km_2022.tif","2022/woothr/weekly/woothr_centroids.csv","2022/woothr/weekly/woothr_count_median_27km_2022.tif","2022/woothr/weekly/woothr_count_median_3km_2022.tif","2022/woothr/weekly/woothr_count_median_9km_2022.tif","2022/woothr/weekly/woothr_occurrence_median_27km_2022.tif","2022/woothr/weekly/woothr_occurrence_median_3km_2022.tif","2022/woothr/weekly/woothr_occurrence_median_9km_2022.tif","2022/woothr/weekly/woothr_proportion-population_median_27km_2022.tif","2022/woothr/weekly/woothr_proportion-population_median_3km_2022.tif","2022/woothr/weekly/woothr_proportion-population_median_9km_2022.tif"]
```

### Download


To download a single file use:

```
https://st-download.ebird.org/v1/fetch?objKey={object_path}&key={access_key}
```

where `object_path` is the path to a given file object in the same format as returned by the list files API and `access_key` is the user specific access key. For example, assuming your access key is `XXXXXXXX`, if you want to download the 3 km seasonal mean relative abundance, first find the corresponding file object path in the JSON returned by the list files API: `2022/woothr/seasonal/woothr_abundance_seasonal_mean_3km_2022.tif`. Then provide that object path to the download API:

```
https://st-download.ebird.org/v1/fetch?objKey=2022/woothr/seasonal/woothr_abundance_seasonal_mean_3km_2022.tif&key=XXXXXXXX
```
