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.

Note: See the Insights Data Caveats—it is critical to avoid misinterpreting the insights. You can find the Datasets, and Terms of Use pages in the GFW API documentation for details on GFW data, API licenses, and rate limits.

Prerequisites¶

Before using the gfw-api-python-client, ensure it is installed (see the Getting Started guide) and that you have obtained an API access token from the Global Fishing Watch API portal.
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,
)

The gfw_client.insights object provides methods for retrieving insights data for specified vessels. Each of these methods returns a result object, which offers convenient ways to access the data as Pydantic models using .data() or as pandas DataFrames using .df().

Tip: Use IPython or Python 3.11+ with python -m asyncio to run gfw-api-python-client code interactively, as these environments support executing async / await expressions directly in the console.

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())