Skip to content

enhance insights API models, documentation, and test coverage #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lykmapipo merged 6 commits into from
Apr 29, 2026
Merged

enhance insights API models, documentation, and test coverage #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b21787a
feat(insights): improve insights API models, request handling, and do…
lykmapipo Mar 7, 2026
c3e64c5
test(insights): expand integration coverage for additional insight types
lykmapipo Mar 7, 2026
3af0d22
docs(insights): expand Insights API usage guide and notebook examples
lykmapipo Mar 8, 2026
4e5570f
Merge branch 'feature/docs' into feature/insights
lykmapipo Mar 31, 2026
c84d03c
Merge branch 'feature/docs' into feature/insights
lykmapipo Apr 29, 2026
2c410e9
docs(insights): add instructions to enable additional vessel insights
lykmapipo Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
280 changes: 275 additions & 5 deletions docs/source/usage-guides/insights-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access aggregated insights about vessel activities. Currently, the [Insights API](https://globalfishingwatch.org/our-apis/documentation#insights-api) focuses on providing summaries related to specific vessels over a defined time range. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/insights-api.ipynb) version of this guide with more usage examples.

> **Note:** See the [Insights Data Caveats](https://globalfishingwatch.org/our-apis/documentation#insights-api-fishing-detected-in-no-take-mpas)—it is critical to avoid misinterpreting the insights. You can find the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits.
> **Note:** See the [Apparent fishing detected in no-take MPAs](https://globalfishingwatch.org/our-apis/documentation#insights-api-fishing-detected-in-no-take-mpas), [Apparent fishing event detected outside known authorized areas](https://globalfishingwatch.org/our-apis/documentation#insights-api-fishing-event-detected-outside-known-authorized-areas), [Coverage](https://globalfishingwatch.org/our-apis/documentation#insights-api-coverage), [AIS off event (aka GAP)](https://globalfishingwatch.org/our-apis/documentation#insights-api-ais-off-event-aka-gap), and [RFMO IUU vessel list](https://globalfishingwatch.org/our-apis/documentation#insights-api-rfmo-iuu-vessel-list) Data Caveats — it is critical to avoid misinterpreting the insights. You can find the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits.

## Prerequisites

Expand Down Expand Up @@ -40,16 +40,15 @@ The `gfw_client.insights` object provides methods for retrieving insights data f

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

**Important:** `start_date` must be on or after `January 1, 2020`

```python
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",
}
"785101812-2127-e5d2-e8bf-7152c5259f5f",
],
)
```
Expand Down Expand Up @@ -100,6 +99,277 @@ dtypes: object(6)
memory usage: 180.0+ bytes
```

## Getting Apparent Fishing-related Insights (`FISHING`)

```python
fishing_insights_result = await gfw_client.insights.get_vessel_insights(
includes=["FISHING"],
start_date="2020-01-01",
end_date="2025-03-03",
vessels=[
"785101812-2127-e5d2-e8bf-7152c5259f5f",
"2339c52c3-3a84-1603-f968-d8890f23e1ed",
"2d26aa452-2d4f-4cae-2ec4-377f85e88dcb",
],
)
```

```python
fishing_insights_df = fishing_insights_result.df()
print(fishing_insights_df)
```

**Output:**

```
<class 'pandas.DataFrame'>
RangeIndex: 1 entries, 0 to 0
Data columns (total 6 columns):
# Column Non-Null Count Dtype
--- ------ -------------- -----
0 period 1 non-null object
1 vessel_ids_without_identity 0 non-null object
2 gap 0 non-null object
3 coverage 0 non-null object
4 apparent_fishing 1 non-null object
5 vessel_identity 0 non-null object
dtypes: object(6)
memory usage: 180.0+ bytes
```

## Getting AIS off/disabling Insights (`GAP`)

```python
gap_insights_result = await gfw_client.insights.get_vessel_insights(
includes=["GAP"],
start_date="2020-01-01",
end_date="2025-03-03",
vessels=[
"785101812-2127-e5d2-e8bf-7152c5259f5f",
"2339c52c3-3a84-1603-f968-d8890f23e1ed",
"2d26aa452-2d4f-4cae-2ec4-377f85e88dcb",
],
)
```

```python
gap_insights_df = gap_insights_result.df()
print(gap_insights_df)
```

**Output:**

```
<class 'pandas.DataFrame'>
RangeIndex: 1 entries, 0 to 0
Data columns (total 6 columns):
# Column Non-Null Count Dtype
--- ------ -------------- -----
0 period 1 non-null object
1 vessel_ids_without_identity 0 non-null object
2 gap 1 non-null object
3 coverage 0 non-null object
4 apparent_fishing 0 non-null object
5 vessel_identity 0 non-null object
dtypes: object(6)
memory usage: 180.0+ bytes
```

## Getting AIS Coverage Metrics Insights (`COVERAGE`)

```python
coverage_insights_result = await gfw_client.insights.get_vessel_insights(
includes=["COVERAGE"],
start_date="2020-01-01",
end_date="2025-03-03",
vessels=[
"2339c52c3-3a84-1603-f968-d8890f23e1ed",
],
)
```

```python
coverage_insights_df = coverage_insights_result.df()
print(coverage_insights_df)
```

**Output:**

```
<class 'pandas.DataFrame'>
RangeIndex: 1 entries, 0 to 0
Data columns (total 6 columns):
# Column Non-Null Count Dtype
--- ------ -------------- -----
0 period 1 non-null object
1 vessel_ids_without_identity 0 non-null object
2 gap 0 non-null object
3 coverage 1 non-null object
4 apparent_fishing 0 non-null object
5 vessel_identity 0 non-null object
dtypes: object(6)
memory usage: 180.0+ bytes
```

## Getting Being Listed in IUU (Illegal,Unreported, and Unregulated) Insights (`VESSEL-IDENTITY-IUU-VESSEL-LIST`)

```python
iuu_insights_result = await gfw_client.insights.get_vessel_insights(
includes=["VESSEL-IDENTITY-IUU-VESSEL-LIST"],
start_date="2020-01-01",
end_date="2025-03-03",
vessels=[
"2d26aa452-2d4f-4cae-2ec4-377f85e88dcb",
],
)
```

```python
iuu_insights_df = iuu_insights_result.df()
print(iuu_insights_df)
```

**Output:**

```
<class 'pandas.DataFrame'>
RangeIndex: 1 entries, 0 to 0
Data columns (total 6 columns):
# Column Non-Null Count Dtype
--- ------ -------------- -----
0 period 1 non-null object
1 vessel_ids_without_identity 0 non-null object
2 gap 0 non-null object
3 coverage 0 non-null object
4 apparent_fishing 0 non-null object
5 vessel_identity 1 non-null object
dtypes: object(6)
memory usage: 180.0+ bytes
```

## Getting Flag Changes Insights (`VESSEL-IDENTITY-FLAG-CHANGES`)

Comment thread
lykmapipo marked this conversation as resolved.
> **Note:** In order to enable this insight for your API access token (`GFW_API_ACCESS_TOKEN`), please contact apis@globalfishingwatch.org. In your message, please specify the email address used to generate the [API tokens](https://globalfishingwatch.org/our-apis/tokens) (i.e., the email address associated with your [Global Fishing Watch account](https://globalfishingwatch.org/our-apis/tokens/signup)).

```python
flag_changes_insights_result = await gfw_client.insights.get_vessel_insights(
includes=["VESSEL-IDENTITY-FLAG-CHANGES"],
start_date="2020-01-01",
end_date="2025-03-03",
vessels=[
"2d26aa452-2d4f-4cae-2ec4-377f85e88dcb",
],
)
```

```python
flag_changes_insights_df = flag_changes_insights_result.df()
print(flag_changes_insights_df.info())
```

**Output:**

```
<class 'pandas.DataFrame'>
RangeIndex: 1 entries, 0 to 0
Data columns (total 6 columns):
# Column Non-Null Count Dtype
--- ------ -------------- -----
0 period 1 non-null object
1 vessel_ids_without_identity 0 non-null object
2 gap 0 non-null object
3 coverage 0 non-null object
4 apparent_fishing 0 non-null object
5 vessel_identity 1 non-null object
dtypes: object(6)
memory usage: 180.0+ bytes
```

## Getting Flag State Presence under Tokyo/Paris MOU black or grey Lists Insights (`VESSEL-IDENTITY-MOU-LIST`)

Comment thread
lykmapipo marked this conversation as resolved.
> **Note:** In order to enable this insight for your API access token (`GFW_API_ACCESS_TOKEN`), please contact apis@globalfishingwatch.org. In your message, please specify the email address used to generate the [API tokens](https://globalfishingwatch.org/our-apis/tokens) (i.e., the email address associated with your [Global Fishing Watch account](https://globalfishingwatch.org/our-apis/tokens/signup)).

```python
mou_insights_result = await gfw_client.insights.get_vessel_insights(
includes=["VESSEL-IDENTITY-MOU-LIST"],
start_date="2020-01-01",
end_date="2025-03-03",
vessels=[
"785101812-2127-e5d2-e8bf-7152c5259f5f",
],
)
```

```python
mou_insights_df = mou_insights_result.df()
print(mou_insights_df.info())
```

**Output:**

```
<class 'pandas.DataFrame'>
RangeIndex: 1 entries, 0 to 0
Data columns (total 6 columns):
# Column Non-Null Count Dtype
--- ------ -------------- -----
0 period 1 non-null object
1 vessel_ids_without_identity 0 non-null object
2 gap 0 non-null object
3 coverage 0 non-null object
4 apparent_fishing 0 non-null object
5 vessel_identity 1 non-null object
dtypes: object(6)
memory usage: 180.0+ bytes
```

## Getting Multiple Insights for Multiple Vessels

> **Note:** In order to enable `VESSEL-IDENTITY-FLAG-CHANGES` and `VESSEL-IDENTITY-MOU-LIST` insights for your API access token (`GFW_API_ACCESS_TOKEN`), please contact apis@globalfishingwatch.org. In your message, please specify the email address used to generate the [API tokens](https://globalfishingwatch.org/our-apis/tokens) (i.e., the email address associated with your [Global Fishing Watch account](https://globalfishingwatch.org/our-apis/tokens/signup)).

```python
all_insights_result = await gfw_client.insights.get_vessel_insights(
includes=[
"FISHING",
"GAP",
"VESSEL-IDENTITY-IUU-VESSEL-LIST",
"COVERAGE",
"VESSEL-IDENTITY-FLAG-CHANGES",
"VESSEL-IDENTITY-MOU-LIST",
],
start_date="2020-01-01",
end_date="2025-03-03",
vessels=[
"785101812-2127-e5d2-e8bf-7152c5259f5f",
"2339c52c3-3a84-1603-f968-d8890f23e1ed",
"2d26aa452-2d4f-4cae-2ec4-377f85e88dcb",
],
)
```

```python
all_insights_df = all_insights_result.df()
print(all_insights_df.info())
```

**Output:**

```
<class 'pandas.DataFrame'>
RangeIndex: 1 entries, 0 to 0
Data columns (total 6 columns):
# Column Non-Null Count Dtype
--- ------ -------------- -----
0 period 1 non-null object
1 vessel_ids_without_identity 0 non-null object
2 gap 1 non-null object
3 coverage 1 non-null object
4 apparent_fishing 1 non-null object
5 vessel_identity 1 non-null object
dtypes: object(6)
memory usage: 180.0+ bytes
```

## Next Steps

Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine vessel insights with event data, vessel details, and more. Check out the following resources:
Expand Down
Loading
Loading