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