WHOI HABhub Classifier Model and Score API V2

Using the V2 API to get class scores from different classifier models

Classifer Scores Endpoint: https://habhub-api.whoi.edu/api/v2/ifcb-species-scores/

Example request with filters: https://habhub-api.whoi.edu/api/v2/ifcb-species-scores/?start_date=2023-06-01&end_date=2023-06-15&species=Alexandrium_catenella&model_id=HABLAB_20240110_Tripos2&score_gte=.9

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
• species (string) - comma separated list of species IDs to find. ex: species=Alexandrium_catenella,Margalefidinium
• dataset_id (string) - comma separated list of dataset IDs to find. ex: dataset_id=nauset,mvco
• model_id (string) - comma separated list of classifier model IDs to find. ex: model_id=HABLAB_20240110_Tripos2
• score_gte (decimal) - classifiers score threshold to filter results that are greater than or equal to. ex: score_gte=.9

Geo filter - limit results to a given bounding box created by the SW and NE points of the box. Both points must be specified:

• bbox_sw (string) - comma separated list of longitude/latitude (GeoJSON format) for the SW point of the box. ex: bbox_sw=-70.773926,41.508899
• bbox_ne (string) - comma separated list of longitude/latitude (GeoJSON format) for the NE point of the box. ex: bbox_ne=-69.697266,42.118917

The API response is paginated with a 100 results per page. To get all the results for a given query in a single request, you'll need to loop through the responses. An example of how to do this with Python is provided below.

Python code example

import requests

# set your filter parameters
# all parameters are optional, but unfiltered searches may return millions of results so use caution
start_date = "2023-06-01"
end_date = "2023-07-30"
species = "Alexandrium_catenella"
# dataset_id = ""
model_id = "HABLAB_20240110_Tripos2"
score_gte = ".9"
# bbox_sw = "lat,long"
# bbox_ne = "lat,long"


def fetch_paginated_results(api_url, params=None):
    """
    Fetch paginated results from an API and combine them into a single response.

    Args:
        api_url (str): The base URL of the API endpoint.
        params (dict, optional): Additional query parameters for the API request.

    Returns:
        list: A combined list of all results from all pages.
    """
    if params is None:
        params = {}

    all_results = []

    while True:
        # Make the API request
        response = requests.get(api_url, params=params)

        # Raise an error if the request failed
        response.raise_for_status()

        # Parse the JSON response
        data = response.json()
        # Get the results
        results = data["results"]
        print(results, len(results))
        # Add the current page's results to the combined list
        all_results.extend(results)

        # Get next/prev links
        links = data.get("links", None)
        # Check if there are more pages
        # Assuming the API provides a "next" field to indicate the next page
        if not links["next"]:
            break

        # Update the API URL to get next page of results
        api_url = links["next"]
        print("Next", api_url)

    return all_results


# Example usage
if __name__ == "__main__":
    API_URL = "https://habhub-api.whoi.edu/api/v2/ifcb-species-scores/"
    PARAMS = {
        "start_date": start_date,
        "end_date": end_date,
        "species": species,
        # "dataset_id": dataset_id,
        "model_id": model_id,
        "score_gte": score_gte,
        # "bbox_sw": bbox_sw,
        # "bbox_ne": bbox_ne,
    }  # Adjust parameters as needed

    try:
        combined_results = fetch_paginated_results(API_URL, params=PARAMS)
        print(f"Fetched {len(combined_results)} items.")
    except requests.RequestException as e:
        print(f"An error occurred: {e}")