Skip to content

WHOI HABhub Data API Documentation

Jump to bottom
Ethan Andrews edited this page Dec 16, 2024 · 1 revision

The WHOI HABHub application data visualizations are based on geospatial data provided by a REST API. This data is also available for public use as long as the WHOI HABHub [https://habhub.whoi.edu] is cited as the data source.

Data Format

All API geospatial data is returned in standard GEOJSON format - https://geojson.org

Data Sources

There are four different HAB data sources that are available from the API.

Cell Concentration and Biovolume Data (Fixed Locations)

This data source provides Cell Concentration data collected from IFCBs at fixed locations. The All Locations endpoint only returns aggregated Max/Mean data for each location. To view the full time-series data for each location, you need to use the Location Detail endpoint to view a specific location by its numeric id property (ex: 1)

All Locations Endpoint: https://habhub-api.whoi.edu/api/v1/ifcb-datasets/

Example request with date filters: https://habhub-api.whoi.edu/api/v1/ifcb-datasets/?start_date=2023-09-01&end_date=2023-09-30

Location Detail Endpoint: [https://habhub-api.whoi.edu/api/v1/ifcb-datasets/[location_id_number]]

Example request with date filters: https://habhub-api.whoi.edu/api/v1/ifcb-datasets/2/?start_date=2023-09-01&end_date=2023-09-30

Available filters:

  • start_date (YYYY-MM-DD format) - start date of the requested date range. Defaults to 1 year before the current date. ex: start_date=2020-12-01
  • end_date (YYYY-MM-DD format) - end date of the requested date range. Defaults to the current date. ex: end_date=2023-12-31
  • seasonal (true/false) - if true, API will return yearly chunks of seasonal data based on the start_date month and the end_date month. For example, a request of start_date=1989-06-01&end_date=2011-08-31&seasonal=true would return only the summer months of June-August for the years from 1989-2011. Defaults to false
  • exclude_month_range (true/false) - Used in conjunction with the seasonal filter. If seasonal filter is true, setting exclude_month_range=true will return yearly chunks of data that exclude the selected start and end months. For example, a request of start_date=1989-06-01&end_date=2011-08-31&seasonal=true&exclude_month_range=true would return all yearly data except for the summer months of June-August for the years from 1989-2011. Defaults to false

Cell Concentrations and Biovolume Data (Spatial Grid)

This data source provides Cell Concentration data collected from IFCBs at all locations (including both fixed and cruise-based datasets) that is then collected and binned into a geospatial grid that covers the HABHub's full geographic range. The All Grid Squares endpoint only returns aggregated Max/Mean data for each grid square. To view the full time-series data for each grid square, you need to use the Grid Square Detail endpoint to view a specific grid by its string geohash id property (ex: drxxk)

All Grid Squares Endpoint: https://habhub-api.whoi.edu/api/v1/ifcb-spatial-grid/

Example request with date filters: https://habhub-api.whoi.edu/api/v1/ifcb-spatial-grid/?start_date=2023-09-01&end_date=2023-09-30&grid_level=0.5

Grid Square Detail Endpoint: [https://habhub-api.whoi.edu/api/v1/ifcb-spatial-grid/[grid_id_string]]

Example request with date filters: https://habhub-api.whoi.edu/api/v1/ifcb-spatial-grid/drxxk/?start_date=2018-09-18&end_date=2023-09-18&seasonal=false&exclude_month_range=false&smoothing_factor=4&grid_level=0.5

Available filters:

  • start_date (YYYY-MM-DD format) - start date of the requested date range. Defaults to 1 year before the current date. ex: start_date=2020-12-01
  • end_date (YYYY-MM-DD format) - end date of the requested date range. Defaults to the current date. ex: end_date=2023-12-31
  • grid_level (decimal format) - changes the size of the geospatial grid. A smaller number means the data is binned into a smaller grid, larger number means larger grid squares. ex: grid_level=0.5
  • seasonal (true/false) - if true, API will return yearly chunks of seasonal data based on the start_date month and the end_date month. For example, a request of start_date=1989-06-01&end_date=2011-08-31&seasonal=true would return only the summer months of June-August for the years from 1989-2011. Defaults to false
  • exclude_month_range (true/false) - Used in conjunction with the seasonal filter. If seasonal filter is true, setting exclude_month_range=true will return yearly chunks of data that exclude the selected start and end months. For example, a request of start_date=1989-06-01&end_date=2011-08-31&seasonal=true&exclude_month_range=true would return all yearly data except for the summer months of June-August for the years from 1989-2011. Defaults to false

Shellfish Toxicity Data

This data source provides shellfish toxicity measurements for Alexandrium catenella/PSP collected at a number of fixed data stations from Maine to Massachusetts

Endpoint: https://habhub-api.whoi.edu/api/v1/stations/

Example request with date filters: https://habhub-api.whoi.edu/api/v1/stations/?start_date=2020-09-01&end_date=2020-09-30

Available filters:

  • start_date (YYYY-MM-DD format) - start date of the requested date range. Defaults to 1 year before the current date. ex: start_date=2020-12-01
  • end_date (YYYY-MM-DD format) - end date of the requested date range. Defaults to the current date. ex: end_date=2023-12-31
  • seasonal (true/false) - if true, API will return yearly chunks of seasonal data based on the start_date month and the end_date month. For example, a request of start_date=1989-06-01&end_date=2011-08-31&seasonal=true would return only the summer months of June-August for the years from 1989-2011. Defaults to false
  • exclude_month_range (true/false) - Used in conjunction with the seasonal filter. If seasonal filter is true, setting exclude_month_range=true will return yearly chunks of data that exclude the selected start and end months. For example, a request of start_date=1989-06-01&end_date=2011-08-31&seasonal=true&exclude_month_range=true would return all yearly data except for the summer months of June-August for the years from 1989-2011. Defaults to false

State Shellfish Area Closures

This data source provides past biotoxin-based shellfish area closures from state governments. Each GeoJSON object represents a polygonal shellfishing area defined as by each state's government with a list of closure notices related to each shellfish area.

This resource does not provide up-to-date information of HAB-related shellfishing closures. Check with state and/or local authorities before harvesting. For the most up-to-date information, see sites maintained by Maine Department of Marine Resources, New Hampshire Department of Environmental Services, and Massachusetts Division of Marine Fisheries and seek guidance from local town managers before harvesting.

Example request with all filters: https://habhub-api.whoi.edu/api/v1/area-closures/?start_date=2018-09-18&end_date=2023-09-18&seasonal=false&exclude_month_range=false&states=MA,NH

  • start_date (YYYY-MM-DD format) - start date of the requested date range. Defaults to 1 year before the current date. ex: start_date=2020-12-01
  • end_date (YYYY-MM-DD format) - end date of the requested date range. Defaults to the current date. ex: end_date=2023-12-31
  • seasonal (true/false) - if true, API will return yearly chunks of seasonal data based on the start_date month and the end_date month. For example, a request of start_date=1989-06-01&end_date=2011-08-31&seasonal=true would return only the summer months of June-August for the years from 1989-2011. Defaults to false
  • exclude_month_range (true/false) - Used in conjunction with the seasonal filter. If seasonal filter is true, setting exclude_month_range=true will return yearly chunks of data that exclude the selected start and end months. For example, a request of start_date=1989-06-01&end_date=2011-08-31&seasonal=true&exclude_month_range=true would return all yearly data except for the summer months of June-August for the years from 1989-2011. Defaults to false
  • states (comma separated list of state abbreviations) - filter results to only selected states. ex states=MA,NH

Python Usage Example

Below is a basic code example of how to use the Python Requests library to make an API request:

import requests

params = {
    'start_date': '2020-09-01',
    'end_date': '2020-09-30',
    'seasonal': False,
    'exclude_month_range': False,
}
r = requests.get("https://habhub-api.whoi.edu/api/v1/stations/", params=params)
print(r.text)
Clone this wiki locally