add vessel identity flag change and MOU insight support

docs/source/index.md

@@ -23,6 +23,8 @@ workflow-guides/index
 
 development-guides/index
 apidocs/index
+Releases <https://github.com/GlobalFishingWatch/gfw-api-python-client/releases>
+PyPI <https://pypi.org/project/gfw-api-python-client/>
 GitHub <https://github.com/GlobalFishingWatch/gfw-api-python-client>
 ```
 

docs/source/usage-guides/insights-api.md

@@ -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
 
@@ -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",
     ],
 )
 ```
@@ -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`)
+
+> **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`)
+
+> **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: