Insights API¶

This guide provides detailed instructions on how to use the gfw-api-python-client to access aggregated insights about vessel activities. Currently, the Insights API focuses on providing summaries related to specific vessels over a defined time range. Here is a Jupyter Notebook version of this guide with more usage examples.

Prerequisites¶

You have installed the gfw-api-python-client. Refer to the Getting Started guide for installation instructions.
You will need a valid Vessel ID to retrieve insights for a specific vessel. You can obtain these IDs using the Vessels API.

Getting Started¶

To interact with the Insights endpoints, you first need to instantiate the gfw.Client and then access the insights resource:

import os

import gfwapiclient as gfw


access_token = os.environ.get(
    "GFW_API_ACCESS_TOKEN",
    "<OR_PASTE_YOUR_GFW_API_ACCESS_TOKEN_HERE>",
)

gfw_client = gfw.Client(
    access_token=access_token,
)

Getting Insights by Vessel (`get_vessel_insights`)¶

The get_vessel_insights() method allows you to retrieve aggregated insights for a specific vessel within a given time range.

insights_result = await gfw_client.insights.get_vessel_insights(
    includes=["FISHING"],
    start_date="2020-01-01",
    end_date="2025-03-03",
    vessels=[
        {
            "dataset_id": "public-global-vessel-identity:latest",
            "vessel_id": "785101812-2127-e5d2-e8bf-7152c5259f5f",
        }
    ],
)

Access the insights data as Pydantic model¶

insights = insights_result.data()
print(
    (
        insights.period.start_date,
        insights.period.end_date,
        insights.apparent_fishing.period_selected_counters.events,
    )
)
print(insights.model_dump())

Output:

(datetime.date(2020, 1, 1), datetime.date(2025, 3, 3), 2829)

Access the insights data as a DataFrame¶

insights_df = insights_result.df()
print(insights_df.info())
print(insights_df.head())