---
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/{version_year}/{species_code}?key={access_key}
```

where `species_code` is the 6-letter eBird species code, `access_key` is the user specific access key, and `{version_year}` is the version (`2023` for Status data products and `2023` for Trends data products). The result will be a list of file objects in JSON format. For example, assuming your access key is `XXXXXXXX`, to list available Status data products for Wood Thrush (species code `woothr`) use:

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

which will return:

```
["2023/woothr/config.json","2023/woothr/pis/pi_rangewide.csv","2023/woothr/pis/woothr_end_day_of_year_27km_2023.tif","2023/woothr/pis/woothr_n-folds-modeled_27km_2023.tif","2023/woothr/pis/woothr_pi_count_astwbd-c2-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_astwbd-c3-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_gsw-c2-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c11-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c12-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c14-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c15-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c21-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c22-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c31-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs1-c32-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs2-c25-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs2-c36-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs3-c27-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_count_mcd12q1-lccs3-c50-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_astwbd-c1-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_astwbd-c2-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_astwbd-c3-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_gsw-c2-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c11-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c14-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c15-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c21-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c22-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c31-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs1-c32-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs2-c25-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs2-c36-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs3-c27-pland_27km_2023.tif","2023/woothr/pis/woothr_pi_occurrence_mcd12q1-lccs3-c50-pland_27km_2023.tif","2023/woothr/pis/woothr_start_day_of_year_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-log-pearson_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-log-pearson_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-log-pearson_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-log-pearson_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-mae_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-mae_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-mae_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-mae_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-poisson-dev_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-poisson-dev_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-poisson-dev_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-poisson-dev_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-rmse_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-rmse_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-rmse_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-rmse_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-spearman_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-spearman_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-spearman_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_abd-spearman_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-f1_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-f1_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-f1_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-f1_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-mcc_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-mcc_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-mcc_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-mcc_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-prevalence_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-prevalence_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-prevalence_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_binary-prevalence_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-log-pearson_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-log-pearson_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-log-pearson_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-log-pearson_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-mae_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-mae_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-mae_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-mae_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-poisson-dev_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-poisson-dev_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-poisson-dev_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-poisson-dev_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-rmse_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-rmse_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-rmse_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-rmse_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-spearman_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-spearman_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-spearman_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_count-spearman_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-bernoulli-dev_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-bernoulli-dev_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-bernoulli-dev_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-bernoulli-dev_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-bin-spearman_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-bin-spearman_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-bin-spearman_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-bin-spearman_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-brier_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-brier_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-brier_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-brier_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc-gt-prev_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc-gt-prev_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc-gt-prev_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc-gt-prev_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc-normalized_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc-normalized_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc-normalized_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc-normalized_sd_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc_mean_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc_mean_raw_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc_sd_27km_2023.tif","2023/woothr/ppms/woothr_ppm_occ-pr-auc_sd_raw_27km_2023.tif","2023/woothr/ranges/woothr_range_raw_27km_2023.gpkg","2023/woothr/ranges/woothr_range_raw_9km_2023.gpkg","2023/woothr/ranges/woothr_range_smooth_27km_2023.gpkg","2023/woothr/ranges/woothr_range_smooth_9km_2023.gpkg","2023/woothr/regional_stats.csv","2023/woothr/seasonal/woothr_abundance_full-year_max_27km_2023.tif","2023/woothr/seasonal/woothr_abundance_full-year_max_3km_2023.tif","2023/woothr/seasonal/woothr_abundance_full-year_max_9km_2023.tif","2023/woothr/seasonal/woothr_abundance_full-year_mean_27km_2023.tif","2023/woothr/seasonal/woothr_abundance_full-year_mean_3km_2023.tif","2023/woothr/seasonal/woothr_abundance_full-year_mean_9km_2023.tif","2023/woothr/seasonal/woothr_abundance_seasonal_max_27km_2023.tif","2023/woothr/seasonal/woothr_abundance_seasonal_max_3km_2023.tif","2023/woothr/seasonal/woothr_abundance_seasonal_max_9km_2023.tif","2023/woothr/seasonal/woothr_abundance_seasonal_mean_27km_2023.tif","2023/woothr/seasonal/woothr_abundance_seasonal_mean_3km_2023.tif","2023/woothr/seasonal/woothr_abundance_seasonal_mean_9km_2023.tif","2023/woothr/seasonal/woothr_count_full-year_max_27km_2023.tif","2023/woothr/seasonal/woothr_count_full-year_max_3km_2023.tif","2023/woothr/seasonal/woothr_count_full-year_max_9km_2023.tif","2023/woothr/seasonal/woothr_count_full-year_mean_27km_2023.tif","2023/woothr/seasonal/woothr_count_full-year_mean_3km_2023.tif","2023/woothr/seasonal/woothr_count_full-year_mean_9km_2023.tif","2023/woothr/seasonal/woothr_count_seasonal_max_27km_2023.tif","2023/woothr/seasonal/woothr_count_seasonal_max_3km_2023.tif","2023/woothr/seasonal/woothr_count_seasonal_max_9km_2023.tif","2023/woothr/seasonal/woothr_count_seasonal_mean_27km_2023.tif","2023/woothr/seasonal/woothr_count_seasonal_mean_3km_2023.tif","2023/woothr/seasonal/woothr_count_seasonal_mean_9km_2023.tif","2023/woothr/seasonal/woothr_occurrence_full-year_max_27km_2023.tif","2023/woothr/seasonal/woothr_occurrence_full-year_max_3km_2023.tif","2023/woothr/seasonal/woothr_occurrence_full-year_max_9km_2023.tif","2023/woothr/seasonal/woothr_occurrence_full-year_mean_27km_2023.tif","2023/woothr/seasonal/woothr_occurrence_full-year_mean_3km_2023.tif","2023/woothr/seasonal/woothr_occurrence_full-year_mean_9km_2023.tif","2023/woothr/seasonal/woothr_occurrence_seasonal_max_27km_2023.tif","2023/woothr/seasonal/woothr_occurrence_seasonal_max_3km_2023.tif","2023/woothr/seasonal/woothr_occurrence_seasonal_max_9km_2023.tif","2023/woothr/seasonal/woothr_occurrence_seasonal_mean_27km_2023.tif","2023/woothr/seasonal/woothr_occurrence_seasonal_mean_3km_2023.tif","2023/woothr/seasonal/woothr_occurrence_seasonal_mean_9km_2023.tif","2023/woothr/seasonal/woothr_proportion-population_seasonal_mean_27km_2023.tif","2023/woothr/seasonal/woothr_proportion-population_seasonal_mean_3km_2023.tif","2023/woothr/seasonal/woothr_proportion-population_seasonal_mean_9km_2023.tif","2023/woothr/web_download/seasonal/woothr_abundance_seasonal_breeding_max_2023.tif","2023/woothr/web_download/seasonal/woothr_abundance_seasonal_breeding_mean_2023.tif","2023/woothr/web_download/seasonal/woothr_abundance_seasonal_full-year_max_2023.tif","2023/woothr/web_download/seasonal/woothr_abundance_seasonal_full-year_mean_2023.tif","2023/woothr/web_download/seasonal/woothr_abundance_seasonal_nonbreeding_max_2023.tif","2023/woothr/web_download/seasonal/woothr_abundance_seasonal_nonbreeding_mean_2023.tif","2023/woothr/web_download/seasonal/woothr_abundance_seasonal_postbreeding-migration_max_2023.tif","2023/woothr/web_download/seasonal/woothr_abundance_seasonal_postbreeding-migration_mean_2023.tif","2023/woothr/web_download/seasonal/woothr_abundance_seasonal_prebreeding-migration_max_2023.tif","2023/woothr/web_download/seasonal/woothr_abundance_seasonal_prebreeding-migration_mean_2023.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-01-04.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-01-11.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-01-18.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-01-25.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-02-01.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-02-08.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-02-15.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-02-22.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-03-01.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-03-08.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-03-15.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-03-22.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-03-29.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-04-05.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-04-12.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-04-19.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-04-26.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-05-03.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-05-10.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-05-17.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-05-24.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-05-31.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-06-07.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-06-14.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-06-21.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-06-28.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-07-05.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-07-12.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-07-19.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-07-26.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-08-02.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-08-09.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-08-16.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-08-23.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-08-30.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-09-06.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-09-13.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-09-20.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-09-27.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-10-04.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-10-11.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-10-18.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-10-25.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-11-01.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-11-08.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-11-15.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-11-22.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-11-29.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-12-06.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-12-13.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-12-20.tif","2023/woothr/web_download/weekly/woothr_abundance_median_2023-12-27.tif","2023/woothr/web_download/woothr_abundance_median_2023.zip","2023/woothr/web_download/woothr_range_2023.zip","2023/woothr/web_download/woothr_regional_2023.zip","2023/woothr/weekly/band-dates.csv","2023/woothr/weekly/woothr_abundance_lower_27km_2023.tif","2023/woothr/weekly/woothr_abundance_lower_3km_2023.tif","2023/woothr/weekly/woothr_abundance_lower_9km_2023.tif","2023/woothr/weekly/woothr_abundance_median_27km_2023.tif","2023/woothr/weekly/woothr_abundance_median_3km_2023.tif","2023/woothr/weekly/woothr_abundance_median_9km_2023.tif","2023/woothr/weekly/woothr_abundance_upper_27km_2023.tif","2023/woothr/weekly/woothr_abundance_upper_3km_2023.tif","2023/woothr/weekly/woothr_abundance_upper_9km_2023.tif","2023/woothr/weekly/woothr_centroids.csv","2023/woothr/weekly/woothr_count_median_27km_2023.tif","2023/woothr/weekly/woothr_count_median_3km_2023.tif","2023/woothr/weekly/woothr_count_median_9km_2023.tif","2023/woothr/weekly/woothr_occurrence_median_27km_2023.tif","2023/woothr/weekly/woothr_occurrence_median_3km_2023.tif","2023/woothr/weekly/woothr_occurrence_median_9km_2023.tif","2023/woothr/weekly/woothr_proportion-population_median_27km_2023.tif","2023/woothr/weekly/woothr_proportion-population_median_3km_2023.tif","2023/woothr/weekly/woothr_proportion-population_median_9km_2023.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=2023/woothr/seasonal/woothr_abundance_seasonal_mean_3km_2023.tif&key=XXXXXXXX
```
