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=XXXXXXXXwhich 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