diff --git a/docs/source/conf.py b/docs/source/conf.py index 7538520..452f9e5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -34,8 +34,8 @@ "sphinx.ext.autodoc", "sphinx.ext.intersphinx", # third-party extensions - "myst_parser", - # "myst_nb", + # "myst_parser", # imported by myst_nb automatically + "myst_nb", "autodoc2", "sphinx_copybutton", "sphinx_inline_tabs", @@ -47,7 +47,8 @@ # The suffix of source filenames. source_suffix = { ".rst": "restructuredtext", - ".md": "markdown", + ".md": "myst-nb", + ".ipynb": "myst-nb", } # The master toctree document. @@ -95,6 +96,16 @@ ] myst_heading_anchors = 3 +# -- MyST-NB execution configuration ------------------------------------------ +# https://myst-nb.readthedocs.io/en/latest/configuration.html#config-intro + +nb_execution_mode = "force" +nb_execution_timeout = 300 +nb_execution_raise_on_error = True + +nb_output_stderr = "show" +nb_merge_streams = True + # -- Options for autodoc2 ------------------------------------------------- # https://sphinx-autodoc2.readthedocs.io/en/latest/config.html diff --git a/docs/source/getting-started.md b/docs/source/getting-started.md index 9bccd24..cbb841d 100644 --- a/docs/source/getting-started.md +++ b/docs/source/getting-started.md @@ -226,6 +226,6 @@ memory usage: 43.7+ KB This guide has provided you with the fundamental steps to install and use the `gfw-api-python-client` for making basic API requests. -To further explore the capabilities of our APIs (`4Wings`, `Vessels`, `Events`, `Insights`, `Datasets`, `References`, etc.), please refer to the detailed [Usage Guides](usage-guides/index). These guides delve into specific use cases and demonstrate how to effectively leverage the `gfw-api-python-client` for your data exploration needs. +To further explore the capabilities of our APIs (`4Wings`, `Vessels`, `Events`, `Insights`, `Datasets`, `References`, etc.), please refer to the detailed [Usage Guides](usage-guides/index) and [Workflow Guides](workflow-guides/index). These guides delve into specific use cases and demonstrate how to effectively leverage the `gfw-api-python-client` for your data exploration needs. Happy coding and data exploring! diff --git a/docs/source/index.md b/docs/source/index.md index bb58aed..188bcd3 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -14,6 +14,7 @@ The `gfw-api-python-client` simplifies access to Global Fishing Watch (GFW) data getting-started installation usage-guides/index +workflow-guides/index ``` ```{toctree} @@ -49,6 +50,10 @@ To learn about how to use `gfw-api-python-client`, check out the following resou - [Insights API](usage-guides/insights-api) - [Datasets API](usage-guides/datasets-api) - [References Data API](usage-guides/references-data-api) +- [Workflow Guides](workflow-guides/index) + - [Analyze apparent fishing effort in Senegalese EEZ](workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez) + - [Analyze apparent fishing effort in Argentinian EEZ](workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez) + - [Analyze a fleet in Ghanaian EEZ](workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez) If you find bugs, need help, or want to contribute, check out the following resources: diff --git a/docs/source/usage-guides/4wings-api.md b/docs/source/usage-guides/4wings-api.md index 748f00b..e3b58cc 100644 --- a/docs/source/usage-guides/4wings-api.md +++ b/docs/source/usage-guides/4wings-api.md @@ -374,7 +374,7 @@ The 4Wings API often requires specifying geographic regions. You can use the [Re ## Next Steps -Explore the [Usage Guides](index) for other API resources to understand how you can combine the reporting and statistical capabilities of the 4Wings API with vessel information, event data, and more. Check out the following resources: +Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine the reporting and statistical capabilities of the 4Wings API with vessel information, event data, and more. Check out the following resources: - [Vessels API](vessels-api) - [Events API](events-api) diff --git a/docs/source/usage-guides/datasets-api.md b/docs/source/usage-guides/datasets-api.md index 0c1e96f..3e9c587 100644 --- a/docs/source/usage-guides/datasets-api.md +++ b/docs/source/usage-guides/datasets-api.md @@ -169,7 +169,7 @@ memory usage: 60.6+ KB ## Next Steps -Explore the [Usage Guides](index) for other API resources. Check out the following resources: +Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources. Check out the following resources: - [4Wings API](4wings-api) - [Vessels API](vessels-api) diff --git a/docs/source/usage-guides/events-api.md b/docs/source/usage-guides/events-api.md index c570a91..f3afd85 100644 --- a/docs/source/usage-guides/events-api.md +++ b/docs/source/usage-guides/events-api.md @@ -219,7 +219,7 @@ Please be aware that the accuracy and completeness of the event data can vary. R ## Next Steps -Explore the [Usage Guides](index) for other API resources to understand how you can combine event data with information about vessels, and more. Check out the following resources: +Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine event data with information about vessels, and more. Check out the following resources: - [4Wings API](4wings-api) - [Vessels API](vessels-api) diff --git a/docs/source/usage-guides/insights-api.md b/docs/source/usage-guides/insights-api.md index 5208c2b..51c0813 100644 --- a/docs/source/usage-guides/insights-api.md +++ b/docs/source/usage-guides/insights-api.md @@ -98,7 +98,7 @@ memory usage: 180.0+ bytes ## Next Steps -Explore the [Usage 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: +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: - [Vessels API](vessels-api) - [Events API](events-api) diff --git a/docs/source/usage-guides/references-data-api.md b/docs/source/usage-guides/references-data-api.md index 1290a74..b54c014 100644 --- a/docs/source/usage-guides/references-data-api.md +++ b/docs/source/usage-guides/references-data-api.md @@ -178,7 +178,7 @@ memory usage: 1.4+ KB ## Next Steps -Explore the [Usage Guides](index) for other API resources to understand how you can combine reference data with dynamic information about events, vessels, and more. Check out the following resources: +Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine reference data with dynamic information about events, vessels, and more. Check out the following resources: - [4Wings API](4wings-api) - [Vessels API](vessels-api) diff --git a/docs/source/usage-guides/vessels-api.md b/docs/source/usage-guides/vessels-api.md index ec9ef6c..4120d06 100644 --- a/docs/source/usage-guides/vessels-api.md +++ b/docs/source/usage-guides/vessels-api.md @@ -198,7 +198,7 @@ memory usage: 188.0+ bytes ## Next Steps -Explore the [Usage Guides](index) for other API resources to understand how you can combine vessel data with information about events, and more. Check out the following resources: +Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine vessel data with information about events, and more. Check out the following resources: - [4Wings API](4wings-api) - [Events API](events-api) diff --git a/docs/source/workflow-guides/index.md b/docs/source/workflow-guides/index.md new file mode 100644 index 0000000..e3adbac --- /dev/null +++ b/docs/source/workflow-guides/index.md @@ -0,0 +1,14 @@ +# Workflow Guides + +The sections below provide detailed instructions on how to combine Global Fishing Watch APIs to build powerful **workflows** and **applications** for a variety of **use cases** using the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client). For additional context and expanded explanations, refer to the [API Workflows Guide (PDF)](https://globalfishingwatch.org/our-apis/assets/2025_GFW_API_Workflows.pdf), and [API Workflows](https://globalfishingwatch.org/our-apis/documentation#api-workflows) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction). + + +> **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), 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. + +```{toctree} +:maxdepth: 1 + +workflow-01-analyze-apparent-fishing-effort-senegalese-eez +workflow-02-analyze-apparent-fishing-effort-argentinian-eez +workflow-03-analyze-fleet-in-ghanaian-eez +``` diff --git a/docs/source/workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez.ipynb b/docs/source/workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez.ipynb new file mode 100644 index 0000000..c37fb6a --- /dev/null +++ b/docs/source/workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez.ipynb @@ -0,0 +1,1260 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "1b582ffc-7477-46c3-b5bf-2caf9d028bf2", + "metadata": {}, + "source": [ + "\"Open" + ] + }, + { + "cell_type": "markdown", + "id": "87eddf13-ac9c-45b0-ae10-24eb1620e07e", + "metadata": {}, + "source": [ + "# Analyze apparent fishing effort in Senegalese EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "d79f0ab4-ab4d-4098-82b0-b6a5c772e101", + "metadata": {}, + "source": [ + "This guide provides detailed instructions to on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to **Analyze apparent fishing effort in [Senegalese EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8371) region and monitor vessel activities** using **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)**, and **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)**." + ] + }, + { + "cell_type": "markdown", + "id": "7ac25ecf-ffd7-40d7-9ea0-a6514c9fcd85", + "metadata": {}, + "source": [ + "**Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), 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." + ] + }, + { + "cell_type": "markdown", + "id": "71018cec-10c0-4619-9a7d-838a9f43cb15", + "metadata": {}, + "source": [ + "## Prerequisites" + ] + }, + { + "cell_type": "markdown", + "id": "996ca24b-99e4-4546-805b-697e4c2eb321", + "metadata": {}, + "source": [ + "Before using the `gfw-api-python-client`, ensure it is installed (see the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html) guide) and that you have obtained an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)." + ] + }, + { + "cell_type": "markdown", + "id": "6be16f6f-19fc-4d19-a0ed-ba370c844fa6", + "metadata": {}, + "source": [ + "## Installation" + ] + }, + { + "cell_type": "markdown", + "id": "af48cf4e-e24c-47aa-a2c5-64cf87be9c33", + "metadata": {}, + "source": [ + "The `gfw-api-python-client` can be easily installed using pip:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "88c09924-87d2-4c86-ad60-aed623416193", + "metadata": {}, + "outputs": [], + "source": [ + "# %pip install gfw-api-python-client" + ] + }, + { + "cell_type": "markdown", + "id": "eafaa9d1-2143-452c-813c-75b21fd2198c", + "metadata": {}, + "source": [ + "## Usage" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "cc98323c-c9e4-401c-8f26-f551968c003a", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "import datetime\n", + "import pandas as pd\n", + "import gfwapiclient as gfw" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "047ff069-3c87-47fe-bb4a-acb920df2137", + "metadata": {}, + "outputs": [], + "source": [ + "try:\n", + " from google.colab import userdata\n", + "\n", + " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", + "except Exception as exc:\n", + " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", + "\n", + "access_token = access_token or \"\"" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "708e137f-6aa0-461e-b1af-33512a2093fc", + "metadata": {}, + "outputs": [], + "source": [ + "gfw_client = gfw.Client(\n", + " access_token=access_token,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b08a0e2c-3b9d-4c5e-b3a0-a5663fa32637", + "metadata": {}, + "source": [ + "## Introduction" + ] + }, + { + "cell_type": "markdown", + "id": "62fe47aa-ed77-4815-b08d-8c96f2480b04", + "metadata": {}, + "source": [ + "**Use Case: A Port Inspector Monitoring Vessel Activity**" + ] + }, + { + "cell_type": "markdown", + "id": "5109f67f-aaae-4a7d-9a15-4db740542694", + "metadata": {}, + "source": [ + "Mamadou, a port inspector in Dakar, Senegal, monitors vessel activity within **[Senegalese Exclusive Economic Zone (EEZ)]((https://www.marineregions.org/gazetteer.php?p=details&id=8371))**. His goal is to:\n", + "\n", + "1. Analyzing apparent fishing effort, specifically for **trawlers** in Senegalese EEZ.\n", + "2. Identifying vessels involved in **apparent trawling activity** and determining their reported **flag states**.\n", + "3. Checking vessel history, including prior **encounters (or potential transshipment)** or **port visits**.\n", + "4. Generating reports for enforcement authorities to assess risks." + ] + }, + { + "cell_type": "markdown", + "id": "b16b1b52-6b68-494a-9d76-ca7a7ab485a0", + "metadata": {}, + "source": [ + "**APIs Used:**\n", + "️\n", + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** – To retrieve **apparent fishing effort** data for trawlers operating in Senegalese EEZ over the past 3 months.\n", + "2. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** – To retrieve **detailed vessel information**, including `flag`, `ownership history`, and `authorizations`." + ] + }, + { + "cell_type": "markdown", + "id": "a6006ce5-675f-4d1f-89a5-69130ff1ed5b", + "metadata": {}, + "source": [ + "**Important:** In order to avoid any misinterpretation of **GFW data**, please refer to our official **data caveats** documentations:\n", + "- [Apparent fishing effort](https://globalfishingwatch.org/dataset-and-code-fishing-effort/) \n", + "- [Exclusive economic zone boundaries definition](https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition)\n", + "- [Vessel ID](https://globalfishingwatch.org/our-apis/documentation#vessel-id)\n", + "- [Vessel API - Vessel identity information](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)" + ] + }, + { + "cell_type": "markdown", + "id": "5413d78e-e745-4f74-a062-f303c7a1669f", + "metadata": {}, + "source": [ + "**Important Caveats:**\n", + "\n", + "1. The [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api) only supports **one active report per user at a time**.\n", + "2. **Sending multiple requests simultaneously** results in a **429 Too Many Requests** error.\n", + "3. If a report takes over **100 seconds** to generate, it may return a **524 Gateway Timeout** error." + ] + }, + { + "cell_type": "markdown", + "id": "2c1e1858-c328-4719-8f10-40ae5b43ecb0", + "metadata": {}, + "source": [ + "## Step 0: Identify the Region of Interest (ROI) - Senegalese EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "7d5e3571-f47f-4c2f-8d0d-0c89baae4411", + "metadata": {}, + "source": [ + "Before making API requests, Mamadou must specify the geographic area for analysis using a **Region ID**:" + ] + }, + { + "cell_type": "markdown", + "id": "75a985b1-3803-48d9-b2f3-f12b29bd29e7", + "metadata": {}, + "source": [ + "**Options to Define the Region:**\n", + "\n", + "1. **Using Region ID** - Each EEZ has a unique ID in the **[public-eez-areas](https://globalfishingwatch.org/our-apis/documentation#regions)** dataset.\n", + "2. **Custom Geometries** - Users can define a custom area using GeoJSON.\n", + " \n", + "For **[Senegalese EEZ, the region ID is 8371](https://www.marineregions.org/gazetteer.php?p=details&id=8371)** (public-eez-areas dataset)." + ] + }, + { + "cell_type": "markdown", + "id": "6fe5edf3-8e96-4147-8c59-a6bc8982662d", + "metadata": {}, + "source": [ + "## Step 1: Retrieve Apparent Fishing Effort in Senegalese EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "4bede3c0-3d01-4661-8b88-467244417d20", + "metadata": {}, + "source": [ + "Mamadou **first queries** the **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** to get **apparent fishing effort for all vessels**, grouping them by **vessel ID** in **[Senegalese EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8371)**. Please [learn more about apparent fishing effort here](https://globalfishingwatch.org/our-apis/documentation#ais-apparent-fishing-effort) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort)." + ] + }, + { + "cell_type": "markdown", + "id": "2e2e42d9-1b9e-4115-b601-72d0e86ab91d", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **[Region ID](https://globalfishingwatch.org/our-apis/documentation#regions)** - [8371 Senegalese EEZ]((https://www.marineregions.org/gazetteer.php?p=details&id=8371))\n", + "2. **[Date Range](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Last 3 Months\n", + "3. **[Grouped By](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Vessel ID\n", + "4. **[Gear Type](https://globalfishingwatch.org/our-apis/documentation#gear-types-supported)** - Trawlers " + ] + }, + { + "cell_type": "markdown", + "id": "849f6157-fa79-456f-8974-d294c77a0729", + "metadata": {}, + "source": [ + "**Why Use group-by=VESSEL_ID?**\n", + "\n", + "Grouping by **VESSEL_ID** allows **individual vessel identification** in the response. This is crucial for **tracking vessel activity** and, more importantly, linking each detected vessel to the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** in the next step. By structuring the query this way, we can fetch vessel details such as **flag, name, and ownership records** in **Step 2 below**.\n" + ] + }, + { + "cell_type": "markdown", + "id": "cf72ff2d-afd7-45bb-8350-aceaebc154d4", + "metadata": {}, + "source": [ + "**Explanation of Parameters & Considerations**\n", + "\n", + "- Gear types, such as **trawlers**, are inferred based on **Global Fishing Watch’s vessel classification system**, which relies on **AIS data and vessel public registries**. The **gear type associated with each vessel is not always 100% accurate**, as it may be derived from historical sources or inferred from movement patterns. See more details on [supported gear types here](https://globalfishingwatch.org/our-apis/documentation#gear-types-supported).\n", + "- Also, please see data caveats regarding [vessel types and their classification here](https://globalfishingwatch.org/our-apis/documentation#vessel-types).\n", + "- See more details on retrieving [Region IDs here](https://globalfishingwatch.org/our-apis/documentation#regions)." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "db35d1b2-ba32-4a58-97f3-17059b3de164", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", + " spatial_resolution=\"HIGH\",\n", + " group_by=\"VESSEL_ID\",\n", + " temporal_resolution=\"MONTHLY\",\n", + " filters=[\"geartype in ('trawlers')\"],\n", + " start_date=\"2024-11-01\",\n", + " end_date=\"2025-01-31\",\n", + " spatial_aggregation=True,\n", + " region={\n", + " \"dataset\": \"public-eez-areas\",\n", + " \"id\": \"8371\",\n", + " },\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "301f888e-3b7e-4946-a7aa-496e05b53cbd", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_df = step_1_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "866f84fb-50c4-47e2-95fa-43fbc06d17cd", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 170 entries, 0 to 169\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 170 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 170 non-null object \n", + " 3 gear_type 170 non-null object \n", + " 4 hours 170 non-null float64 \n", + " 5 vessel_ids 0 non-null object \n", + " 6 vessel_id 170 non-null object \n", + " 7 vessel_type 170 non-null object \n", + " 8 entry_timestamp 170 non-null datetime64[ns, UTC]\n", + " 9 exit_timestamp 170 non-null datetime64[ns, UTC]\n", + " 10 first_transmission_date 170 non-null datetime64[ns, UTC]\n", + " 11 last_transmission_date 170 non-null datetime64[ns, UTC]\n", + " 12 imo 170 non-null object \n", + " 13 mmsi 170 non-null object \n", + " 14 call_sign 170 non-null object \n", + " 15 dataset 170 non-null object \n", + " 16 report_dataset 170 non-null object \n", + " 17 ship_name 170 non-null object \n", + " 18 lat 0 non-null object \n", + " 19 lon 0 non-null object \n", + "dtypes: datetime64[ns, UTC](4), float64(1), object(15)\n", + "memory usage: 26.7+ KB\n" + ] + } + ], + "source": [ + "step_1_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "c76de7b9-260b-4469-aea5-0ad8fe2f25a4", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typehoursmmsiship_name
0CHNTRAWLERS31.888889412444322MIN LONG YU61146
1SENTRAWLERS524.815556663093000AMINE
2CHNTRAWLERS0.368056412209175MENGXIN24
3ESPTRAWLERS1.306389225987981CIUDAD DE HUELVA
4CHNTRAWLERS216.545000412549331YUAN YU 886
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours mmsi ship_name\n", + "0 CHN TRAWLERS 31.888889 412444322 MIN LONG YU61146\n", + "1 SEN TRAWLERS 524.815556 663093000 AMINE\n", + "2 CHN TRAWLERS 0.368056 412209175 MENGXIN24\n", + "3 ESP TRAWLERS 1.306389 225987981 CIUDAD DE HUELVA\n", + "4 CHN TRAWLERS 216.545000 412549331 YUAN YU 886" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_report_df[[\"flag\", \"gear_type\", \"hours\", \"mmsi\", \"ship_name\"]].head()" + ] + }, + { + "cell_type": "markdown", + "id": "792a7b37-50c6-4218-afc9-1e2d1bcdfdb6", + "metadata": {}, + "source": [ + "### Explore Vessels Potentially Engaged in Trawling Activity in the Senegalese EEZ" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "c44d3d72-ebe5-4fe0-85fb-8e8675bd1922", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_agg_report_df = (\n", + " step_1_report_df.groupby([\"flag\", \"gear_type\", \"mmsi\", \"ship_name\"], as_index=False)\n", + " .agg(hours=(\"hours\", \"sum\"))\n", + " .sort_values(by=\"hours\", ascending=False)\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "545d63f0-e3b6-4e81-8c5c-55990eeec9b0", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typemmsiship_namehours
66SENTRAWLERS663178000NUEVONOSOLAR1678.888333
52SENTRAWLERS663115000BETTY1648.771944
49SENTRAWLERS663112000TADORNE1610.828611
42SENTRAWLERS663039000SEGUNDO SAN RAFAEL1595.538333
74SENTRAWLERS663250000PRAIA DA MAROSA1573.587500
\n", + "
" + ], + "text/plain": [ + " flag gear_type mmsi ship_name hours\n", + "66 SEN TRAWLERS 663178000 NUEVONOSOLAR 1678.888333\n", + "52 SEN TRAWLERS 663115000 BETTY 1648.771944\n", + "49 SEN TRAWLERS 663112000 TADORNE 1610.828611\n", + "42 SEN TRAWLERS 663039000 SEGUNDO SAN RAFAEL 1595.538333\n", + "74 SEN TRAWLERS 663250000 PRAIA DA MAROSA 1573.587500" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_agg_report_df.head()" + ] + }, + { + "cell_type": "markdown", + "id": "3f948958-ebce-4478-8b17-d6143c38956b", + "metadata": {}, + "source": [ + "### What We have Learned from Step 1" + ] + }, + { + "cell_type": "markdown", + "id": "7d51287d-263b-4ff5-a40a-5efa7e7ea0a4", + "metadata": {}, + "source": [ + "- There are vessels appear to have been engaged in potential trawling activity in Senegalese EEZ over the past 3 months i.e.,:\n", + " - `NUEVONOSOLAR (mmsi: 663178000, flag: SEN)`\n", + " - `BETTY (mmsi: 663115000, flag: SEN)`\n", + "- We will retrieve these vessels' `ownership`, `flag history`, and `authorizations` in **Step 2 to validate** them." + ] + }, + { + "cell_type": "markdown", + "id": "80289282-d160-4901-9bf8-a7996785c898", + "metadata": {}, + "source": [ + "## Step 2: Retrieve Vessel Details Using the Vessels API" + ] + }, + { + "cell_type": "markdown", + "id": "dcbde755-0e9c-48d9-babe-aaee3179b88d", + "metadata": {}, + "source": [ + "Mamadou queries the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** to **get detailed vessel identity and ownership records**. Please [learn more about Vessels API here](https://globalfishingwatch.org/our-apis/documentation#vessels-api) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)." + ] + }, + { + "cell_type": "markdown", + "id": "ba645e15-f111-48f3-96a4-7e091f27669e", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **Vessel IDs** from [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api), **Step 1 above**.\n", + "2. **[Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset)** - `public-global-vessel-identity:latest`.\n", + "3. **[Includes](https://globalfishingwatch.org/our-apis/documentation#get-vessels-by-ids-url-parameters)** - `POTENTIAL_RELATED_SELF_REPORTED_INFO`." + ] + }, + { + "cell_type": "markdown", + "id": "42a309da-6a56-46a0-aa86-2a148d21d855", + "metadata": {}, + "source": [ + "**Note:** Vessels may change identifiers over time, such as their `Maritime Mobile Service Identity (MMSI)`,` International Maritime Organization (IMO) number)`, `call sign`, or even their `name`. These changes can occur due to `re-registration`, `changes in ownership`, or other `operational reasons` within the `AIS transponder`. Parameter (`includes = POTENTIAL_RELATED_SELF_REPORTED_INFO`) helps group all **vessel ids** that are **potentially related** as part of the **same physical vessel** based on publicly available registry information." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "5b507df7-99fe-4bb2-82da-7ed4ad4cfa8e", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_vessel_mmsis = list(step_1_agg_report_df[\"mmsi\"].head(n=2))" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "f87106f0-b2a0-482c-bd1f-d11119ee53a3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['663178000', '663115000']" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_vessel_mmsis" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "1eb89d2a-4d53-4d67-a668-0cbb233e950c", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_vessel_ids = list(\n", + " step_1_report_df[step_1_report_df[\"mmsi\"].isin(step_1_vessel_mmsis)][\n", + " \"vessel_id\"\n", + " ].unique()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "e670a688-3af0-410d-b93b-ec1e06ec4e09", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['894bc3ec6-6ade-f09c-e792-ff2e947508d8',\n", + " 'bf28c5a58-8c83-8690-8689-7f2d520f926e']" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_vessel_ids" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "428889bd-4761-4301-b21e-fbc37eba5622", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_vessels_result = await gfw_client.vessels.get_vessels_by_ids(\n", + " ids=step_1_vessel_ids,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "c64d68dc-b952-412f-827c-df5236c98bd7", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_vessels_df = step_2_vessels_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "757e6c3c-d0df-4b8f-839d-1e31518d42d7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 2 entries, 0 to 1\n", + "Data columns (total 7 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 dataset 2 non-null object\n", + " 1 registry_info_total_records 2 non-null int64 \n", + " 2 registry_info 2 non-null object\n", + " 3 registry_owners 2 non-null object\n", + " 4 registry_public_authorizations 2 non-null object\n", + " 5 combined_sources_info 2 non-null object\n", + " 6 self_reported_info 2 non-null object\n", + "dtypes: int64(1), object(6)\n", + "memory usage: 244.0+ bytes\n" + ] + } + ], + "source": [ + "step_2_vessels_df.info()" + ] + }, + { + "cell_type": "markdown", + "id": "7746d027-fb76-41dd-86e9-b949284ec19c", + "metadata": {}, + "source": [ + "**Understanding Vessel Details Response Data**\n", + "\n", + "- **registryInfoTotalRecords** – This represents the **number of registry records** found for the vessels.\n", + "- **registryInfo** – Contains **public registry data**. This data is sourced from official **vessel registries**.\n", + "- **registryOwners** – Lists the **registered owners** of the vessel based on public sources.\n", + "- **registryPublicAuthorizations** – Represents known **fishing authorizations** from public sources. Users should verify against national registries and RFMO records for additional context.\n", + "- **combinedSourcesInfo** – Provides inferred data from multiple sources, including. This is not explicitly reported by vessels but determined through **GFW's classification methods**.\n", + "- **selfReportedInfo** – Contains **AIS self-reported** data, including `MMSI`, `ship name`, and `flag` as broadcast by the **vessel itself**. Self-reported data may not always align with registry data and should be cross-checked." + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "4767e025-e26e-4a61-8971-8f2cc90385cc", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
registry_inforegistry_ownersself_reported_info
0[{'id': '199483471cd2da3717552fddb1a3172a', 's...[{'name': 'ARMEMENT SOPASEN', 'flag': 'SEN', '...[{'id': '894bc3ec6-6ade-f09c-e792-ff2e947508d8...
1[{'id': '29fef17154387858d8d4c777311c57f7', 's...[{'name': 'SENEVISA', 'flag': 'ESP', 'ssvid': ...[{'id': 'bf28c5a58-8c83-8690-8689-7f2d520f926e...
\n", + "
" + ], + "text/plain": [ + " registry_info \\\n", + "0 [{'id': '199483471cd2da3717552fddb1a3172a', 's... \n", + "1 [{'id': '29fef17154387858d8d4c777311c57f7', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'ARMEMENT SOPASEN', 'flag': 'SEN', '... \n", + "1 [{'name': 'SENEVISA', 'flag': 'ESP', 'ssvid': ... \n", + "\n", + " self_reported_info \n", + "0 [{'id': '894bc3ec6-6ade-f09c-e792-ff2e947508d8... \n", + "1 [{'id': 'bf28c5a58-8c83-8690-8689-7f2d520f926e... " + ] + }, + "execution_count": 18, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_vessels_df[[\"registry_info\", \"registry_owners\", \"self_reported_info\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "46760bde-049d-433c-817d-ae63b1c58924", + "metadata": {}, + "source": [ + "### Explore Vessels Registry Info" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "7efdc6d6-52d8-40bb-9537-e09f242fdb25", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_registry_info_df = pd.json_normalize(\n", + " step_2_vessels_df[\"registry_info\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "27ab60a9-6496-4406-9ae4-57a7aa97f6fa", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namegear_typessource_code
0663115000SENBETTYBETTY[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
1663178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
2762178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
3552178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name gear_types \\\n", + "0 663115000 SEN BETTY BETTY [TRAWLERS] \n", + "1 663178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "2 762178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "3 552178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "\n", + " source_code \n", + "0 [IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL] \n", + "1 [IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL] \n", + "2 [IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL] \n", + "3 [IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL] " + ] + }, + "execution_count": 20, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_registry_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"gear_types\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "db341dcf-c0a4-48df-bcc9-1e8fa78d3b25", + "metadata": {}, + "source": [ + "### Explore Registry Owners" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "24cec6f2-3e70-4396-a779-13ace779733f", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_registry_owners_df = pd.json_normalize(\n", + " step_2_vessels_df[\"registry_owners\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "16f804f4-ea4f-4a07-8c53-497e09deddfd", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagnamesource_code
0663115000SENARMEMENT SOPASEN[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
1663178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
2663176000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
3762178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
4552178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag name source_code\n", + "0 663115000 SEN ARMEMENT SOPASEN [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "1 663178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "2 663176000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "3 762178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "4 552178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]" + ] + }, + "execution_count": 22, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_registry_owners_df[[\"ssvid\", \"flag\", \"name\", \"source_code\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "7a22580f-7c7a-4181-9a80-e37687cc0471", + "metadata": {}, + "source": [ + "### Explore Vessels Self Reported Info" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "c2fa4bdd-1b51-4b37-abf5-aa18a1cab3e5", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_self_reported_info_df = pd.json_normalize(\n", + " step_2_vessels_df[\"self_reported_info\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "d1b559c7-4587-4019-a843-181017dd3f07", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namesource_code
0663115000SENBETTYBETTY[AIS]
1663178000SENNUEVONOSOLARNUEVONOSOLAR[AIS]
2663178000SENNUEVO=NOSOLAR+3&!U.?NUEVONOSOLAR3U[AIS]
3762178000NoneNUEVO NOSOLARNUEVONOSOLAR[AIS]
4552178000NoneNUEVO NOSOLARNUEVONOSOLAR[AIS]
5663178000SENNUEVO NOSOLARNUEVONOSOLAR[AIS]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name source_code\n", + "0 663115000 SEN BETTY BETTY [AIS]\n", + "1 663178000 SEN NUEVONOSOLAR NUEVONOSOLAR [AIS]\n", + "2 663178000 SEN NUEVO=NOSOLAR+3&!U.? NUEVONOSOLAR3U [AIS]\n", + "3 762178000 None NUEVO NOSOLAR NUEVONOSOLAR [AIS]\n", + "4 552178000 None NUEVO NOSOLAR NUEVONOSOLAR [AIS]\n", + "5 663178000 SEN NUEVO NOSOLAR NUEVONOSOLAR [AIS]" + ] + }, + "execution_count": 24, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_self_reported_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "6a6bcbcd-49a8-4575-9003-d8495deeb2d3", + "metadata": {}, + "source": [ + "### What We have Learned from Step 2" + ] + }, + { + "cell_type": "markdown", + "id": "53b4b694-b730-451c-b853-01485b6ca38c", + "metadata": {}, + "source": [ + "- **Vessel Identity:**\n", + " - `NUEVONOSOLAR (mmsi: 663178000, flag: SEN)`- appears to be registered under Senegal (SEN)\n", + " - `BETTY (mmsi: 663115000, flag: SEN)` - appears to be registered under Senegal (SEN)\n", + "- **Ownership & Historical Changes:**\n", + " - `NUEVONOSOLAR (mmsi: 663178000, flag: SEN)` - **SENEVISA** appears to be listed as the registered owner.\n", + " - `BETTY (mmsi: 663115000, flag: SEN)`- **ARMEMENT SOPASEN** appears to be listed as the registered owner." + ] + }, + { + "cell_type": "markdown", + "id": "e35fec91-477e-4fb5-99f2-766b3a5dbeff", + "metadata": {}, + "source": [ + "**Next Steps:**\n", + "\n", + "- Further, **validate ownership history** using official registry sources.\n", + "- Assess whether any **historical changes** in `flag`, `name`, or `ownership` are relevant for enforcement.\n", + "- Generate an **apparent activity report** with all available details." + ] + }, + { + "cell_type": "markdown", + "id": "8b951044-6905-4e38-9885-13a98cf3a7cf", + "metadata": {}, + "source": [ + "## Summary of API Flow" + ] + }, + { + "cell_type": "markdown", + "id": "c8f86731-be44-4b89-8abb-cf2f6693b4c9", + "metadata": {}, + "source": [ + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** - Retrieve apparent fishing effort for **trawlers** within Senegalese EEZ.\n", + "2. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** - Fetch detailed **vessel identity**, **ownership history**, and **public authorizations** for vessels detected in **Step 1**.\n", + "3. **Analyze vessel history** - Compare **registry records**, **AIS self-reported** data, and inferred information to identify potential flag-hopping or historical changes in vessel identity.\n", + "4. **Assess authorizations** - Cross-check whether vessels have publicly available fishing authorizations and consider external official sources for further verification.\n", + "5. **Generate an analysis report** - Provide enforcement authorities with a structured report highlighting vessel activity, identity records, and any notable discrepancies for further investigation." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez.ipynb b/docs/source/workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez.ipynb new file mode 100644 index 0000000..0953cfe --- /dev/null +++ b/docs/source/workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez.ipynb @@ -0,0 +1,2173 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "1b582ffc-7477-46c3-b5bf-2caf9d028bf2", + "metadata": {}, + "source": [ + "\"Open" + ] + }, + { + "cell_type": "markdown", + "id": "87eddf13-ac9c-45b0-ae10-24eb1620e07e", + "metadata": {}, + "source": [ + "# Analyze apparent fishing effort in Argentinian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "d79f0ab4-ab4d-4098-82b0-b6a5c772e101", + "metadata": {}, + "source": [ + "This guide provides detailed instructions to on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to **Analyze apparent fishing effort in [Argentinian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8466) region and monitor industrial trawlers** using **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)**, **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)**, and **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)**." + ] + }, + { + "cell_type": "markdown", + "id": "7ac25ecf-ffd7-40d7-9ea0-a6514c9fcd85", + "metadata": {}, + "source": [ + "**Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), 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." + ] + }, + { + "cell_type": "markdown", + "id": "71018cec-10c0-4619-9a7d-838a9f43cb15", + "metadata": {}, + "source": [ + "## Prerequisites" + ] + }, + { + "cell_type": "markdown", + "id": "996ca24b-99e4-4546-805b-697e4c2eb321", + "metadata": {}, + "source": [ + "Before using the `gfw-api-python-client`, ensure it is installed (see the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html) guide) and that you have obtained an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)." + ] + }, + { + "cell_type": "markdown", + "id": "6be16f6f-19fc-4d19-a0ed-ba370c844fa6", + "metadata": {}, + "source": [ + "## Installation" + ] + }, + { + "cell_type": "markdown", + "id": "af48cf4e-e24c-47aa-a2c5-64cf87be9c33", + "metadata": {}, + "source": [ + "The `gfw-api-python-client` can be easily installed using pip:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "88c09924-87d2-4c86-ad60-aed623416193", + "metadata": {}, + "outputs": [], + "source": [ + "# %pip install gfw-api-python-client" + ] + }, + { + "cell_type": "markdown", + "id": "eafaa9d1-2143-452c-813c-75b21fd2198c", + "metadata": {}, + "source": [ + "## Usage" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "cc98323c-c9e4-401c-8f26-f551968c003a", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "import datetime\n", + "import pandas as pd\n", + "import gfwapiclient as gfw" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "047ff069-3c87-47fe-bb4a-acb920df2137", + "metadata": {}, + "outputs": [], + "source": [ + "try:\n", + " from google.colab import userdata\n", + "\n", + " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", + "except Exception as exc:\n", + " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", + "\n", + "access_token = access_token or \"\"" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "708e137f-6aa0-461e-b1af-33512a2093fc", + "metadata": {}, + "outputs": [], + "source": [ + "gfw_client = gfw.Client(\n", + " access_token=access_token,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b08a0e2c-3b9d-4c5e-b3a0-a5663fa32637", + "metadata": {}, + "source": [ + "## Introduction" + ] + }, + { + "cell_type": "markdown", + "id": "62fe47aa-ed77-4815-b08d-8c96f2480b04", + "metadata": {}, + "source": [ + "**Use Case: A Fisheries Enforcement Officer Monitoring Industrial Trawlers**" + ] + }, + { + "cell_type": "markdown", + "id": "5109f67f-aaae-4a7d-9a15-4db740542694", + "metadata": {}, + "source": [ + "Maria, a fisheries enforcement officer in Argentina, monitors industrial trawlers operating within **[Argentinian Exclusive Economic Zone (EEZ)](https://www.marineregions.org/gazetteer.php?p=details&id=8466)**. His goal is to:\n", + "\n", + "1. Analyzing apparent fishing effort for **trawlers** operating in Argentinian EEZ.\n", + "2. Identifying vessels involved in **apparent trawling activity** and determining their reported **flag states**.\n", + "3. Checking vessel history, including **potential transshipment** and **port visits**.\n", + "4. Generating reports to support fisheries enforcement decisions." + ] + }, + { + "cell_type": "markdown", + "id": "b16b1b52-6b68-494a-9d76-ca7a7ab485a0", + "metadata": {}, + "source": [ + "**APIs Used:**\n", + "️\n", + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** – Retrieve **apparent fishing effort** data for trawlers.\n", + "2. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** – Group vessels by ID that are involved in **trawling activity**.\n", + "3. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** – Retrieve **vessel identity** & **ownership** details.\n", + "4. **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)** – Fetch **port visits** & **potential transshipment** history. " + ] + }, + { + "cell_type": "markdown", + "id": "c93924be-f36e-4f6c-830f-4d06c03d08f7", + "metadata": {}, + "source": [ + "**Important:** In order to avoid any misinterpretation of **GFW data**, please refer to our official **data caveats** documentations:\n", + "- [Apparent fishing effort](https://globalfishingwatch.org/dataset-and-code-fishing-effort/) \n", + "- [Exclusive economic zone boundaries definition](https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition)\n", + "- [Vessel ID](https://globalfishingwatch.org/our-apis/documentation#vessel-id)\n", + "- [Vessel API - Vessel identity information](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)" + ] + }, + { + "cell_type": "markdown", + "id": "01169672-36d5-4b2b-969d-471070d75f8c", + "metadata": {}, + "source": [ + "**Important Caveats:**\n", + "\n", + "1. The [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api) only supports **one active report per user at a time**.\n", + "2. **Sending multiple requests simultaneously** results in a **429 Too Many Requests** error.\n", + "3. If a report takes over **100 seconds** to generate, it may return a **524 Gateway Timeout** error." + ] + }, + { + "cell_type": "markdown", + "id": "2c1e1858-c328-4719-8f10-40ae5b43ecb0", + "metadata": {}, + "source": [ + "## Step 0: Identify the Region of Interest (ROI) - Argentinian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "88789a27-1e15-44af-ba81-7d07ded02e4b", + "metadata": {}, + "source": [ + "Before making API requests, Maria must specify the geographic area for analysis using a **Region ID**:" + ] + }, + { + "cell_type": "markdown", + "id": "75a985b1-3803-48d9-b2f3-f12b29bd29e7", + "metadata": {}, + "source": [ + "**Options to Define the Region:**\n", + "\n", + "1. **Using Region ID** - Each EEZ has a unique ID in the **[public-eez-areas](https://globalfishingwatch.org/our-apis/documentation#regions)** dataset.\n", + "2. **Custom Geometries** - Users can define a custom area using GeoJSON.\n", + " \n", + "For **[Argentinian EEZ, the region ID is 8466](https://www.marineregions.org/gazetteer.php?p=details&id=8466)** (public-eez-areas dataset)." + ] + }, + { + "cell_type": "markdown", + "id": "35a0691d-b747-48e6-8b02-5c2f54a5d536", + "metadata": {}, + "source": [ + "## Step 1: Retrieve Apparent Fishing Effort in Argentinian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "d57cd039-a667-44f7-b785-8d0e50530333", + "metadata": {}, + "source": [ + "Maria **first queries** the **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** to get **apparent fishing effort for all vessels**, grouping them by **gear type** in **[Argentinian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8466)**. Please [learn more about apparent fishing effort here](https://globalfishingwatch.org/our-apis/documentation#ais-apparent-fishing-effort) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort)." + ] + }, + { + "cell_type": "markdown", + "id": "6229af14-613a-4809-96f5-9cb3d6bd3461", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **[Region ID](https://globalfishingwatch.org/our-apis/documentation#regions)** - 8466 Argentinian EEZ\n", + "2. **[Date Range](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Last 6 Months\n", + "3. **[Grouped By](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Gear Type" + ] + }, + { + "cell_type": "markdown", + "id": "b945aa10-40c3-490a-84e7-89092badd783", + "metadata": {}, + "source": [ + "**Why This Step?**\n", + "\n", + "- Identifies which gear types (e.g., `trawlers`, `squid jiggers` etc.) are most active in the Argentinian EEZ.\n", + "- Establishes baseline fishing activity trends before narrowing the search to specific vessels." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "62b9b9e5-4170-40d0-9aef-7579beb89bc0", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", + " spatial_resolution=\"HIGH\",\n", + " group_by=\"GEARTYPE\",\n", + " temporal_resolution=\"MONTHLY\",\n", + " start_date=\"2024-08-01\",\n", + " end_date=\"2025-01-31\",\n", + " spatial_aggregation=True,\n", + " region={\n", + " \"dataset\": \"public-eez-areas\",\n", + " \"id\": \"8466\",\n", + " },\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "4d6190fc-a8fa-4d59-914e-ebae41943381", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_df = step_1_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "d98ca51f-bb46-4edc-9a61-3e26c56bbcc8", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 40 entries, 0 to 39\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 40 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 0 non-null object \n", + " 3 gear_type 40 non-null object \n", + " 4 hours 40 non-null float64\n", + " 5 vessel_ids 40 non-null int64 \n", + " 6 vessel_id 0 non-null object \n", + " 7 vessel_type 0 non-null object \n", + " 8 entry_timestamp 0 non-null object \n", + " 9 exit_timestamp 0 non-null object \n", + " 10 first_transmission_date 0 non-null object \n", + " 11 last_transmission_date 0 non-null object \n", + " 12 imo 0 non-null object \n", + " 13 mmsi 0 non-null object \n", + " 14 call_sign 0 non-null object \n", + " 15 dataset 0 non-null object \n", + " 16 report_dataset 40 non-null object \n", + " 17 ship_name 0 non-null object \n", + " 18 lat 0 non-null object \n", + " 19 lon 0 non-null object \n", + "dtypes: float64(1), int64(1), object(18)\n", + "memory usage: 6.4+ KB\n" + ] + } + ], + "source": [ + "step_1_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "ce844c77-6cf0-4648-bdfb-3a72589c0785", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
gear_typehoursvessel_ids
0inconclusive215.6238892
1set_longlines17.9258331
2inconclusive98.1558332
3other_purse_seines57.3775001
4set_longlines153.9602783
\n", + "
" + ], + "text/plain": [ + " gear_type hours vessel_ids\n", + "0 inconclusive 215.623889 2\n", + "1 set_longlines 17.925833 1\n", + "2 inconclusive 98.155833 2\n", + "3 other_purse_seines 57.377500 1\n", + "4 set_longlines 153.960278 3" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_report_df[[\"gear_type\", \"hours\", \"vessel_ids\"]].head()" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "45319c2a-e82e-4a9a-8a2d-2ea6d9cdada4", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_agg_report_df = (\n", + " step_1_report_df.groupby([\"gear_type\"], as_index=False)\n", + " .agg(hours=(\"hours\", \"sum\"), vessel_ids=(\"vessel_ids\", \"sum\"))\n", + " .sort_values(by=\"hours\", ascending=False)\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "121465c6-65ef-4efa-9d8a-4a0a136564bd", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
gear_typehoursvessel_ids
8trawlers240642.4144441315
1fishing16023.20138994
7squid_jigger6124.06222244
2fixed_gear1948.32555616
3inconclusive1072.35138914
\n", + "
" + ], + "text/plain": [ + " gear_type hours vessel_ids\n", + "8 trawlers 240642.414444 1315\n", + "1 fishing 16023.201389 94\n", + "7 squid_jigger 6124.062222 44\n", + "2 fixed_gear 1948.325556 16\n", + "3 inconclusive 1072.351389 14" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_agg_report_df.head()" + ] + }, + { + "cell_type": "markdown", + "id": "449828f2-dda7-422c-8cfb-770ced828ca6", + "metadata": {}, + "source": [ + "### What We have Learned from Step 1" + ] + }, + { + "cell_type": "markdown", + "id": "e83e24d9-edb1-45d3-af4a-fa60b155ecab", + "metadata": {}, + "source": [ + "- Multiple **gear types** were potentially detected in Argentinian EEZ.\n", + "- `Trawlers` appear to be operating, but further **vessel-level investigation** is needed." + ] + }, + { + "cell_type": "markdown", + "id": "6fe5edf3-8e96-4147-8c59-a6bc8982662d", + "metadata": {}, + "source": [ + "## Step 2: Retrieve Vessel IDs for Trawlers" + ] + }, + { + "cell_type": "markdown", + "id": "4bede3c0-3d01-4661-8b88-467244417d20", + "metadata": {}, + "source": [ + "Maria refines her **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** request to group by **vessel ID**, and filtering only for **trawlers** in **[Argentinian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8466)**. Please [learn more about apparent fishing effort here](https://globalfishingwatch.org/our-apis/documentation#ais-apparent-fishing-effort) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort)." + ] + }, + { + "cell_type": "markdown", + "id": "2e2e42d9-1b9e-4115-b601-72d0e86ab91d", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **[Region ID](https://globalfishingwatch.org/our-apis/documentation#regions)** - [8466 Argentinian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8466)\n", + "2. **[Date Range](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Last 6 Months\n", + "3. **[Grouped By](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Vessel ID\n", + "4. **[Gear Type](https://globalfishingwatch.org/our-apis/documentation#gear-types-supported)** - Trawlers " + ] + }, + { + "cell_type": "markdown", + "id": "849f6157-fa79-456f-8974-d294c77a0729", + "metadata": {}, + "source": [ + "**Why Use group-by=VESSEL_ID?**\n", + "\n", + "Grouping by **VESSEL_ID** allows **individual vessel identification** in the response. This is crucial for **tracking vessel activity** and, more importantly, linking each detected vessel to the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** in the next step. By structuring the query this way, we can fetch vessel details such as **flag, name, and ownership records** in **Step 3 below**.\n" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "db35d1b2-ba32-4a58-97f3-17059b3de164", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", + " spatial_resolution=\"HIGH\",\n", + " group_by=\"VESSEL_ID\",\n", + " temporal_resolution=\"ENTIRE\",\n", + " filters=[\"geartype in ('trawlers')\"],\n", + " start_date=\"2024-08-01\",\n", + " end_date=\"2025-01-31\",\n", + " spatial_aggregation=True,\n", + " region={\n", + " \"dataset\": \"public-eez-areas\",\n", + " \"id\": \"8466\",\n", + " },\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "301f888e-3b7e-4946-a7aa-496e05b53cbd", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_report_df = step_2_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "866f84fb-50c4-47e2-95fa-43fbc06d17cd", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 385 entries, 0 to 384\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 385 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 385 non-null object \n", + " 3 gear_type 385 non-null object \n", + " 4 hours 385 non-null float64 \n", + " 5 vessel_ids 0 non-null object \n", + " 6 vessel_id 385 non-null object \n", + " 7 vessel_type 385 non-null object \n", + " 8 entry_timestamp 385 non-null datetime64[ns, UTC]\n", + " 9 exit_timestamp 385 non-null datetime64[ns, UTC]\n", + " 10 first_transmission_date 385 non-null datetime64[ns, UTC]\n", + " 11 last_transmission_date 385 non-null datetime64[ns, UTC]\n", + " 12 imo 385 non-null object \n", + " 13 mmsi 385 non-null object \n", + " 14 call_sign 385 non-null object \n", + " 15 dataset 385 non-null object \n", + " 16 report_dataset 385 non-null object \n", + " 17 ship_name 385 non-null object \n", + " 18 lat 0 non-null object \n", + " 19 lon 0 non-null object \n", + "dtypes: datetime64[ns, UTC](4), float64(1), object(15)\n", + "memory usage: 60.3+ KB\n" + ] + } + ], + "source": [ + "step_2_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "82a786a1-c437-430e-aeb5-f61d02a5f900", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typehoursmmsiship_name
0URYTRAWLERS10.023056770576463KALATXORI
1ARGTRAWLERS326.160833701079000ENTRENA UNO
2ARGTRAWLERS714.842500701000882FELIX AUGUSTO
3ARGTRAWLERS641.522222701000932ANTONIO ALVAREZ
4ARGTRAWLERS295.007500701000820CORAJE
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours mmsi ship_name\n", + "0 URY TRAWLERS 10.023056 770576463 KALATXORI\n", + "1 ARG TRAWLERS 326.160833 701079000 ENTRENA UNO\n", + "2 ARG TRAWLERS 714.842500 701000882 FELIX AUGUSTO\n", + "3 ARG TRAWLERS 641.522222 701000932 ANTONIO ALVAREZ\n", + "4 ARG TRAWLERS 295.007500 701000820 CORAJE" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_report_df[[\"flag\", \"gear_type\", \"hours\", \"mmsi\", \"ship_name\"]].head()" + ] + }, + { + "cell_type": "markdown", + "id": "630d95dd-8f82-407f-b223-f55e981e3593", + "metadata": {}, + "source": [ + "### Explore Vessels Potentially Engaged in Trawling Activity in the Argentinian EEZ" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "984052a3-3920-4fce-8894-4b67af4a8a69", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_agg_report_df = (\n", + " step_2_report_df.groupby([\"flag\", \"gear_type\", \"mmsi\", \"ship_name\"], as_index=False)\n", + " .agg(hours=(\"hours\", \"sum\"))\n", + " .sort_values(by=\"hours\", ascending=False)\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "83e4dafb-4491-40c9-9f4d-f4cc1e2b7766", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typemmsiship_namehours
297ARGTRAWLERS701024000ATLANTIC SURF III3151.855278
247ARGTRAWLERS701006605CAPESANTE2270.097500
22ARGTRAWLERS701000577MISS TIDE2244.895833
296ARGTRAWLERS701023000CAROLINA P2065.586944
301ARGTRAWLERS701037000DON PEDRO1807.146111
\n", + "
" + ], + "text/plain": [ + " flag gear_type mmsi ship_name hours\n", + "297 ARG TRAWLERS 701024000 ATLANTIC SURF III 3151.855278\n", + "247 ARG TRAWLERS 701006605 CAPESANTE 2270.097500\n", + "22 ARG TRAWLERS 701000577 MISS TIDE 2244.895833\n", + "296 ARG TRAWLERS 701023000 CAROLINA P 2065.586944\n", + "301 ARG TRAWLERS 701037000 DON PEDRO 1807.146111" + ] + }, + "execution_count": 16, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_agg_report_df.head()" + ] + }, + { + "cell_type": "markdown", + "id": "3f948958-ebce-4478-8b17-d6143c38956b", + "metadata": {}, + "source": [ + "### What We have Learned from Step 2" + ] + }, + { + "cell_type": "markdown", + "id": "d4fb7cba-a577-45fe-88fa-8e5001bb9869", + "metadata": {}, + "source": [ + "- There are vessels appear to have been engaged in potential trawling activity in Argentinian EEZ over the past 6 months i.e.,:\n", + " - `ATLANTIC SURF III (mmsi: 701024000, flag: ARG)`\n", + " - `CAPESANTE (mmsi: 701006605, flag: ARG)`\n", + "- We will retrieve these vessels' `ownership`, `flag history`, and `authorizations` in **Step 3 to validate** them." + ] + }, + { + "cell_type": "markdown", + "id": "80289282-d160-4901-9bf8-a7996785c898", + "metadata": {}, + "source": [ + "## Step 3: Retrieve Vessel Details Using the Vessels API" + ] + }, + { + "cell_type": "markdown", + "id": "dcbde755-0e9c-48d9-babe-aaee3179b88d", + "metadata": {}, + "source": [ + "Maria queries the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** to **get detailed vessel identity and ownership records**. Please [learn more about Vessels API here](https://globalfishingwatch.org/our-apis/documentation#vessels-api) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)." + ] + }, + { + "cell_type": "markdown", + "id": "ba645e15-f111-48f3-96a4-7e091f27669e", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **Vessel IDs** from [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api), **Step 2 above**.\n", + "2. **[Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset)** - `public-global-vessel-identity:latest`.\n", + "3. **[Includes](https://globalfishingwatch.org/our-apis/documentation#get-vessels-by-ids-url-parameters)** - `POTENTIAL_RELATED_SELF_REPORTED_INFO`." + ] + }, + { + "cell_type": "markdown", + "id": "42a309da-6a56-46a0-aa86-2a148d21d855", + "metadata": {}, + "source": [ + "**Note:** Vessels may change identifiers over time, such as their `Maritime Mobile Service Identity (MMSI)`,` International Maritime Organization (IMO) number)`, `call sign`, or even their `name`. These changes can occur due to `re-registration`, `changes in ownership`, or other `operational reasons` within the `AIS transponder`. Parameter (`includes = POTENTIAL_RELATED_SELF_REPORTED_INFO`) helps group all **vessel ids** that are **potentially related** as part of the **same physical vessel** based on publicly available registry information." + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "24e8452f-7848-4c88-89db-66e4bf182cd1", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_vessel_mmsis = list(step_2_agg_report_df[\"mmsi\"].head(n=2))" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "f25ceec0-3188-4584-bb95-f76c9e0ac578", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['701024000', '701006605']" + ] + }, + "execution_count": 18, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_vessel_mmsis" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "446b506a-a19f-49cd-9110-ed8b9103af8b", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_vessel_ids = list(\n", + " step_2_report_df[step_2_report_df[\"mmsi\"].isin(step_2_vessel_mmsis)][\n", + " \"vessel_id\"\n", + " ].unique()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "6233b1eb-ed4b-4ba9-bce8-faa1ee027dcc", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['de8a03acd-dc6c-8e08-2867-24e55ffc0017',\n", + " '8e930bac5-594b-aa3f-081d-d12668819e1f']" + ] + }, + "execution_count": 20, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_vessel_ids" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "428889bd-4761-4301-b21e-fbc37eba5622", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_vessels_result = await gfw_client.vessels.get_vessels_by_ids(\n", + " ids=step_2_vessel_ids,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "c64d68dc-b952-412f-827c-df5236c98bd7", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_vessels_df = step_3_vessels_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "757e6c3c-d0df-4b8f-839d-1e31518d42d7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 2 entries, 0 to 1\n", + "Data columns (total 7 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 dataset 2 non-null object\n", + " 1 registry_info_total_records 2 non-null int64 \n", + " 2 registry_info 2 non-null object\n", + " 3 registry_owners 2 non-null object\n", + " 4 registry_public_authorizations 2 non-null object\n", + " 5 combined_sources_info 2 non-null object\n", + " 6 self_reported_info 2 non-null object\n", + "dtypes: int64(1), object(6)\n", + "memory usage: 244.0+ bytes\n" + ] + } + ], + "source": [ + "step_3_vessels_df.info()" + ] + }, + { + "cell_type": "markdown", + "id": "c2d30f1a-352b-42cb-8ee8-acd67f16103f", + "metadata": {}, + "source": [ + "**Understanding Vessel Details Response Data**\n", + "\n", + "- **registryInfoTotalRecords** – This represents the **number of registry records** found for the vessels.\n", + "- **registryInfo** – Contains **public registry data**. This data is sourced from official **vessel registries**.\n", + "- **registryOwners** – Lists the **registered owners** of the vessel based on public sources.\n", + "- **registryPublicAuthorizations** – Represents known **fishing authorizations** from public sources. Users should verify against national registries and RFMO records for additional context.\n", + "- **combinedSourcesInfo** – Provides inferred data from multiple sources, including. This is not explicitly reported by vessels but determined through **GFW's classification methods**.\n", + "- **selfReportedInfo** – Contains **AIS self-reported** data, including `MMSI`, `ship name`, and `flag` as broadcast by the **vessel itself**. Self-reported data may not always align with registry data and should be cross-checked." + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "4767e025-e26e-4a61-8971-8f2cc90385cc", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
registry_inforegistry_ownersself_reported_info
0[{'id': '45502524c9a150e77869ee647423dba1', 's...[{'name': 'GLACIAR PESQUERA', 'flag': 'ARG', '...[{'id': '8e930bac5-594b-aa3f-081d-d12668819e1f...
1[{'id': '2d939efefd3f45788ed103ff0723f564', 's...[{'name': 'CLEARWATER SEAFOODS', 'flag': 'CAN'...[{'id': 'de8a03acd-dc6c-8e08-2867-24e55ffc0017...
\n", + "
" + ], + "text/plain": [ + " registry_info \\\n", + "0 [{'id': '45502524c9a150e77869ee647423dba1', 's... \n", + "1 [{'id': '2d939efefd3f45788ed103ff0723f564', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'GLACIAR PESQUERA', 'flag': 'ARG', '... \n", + "1 [{'name': 'CLEARWATER SEAFOODS', 'flag': 'CAN'... \n", + "\n", + " self_reported_info \n", + "0 [{'id': '8e930bac5-594b-aa3f-081d-d12668819e1f... \n", + "1 [{'id': 'de8a03acd-dc6c-8e08-2867-24e55ffc0017... " + ] + }, + "execution_count": 24, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_vessels_df[[\"registry_info\", \"registry_owners\", \"self_reported_info\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "46760bde-049d-433c-817d-ae63b1c58924", + "metadata": {}, + "source": [ + "### Explore Vessels Registry Info" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "7efdc6d6-52d8-40bb-9537-e09f242fdb25", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_registry_info_df = pd.json_normalize(\n", + " step_3_vessels_df[\"registry_info\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "27ab60a9-6496-4406-9ae4-57a7aa97f6fa", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namegear_typessource_code
0701024000ARGATLANTIC SURF IIIATLANTICSURF3[TRAWLERS][IMO, TMT_OTHER_OFFICIAL]
1701006605ARGCAPESANTECAPESANTE[TRAWLERS][GFW-REVIEW, IMO, RESEARCH-PAPER, TMT_OTHER_OF...
2316003980CANATLANTICLEADERATLANTICLEADER[TRAWLERS][IMO, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name gear_types \\\n", + "0 701024000 ARG ATLANTIC SURF III ATLANTICSURF3 [TRAWLERS] \n", + "1 701006605 ARG CAPESANTE CAPESANTE [TRAWLERS] \n", + "2 316003980 CAN ATLANTICLEADER ATLANTICLEADER [TRAWLERS] \n", + "\n", + " source_code \n", + "0 [IMO, TMT_OTHER_OFFICIAL] \n", + "1 [GFW-REVIEW, IMO, RESEARCH-PAPER, TMT_OTHER_OF... \n", + "2 [IMO, TMT_OTHER_OFFICIAL] " + ] + }, + "execution_count": 26, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_registry_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"gear_types\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "5787e4ee-69e0-4769-ba05-9a57254c7289", + "metadata": {}, + "source": [ + "### Explore Registry Owners" + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "afe07c2a-81cb-45b3-9e86-c23b4ef67fe9", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_registry_owners_df = pd.json_normalize(\n", + " step_3_vessels_df[\"registry_owners\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "df7e0b65-0ab0-4722-aaec-3d11c7674b8f", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagnamesource_code
0701024000ARGGLACIAR PESQUERA[TMT_OTHER_OFFICIAL]
1701006605CANCLEARWATER SEAFOODS[RESEARCH-PAPER]
2316003980CANCS MANPAR[TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag name source_code\n", + "0 701024000 ARG GLACIAR PESQUERA [TMT_OTHER_OFFICIAL]\n", + "1 701006605 CAN CLEARWATER SEAFOODS [RESEARCH-PAPER]\n", + "2 316003980 CAN CS MANPAR [TMT_OTHER_OFFICIAL]" + ] + }, + "execution_count": 28, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_registry_owners_df[[\"ssvid\", \"flag\", \"name\", \"source_code\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "7a22580f-7c7a-4181-9a80-e37687cc0471", + "metadata": {}, + "source": [ + "### Explore Vessels Self Reported Info" + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "c2fa4bdd-1b51-4b37-abf5-aa18a1cab3e5", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_self_reported_info_df = pd.json_normalize(\n", + " step_3_vessels_df[\"self_reported_info\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "d1b559c7-4587-4019-a843-181017dd3f07", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namesource_code
0701024000ARGATLANTIC SURF IIIATLANTICSURF3[AIS]
1701006605ARGCAPESANTECAPESANTE[AIS]
2316003980CANATLANTIC LEADERATLANTICLEADER[AIS]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name source_code\n", + "0 701024000 ARG ATLANTIC SURF III ATLANTICSURF3 [AIS]\n", + "1 701006605 ARG CAPESANTE CAPESANTE [AIS]\n", + "2 316003980 CAN ATLANTIC LEADER ATLANTICLEADER [AIS]" + ] + }, + "execution_count": 30, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_self_reported_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "6a6bcbcd-49a8-4575-9003-d8495deeb2d3", + "metadata": {}, + "source": [ + "### What We have Learned from Step 3" + ] + }, + { + "cell_type": "markdown", + "id": "da9c80ea-94d7-4945-8e90-9f5ec4bad8f1", + "metadata": {}, + "source": [ + "- **Vessel Identity:**\n", + " - `ATLANTIC SURF III (mmsi: 701024000, flag: ARG)`- appears to be registered under Argentina (ARG)\n", + " - `CAPESANTE (mmsi: 701006605, flag: ARG)` - appears to be registered under Argentina (ARG)\n", + "- **Ownership & Historical Changes:**\n", + " - `ATLANTIC SURF III (mmsi: 701024000, flag: ARG)` - **GLACIAR PESQUERA** appears to be listed as the registered owner.\n", + " - `CAPESANTE (mmsi: 701006605, flag: ARG)`- **CLEARWATER SEAFOODS** appears to be listed as the registered owner." + ] + }, + { + "cell_type": "markdown", + "id": "4803ae37-3f96-40dc-8db8-690b51710735", + "metadata": {}, + "source": [ + "## Step 4: Detect Potential Port Visits, Encounters, or Fishing Events" + ] + }, + { + "cell_type": "markdown", + "id": "058cc09a-64dc-4913-a90c-cadc7d38439a", + "metadata": {}, + "source": [ + "Now Maria checks `port visits`, `encounters`, and `fishing events` using the **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)**, which allows **monitoring of vessel activities** such as `potential transshipments`, `unauthorized port entries`, or `fishing activity patterns`." + ] + }, + { + "cell_type": "markdown", + "id": "c8ee8f1c-7e5e-487f-ba45-7f7f609ba389", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **Vessel ID** from 4Wings API\n", + "2. **[Event Types](https://globalfishingwatch.org/our-apis/documentation#events-post-body-parameters)** - Port visits, encounters (potential transshipment), and fishing events.\n", + "3. **Time Range** - Last 6 months.\n", + "4. **[Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset)**:\n", + " - `public-global-port-visits-events::latest` (Port Visits)\n", + " - `public-global-encounters-events:latest` (Encounters between vessels)\n", + " - `public-global-fishing-events:latest` (Fishing activity)\n", + "5. **[Encounter Types](https://globalfishingwatch.org/our-apis/documentation#events-post-body-parameters)** - CARRIER-FISHING" + ] + }, + { + "cell_type": "code", + "execution_count": 31, + "id": "87c3b592-e431-457c-a5f4-5ce07711d52f", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_events_result = await gfw_client.events.get_all_events(\n", + " datasets=[\n", + " \"public-global-encounters-events:latest\",\n", + " \"public-global-fishing-events:latest\",\n", + " \"public-global-port-visits-events:latest\",\n", + " ],\n", + " vessels=step_2_vessel_ids,\n", + " types=[\"ENCOUNTER\", \"FISHING\", \"PORT_VISIT\"],\n", + " start_date=\"2024-08-01\",\n", + " end_date=\"2025-01-31\",\n", + " encounter_types=[\"CARRIER-FISHING\"],\n", + " sort=\"-start\",\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 32, + "id": "64cb0776-7f0d-481e-be98-da00b448c720", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_events_df = step_4_events_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "id": "4c82d647-3870-4a54-979b-7f586575e5c1", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 359 entries, 0 to 358\n", + "Data columns (total 14 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 start 359 non-null datetime64[ns, UTC]\n", + " 1 end 359 non-null datetime64[ns, UTC]\n", + " 2 id 359 non-null object \n", + " 3 type 359 non-null object \n", + " 4 position 359 non-null object \n", + " 5 regions 359 non-null object \n", + " 6 bounding_box 359 non-null object \n", + " 7 distances 359 non-null object \n", + " 8 vessel 359 non-null object \n", + " 9 encounter 0 non-null object \n", + " 10 fishing 351 non-null object \n", + " 11 gap 0 non-null object \n", + " 12 loitering 0 non-null object \n", + " 13 port_visit 8 non-null object \n", + "dtypes: datetime64[ns, UTC](2), object(12)\n", + "memory usage: 39.4+ KB\n" + ] + } + ], + "source": [ + "step_4_events_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 34, + "id": "17d89920-cda2-497d-9797-1e05a84a0daa", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "type\n", + "fishing 351\n", + "port_visit 8\n", + "Name: count, dtype: int64" + ] + }, + "execution_count": 34, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_events_df[\"type\"].value_counts()" + ] + }, + { + "cell_type": "markdown", + "id": "1b472de1-8fef-41a1-a76c-057406d86ee1", + "metadata": {}, + "source": [ + "### Explore Apparent Fishing Events" + ] + }, + { + "cell_type": "code", + "execution_count": 35, + "id": "4d360bc4-9762-4ae6-b5b1-1b937e2d2ed0", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_fishing_events_df = step_4_events_df[step_4_events_df[\"fishing\"].notna()]" + ] + }, + { + "cell_type": "code", + "execution_count": 36, + "id": "18ff38d6-9442-4742-9dc9-accfb1299e43", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_fishing_df = pd.concat(\n", + " [\n", + " pd.json_normalize(step_4_fishing_events_df[\"vessel\"], sep=\"_\"),\n", + " pd.json_normalize(step_4_fishing_events_df[\"fishing\"], sep=\"_\"),\n", + " ],\n", + " axis=1,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "id": "fc6ebae0-eba2-4a8a-892c-6dfc38822bd7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 351 entries, 0 to 350\n", + "Data columns (total 12 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 351 non-null object \n", + " 1 name 351 non-null object \n", + " 2 ssvid 351 non-null object \n", + " 3 flag 351 non-null object \n", + " 4 type 351 non-null object \n", + " 5 public_authorizations 351 non-null object \n", + " 6 nextPort 0 non-null object \n", + " 7 total_distance_km 351 non-null float64\n", + " 8 average_speed_knots 351 non-null float64\n", + " 9 average_duration_hours 0 non-null object \n", + " 10 potential_risk 351 non-null bool \n", + " 11 vessel_public_authorization_status 351 non-null object \n", + "dtypes: bool(1), float64(2), object(9)\n", + "memory usage: 30.6+ KB\n" + ] + } + ], + "source": [ + "step_4_fishing_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 38, + "id": "8799e988-56a2-41d5-b472-bc83064e1807", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
namessvidtotal_distance_kmaverage_speed_knots
0ATLANTIC SURF III701024000117.5454504.351747
1ATLANTIC SURF III70102400010.4088513.791667
2ATLANTIC SURF III70102400061.3669114.448980
3ATLANTIC SURF III70102400092.1807044.485407
4ATLANTIC SURF III701024000974.7618714.051429
...............
346CAPESANTE70100660595.1280594.202542
347CAPESANTE701006605205.8262824.136848
348CAPESANTE701006605369.3366033.938255
349ATLANTIC SURF III701024000256.9088424.186333
350CAPESANTE701006605208.0719853.971505
\n", + "

351 rows × 4 columns

\n", + "
" + ], + "text/plain": [ + " name ssvid total_distance_km average_speed_knots\n", + "0 ATLANTIC SURF III 701024000 117.545450 4.351747\n", + "1 ATLANTIC SURF III 701024000 10.408851 3.791667\n", + "2 ATLANTIC SURF III 701024000 61.366911 4.448980\n", + "3 ATLANTIC SURF III 701024000 92.180704 4.485407\n", + "4 ATLANTIC SURF III 701024000 974.761871 4.051429\n", + ".. ... ... ... ...\n", + "346 CAPESANTE 701006605 95.128059 4.202542\n", + "347 CAPESANTE 701006605 205.826282 4.136848\n", + "348 CAPESANTE 701006605 369.336603 3.938255\n", + "349 ATLANTIC SURF III 701024000 256.908842 4.186333\n", + "350 CAPESANTE 701006605 208.071985 3.971505\n", + "\n", + "[351 rows x 4 columns]" + ] + }, + "execution_count": 38, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_fishing_df[\n", + " [\n", + " \"name\",\n", + " \"ssvid\",\n", + " \"total_distance_km\",\n", + " \"average_speed_knots\",\n", + " ]\n", + "]" + ] + }, + { + "cell_type": "code", + "execution_count": 39, + "id": "3659c048-c8bf-463c-a6cb-fc29f818ed77", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "ssvid\n", + "701024000 245\n", + "701006605 106\n", + "Name: count, dtype: int64" + ] + }, + "execution_count": 39, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_fishing_df[\"ssvid\"].value_counts()" + ] + }, + { + "cell_type": "markdown", + "id": "5da05a04-947e-4f87-b61e-bad015796e5f", + "metadata": {}, + "source": [ + "### Explore Port Visit Events" + ] + }, + { + "cell_type": "code", + "execution_count": 40, + "id": "e806616b-6ed7-4c0c-9bf4-2b4a23de2046", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_port_visit_events_df = step_4_events_df[step_4_events_df[\"port_visit\"].notna()]" + ] + }, + { + "cell_type": "code", + "execution_count": 41, + "id": "58a68605-9432-43fe-b8eb-4d0393f95f60", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_port_visits_df = pd.concat(\n", + " [\n", + " pd.json_normalize(step_4_port_visit_events_df[\"vessel\"], sep=\"_\"),\n", + " pd.json_normalize(step_4_port_visit_events_df[\"port_visit\"], sep=\"_\"),\n", + " ],\n", + " axis=1,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 42, + "id": "685a746e-8091-4321-b851-79a5f3ca0f81", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 8 entries, 0 to 7\n", + "Data columns (total 37 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 8 non-null object \n", + " 1 name 8 non-null object \n", + " 2 ssvid 8 non-null object \n", + " 3 flag 8 non-null object \n", + " 4 type 8 non-null object \n", + " 5 public_authorizations 8 non-null object \n", + " 6 nextPort 0 non-null object \n", + " 7 visit_id 8 non-null object \n", + " 8 confidence 8 non-null object \n", + " 9 duration_hrs 8 non-null float64\n", + " 10 start_anchorage_anchorage_id 8 non-null object \n", + " 11 start_anchorage_at_dock 8 non-null bool \n", + " 12 start_anchorage_distance_from_shore_km 8 non-null float64\n", + " 13 start_anchorage_flag 8 non-null object \n", + " 14 start_anchorage_id 8 non-null object \n", + " 15 start_anchorage_lat 8 non-null float64\n", + " 16 start_anchorage_lon 8 non-null float64\n", + " 17 start_anchorage_name 8 non-null object \n", + " 18 start_anchorage_top_destination 8 non-null object \n", + " 19 intermediate_anchorage_anchorage_id 8 non-null object \n", + " 20 intermediate_anchorage_at_dock 8 non-null bool \n", + " 21 intermediate_anchorage_distance_from_shore_km 8 non-null float64\n", + " 22 intermediate_anchorage_flag 8 non-null object \n", + " 23 intermediate_anchorage_id 8 non-null object \n", + " 24 intermediate_anchorage_lat 8 non-null float64\n", + " 25 intermediate_anchorage_lon 8 non-null float64\n", + " 26 intermediate_anchorage_name 8 non-null object \n", + " 27 intermediate_anchorage_top_destination 8 non-null object \n", + " 28 end_anchorage_anchorage_id 8 non-null object \n", + " 29 end_anchorage_at_dock 8 non-null bool \n", + " 30 end_anchorage_distance_from_shore_km 8 non-null float64\n", + " 31 end_anchorage_flag 8 non-null object \n", + " 32 end_anchorage_id 8 non-null object \n", + " 33 end_anchorage_lat 8 non-null float64\n", + " 34 end_anchorage_lon 8 non-null float64\n", + " 35 end_anchorage_name 8 non-null object \n", + " 36 end_anchorage_top_destination 8 non-null object \n", + "dtypes: bool(3), float64(10), object(24)\n", + "memory usage: 2.3+ KB\n" + ] + } + ], + "source": [ + "step_4_port_visits_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 43, + "id": "0e77b956-f0f8-4fbd-8a49-0116e4401c12", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
namessvidconfidencestart_anchorage_nameintermediate_anchorage_nameend_anchorage_name
0ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
1CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
2CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
3ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
4CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
5ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
6CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
7ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
\n", + "
" + ], + "text/plain": [ + " name ssvid confidence start_anchorage_name \\\n", + "0 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "1 CAPESANTE 701006605 4 USHUAIA \n", + "2 CAPESANTE 701006605 4 USHUAIA \n", + "3 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "4 CAPESANTE 701006605 4 USHUAIA \n", + "5 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "6 CAPESANTE 701006605 4 USHUAIA \n", + "7 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "\n", + " intermediate_anchorage_name end_anchorage_name \n", + "0 MAR DEL PLATA MAR DEL PLATA \n", + "1 USHUAIA USHUAIA \n", + "2 USHUAIA USHUAIA \n", + "3 MAR DEL PLATA MAR DEL PLATA \n", + "4 USHUAIA USHUAIA \n", + "5 MAR DEL PLATA MAR DEL PLATA \n", + "6 USHUAIA USHUAIA \n", + "7 MAR DEL PLATA MAR DEL PLATA " + ] + }, + "execution_count": 43, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_port_visits_df[\n", + " [\n", + " \"name\",\n", + " \"ssvid\",\n", + " \"confidence\",\n", + " \"start_anchorage_name\",\n", + " \"intermediate_anchorage_name\",\n", + " \"end_anchorage_name\",\n", + " ]\n", + "]" + ] + }, + { + "cell_type": "code", + "execution_count": 44, + "id": "32ee1871-f1c7-4561-9384-5a681293e7e5", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "ssvid\n", + "701024000 4\n", + "701006605 4\n", + "Name: count, dtype: int64" + ] + }, + "execution_count": 44, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_port_visits_df[\"ssvid\"].value_counts()" + ] + }, + { + "cell_type": "markdown", + "id": "61d59d0c-8919-40c4-ac30-bb9ab35a4d53", + "metadata": {}, + "source": [ + "### What We have learned from step 4" + ] + }, + { + "cell_type": "markdown", + "id": "4771fe04-5984-4576-b774-a83f104d7194", + "metadata": {}, + "source": [ + "- **Apparent Fishing Events:**\n", + " - `ATLANTIC SURF III (mmsi: 701024000, flag: ARG)`- has been detected in multiple apparent fishing events during the analyzed timeframe (August 2024 – January 2025)\n", + " - `CAPESANTE (mmsi: 701006605, flag: ARG)` - has been detected in multiple apparent fishing events during the analyzed timeframe (August 2024 – January 2025)\n", + "- **Port Visit Events:**\n", + " - `ATLANTIC SURF III (mmsi: 701024000, flag: ARG)`- potentially made multiple port visits, including stops at `MAR DEL PLATA`\n", + " - `CAPESANTE (mmsi: 701006605, flag: ARG)` - potentially made multiple port visits, including stops at `USHUAIA`\n", + "- **ENCOUNTER Events:** No explicit **ENCOUNTER** events were returned in the response dataset. Check more details [here](https://globalfishingwatch.org/faqs/what-is-a-vessel-encounter/). You can read more about transshipment behavior from our [report](https://globalfishingwatch.org/wp-content/uploads/GlobalViewOfTransshipment_Aug2017.pdf) or [scientific publication](https://www.frontiersin.org/articles/10.3389/fmars.2018.00240/full)." + ] + }, + { + "cell_type": "markdown", + "id": "f0cf3958-fb92-49c0-ba2f-2cfe971bcbc5", + "metadata": {}, + "source": [ + "**Potential Considerations:**\n", + "\n", + "- The vessel's fishing activities appear near the EEZ boundary, requiring further assessment of compliance with national or RFMO regulations.\n", + "- The absence of matching public authorizations in the RFMO registry does not necessarily indicate illegality, but it suggests that authorities may need to verify through national databases or official sources." + ] + }, + { + "cell_type": "markdown", + "id": "8b951044-6905-4e38-9885-13a98cf3a7cf", + "metadata": {}, + "source": [ + "### Summary of API Flow" + ] + }, + { + "cell_type": "markdown", + "id": "c8f86731-be44-4b89-8abb-cf2f6693b4c9", + "metadata": {}, + "source": [ + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** - Retrieve apparent fishing effort for **trawlers** within Argentinian EEZ.\n", + "2. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** - Fetch **vessel identity**, **ownership history**, and **public authorizations**.\n", + "3. **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)** - Detect potential **port visits**, **encounters**, and **apparent fishing** events to analyze operational patterns.\n", + "4. **Assess potential risks** - Compare registry records, AIS data, and inferred vessel activity for enforcement follow-ups.\n", + "5. **Generate a report** - Provide a structured analysis for relevant authorities." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/source/workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez.ipynb b/docs/source/workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez.ipynb new file mode 100644 index 0000000..a894429 --- /dev/null +++ b/docs/source/workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez.ipynb @@ -0,0 +1,1996 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "1b582ffc-7477-46c3-b5bf-2caf9d028bf2", + "metadata": {}, + "source": [ + "\"Open" + ] + }, + { + "cell_type": "markdown", + "id": "87eddf13-ac9c-45b0-ae10-24eb1620e07e", + "metadata": {}, + "source": [ + "# Analyze a fleet in Ghanaian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "2006da5f-b6dc-491b-b64d-ad332e89e814", + "metadata": {}, + "source": [ + "This guide provides detailed instructions to on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to **Monitor a Fleet (a group of vessels) of Tuna Longliners in [Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400) region for Compliance** using **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)**, **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)**, and **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)**." + ] + }, + { + "cell_type": "markdown", + "id": "7ac25ecf-ffd7-40d7-9ea0-a6514c9fcd85", + "metadata": {}, + "source": [ + "**Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), 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." + ] + }, + { + "cell_type": "markdown", + "id": "71018cec-10c0-4619-9a7d-838a9f43cb15", + "metadata": {}, + "source": [ + "## Prerequisites" + ] + }, + { + "cell_type": "markdown", + "id": "996ca24b-99e4-4546-805b-697e4c2eb321", + "metadata": {}, + "source": [ + "Before using the `gfw-api-python-client`, ensure it is installed (see the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html) guide) and that you have obtained an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)." + ] + }, + { + "cell_type": "markdown", + "id": "6be16f6f-19fc-4d19-a0ed-ba370c844fa6", + "metadata": {}, + "source": [ + "## Installation" + ] + }, + { + "cell_type": "markdown", + "id": "af48cf4e-e24c-47aa-a2c5-64cf87be9c33", + "metadata": {}, + "source": [ + "The `gfw-api-python-client` can be easily installed using pip:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "88c09924-87d2-4c86-ad60-aed623416193", + "metadata": {}, + "outputs": [], + "source": [ + "# %pip install gfw-api-python-client" + ] + }, + { + "cell_type": "markdown", + "id": "b7a03d8d-8dec-4096-8395-d8cfc599db69", + "metadata": {}, + "source": [ + "## Usage" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "d93d57ae-0ec7-4d97-8fea-f679e89fc3b1", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "import datetime\n", + "import pandas as pd\n", + "import gfwapiclient as gfw" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "0b398f94-cd59-49c8-95a3-0ee46cf17e77", + "metadata": {}, + "outputs": [], + "source": [ + "try:\n", + " from google.colab import userdata\n", + "\n", + " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", + "except Exception as exc:\n", + " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", + "\n", + "access_token = access_token or \"\"" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "f5884635-6941-4f97-8b1a-5fd485a95bc4", + "metadata": {}, + "outputs": [], + "source": [ + "gfw_client = gfw.Client(\n", + " access_token=access_token,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b08a0e2c-3b9d-4c5e-b3a0-a5663fa32637", + "metadata": {}, + "source": [ + "## Introduction" + ] + }, + { + "cell_type": "markdown", + "id": "62fe47aa-ed77-4815-b08d-8c96f2480b04", + "metadata": {}, + "source": [ + "**Use Case: Monitoring a Fleet of Tuna Longliners for Compliance**" + ] + }, + { + "cell_type": "markdown", + "id": "5109f67f-aaae-4a7d-9a15-4db740542694", + "metadata": {}, + "source": [ + "Kwame is a fisheries compliance officer in Ghana, responsible for monitoring a fleet of tuna longliners operating within **[Ghanaian Exclusive Economic Zone (EEZ)](https://www.marineregions.org/gazetteer.php?p=details&id=8400)**. His goal is to:\n", + "\n", + "1. Track apparent fishing effort for **longliners** over the last 12 months.\n", + "2. Identify potential vessels in this fleet, their operational patterns, and their activity levels.\n", + "3. Retrieve vessel details, including **flag state**, **ownership history**, and **authorizations**.\n", + "4. Analyze events such as **port visits** and **encounters (potential transshipment)** activities." + ] + }, + { + "cell_type": "markdown", + "id": "b16b1b52-6b68-494a-9d76-ca7a7ab485a0", + "metadata": {}, + "source": [ + "**APIs Used:**\n", + "️\n", + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** – Retrieve apparent fishing effort grouped by vessel ID in Ghanaian EEZ.\n", + "2. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** – Get vessel identity, ownership, and compliance details.\n", + "3. **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)** – Identify port visits and potential transshipment activities for vessels in the fleet." + ] + }, + { + "cell_type": "markdown", + "id": "0ebc365c-2c5c-413e-80a5-36a4825f3032", + "metadata": {}, + "source": [ + "**Important:** In order to avoid any misinterpretation of **GFW data**, please refer to our official **data caveats** documentations:\n", + "- [Apparent fishing effort](https://globalfishingwatch.org/dataset-and-code-fishing-effort/) \n", + "- [Exclusive economic zone boundaries definition](https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition)\n", + "- [Vessel ID](https://globalfishingwatch.org/our-apis/documentation#vessel-id)\n", + "- [Vessel API - Vessel identity information](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)" + ] + }, + { + "cell_type": "markdown", + "id": "379460dd-ed9f-49ee-9c9b-e428ad5f4522", + "metadata": {}, + "source": [ + "**Important Caveats:**\n", + "\n", + "1. The [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api) only supports **one active report per user at a time**.\n", + "2. **Sending multiple requests simultaneously** results in a **429 Too Many Requests** error.\n", + "3. If a report takes over **100 seconds** to generate, it may return a **524 Gateway Timeout** error." + ] + }, + { + "cell_type": "markdown", + "id": "2c1e1858-c328-4719-8f10-40ae5b43ecb0", + "metadata": {}, + "source": [ + "## Step 0: Identify the Region of Interest (ROI) - Ghanaian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "64b1bbab-9780-4821-ae4f-ccff0a4bb100", + "metadata": {}, + "source": [ + "Before making API requests, Kwame must specify the geographic area for analysis using a **Region ID**:" + ] + }, + { + "cell_type": "markdown", + "id": "362137ce-97eb-4965-a649-a038bd5d167f", + "metadata": {}, + "source": [ + "**Options to Define the Region:**\n", + "\n", + "1. **Using Region ID** - Each EEZ has a unique ID in the **[public-eez-areas](https://globalfishingwatch.org/our-apis/documentation#regions)** dataset.\n", + "2. **Custom Geometries** - Users can define a custom area using GeoJSON.\n", + " \n", + "For **[Ghanaian EEZ, the region ID is 8400](https://www.marineregions.org/gazetteer.php?p=details&id=8400)** (public-eez-areas dataset)." + ] + }, + { + "cell_type": "markdown", + "id": "6fe5edf3-8e96-4147-8c59-a6bc8982662d", + "metadata": {}, + "source": [ + "## Step 1: Retrieve Fishing Effort in Ghanaian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "eba86e0d-90f7-4494-857c-261f9b734dc0", + "metadata": {}, + "source": [ + "Kwame **first queries** the **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** to get **fishing effort for all vessels**, grouping them by **gear type** in **[Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400)**. Please [learn more about apparent fishing effort here](https://globalfishingwatch.org/our-apis/documentation#ais-apparent-fishing-effort) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort)." + ] + }, + { + "cell_type": "markdown", + "id": "8816740a-4871-49e8-862c-049e0a3d02d3", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **[Region ID](https://globalfishingwatch.org/our-apis/documentation#regions)** - 8400 Ghanaian EEZ\n", + "2. **[Date Range](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Last 12 Months\n", + "3. **[Grouped By](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Gear Type" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "38c3bc74-e0f6-4f81-b830-3e3393d6b3d0", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", + " spatial_resolution=\"LOW\",\n", + " group_by=\"GEARTYPE\",\n", + " temporal_resolution=\"ENTIRE\",\n", + " start_date=\"2024-01-01\",\n", + " end_date=\"2025-01-01\",\n", + " spatial_aggregation=True,\n", + " region={\n", + " \"dataset\": \"public-eez-areas\",\n", + " \"id\": \"8400\",\n", + " },\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "5ee5daa3-6696-4552-8d1a-61df417b8873", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_df = step_1_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "35dac242-6479-437a-a35f-249ad22cf191", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 9 entries, 0 to 8\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 9 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 0 non-null object \n", + " 3 gear_type 9 non-null object \n", + " 4 hours 9 non-null float64\n", + " 5 vessel_ids 9 non-null int64 \n", + " 6 vessel_id 0 non-null object \n", + " 7 vessel_type 0 non-null object \n", + " 8 entry_timestamp 0 non-null object \n", + " 9 exit_timestamp 0 non-null object \n", + " 10 first_transmission_date 0 non-null object \n", + " 11 last_transmission_date 0 non-null object \n", + " 12 imo 0 non-null object \n", + " 13 mmsi 0 non-null object \n", + " 14 call_sign 0 non-null object \n", + " 15 dataset 0 non-null object \n", + " 16 report_dataset 9 non-null object \n", + " 17 ship_name 0 non-null object \n", + " 18 lat 0 non-null object \n", + " 19 lon 0 non-null object \n", + "dtypes: float64(1), int64(1), object(18)\n", + "memory usage: 1.5+ KB\n" + ] + } + ], + "source": [ + "step_1_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "6a245cc8-0236-4554-b4c8-d9bbc11db235", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typehoursvessel_ids
0Nonedrifting_longlines593.1383333
1Nonepurse_seines6.3405561
2Nonefishing20929.56333321
3Noneinconclusive30496.17361127
4Nonepole_and_line3481.5091675
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours vessel_ids\n", + "0 None drifting_longlines 593.138333 3\n", + "1 None purse_seines 6.340556 1\n", + "2 None fishing 20929.563333 21\n", + "3 None inconclusive 30496.173611 27\n", + "4 None pole_and_line 3481.509167 5" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_report_df[[\"flag\", \"gear_type\", \"hours\", \"vessel_ids\"]].head()" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "b56ec0e4-5f85-4a10-bd94-39ea55128920", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_agg_report_df = (\n", + " step_1_report_df.groupby([\"gear_type\"], as_index=False)\n", + " .agg(hours=(\"hours\", \"sum\"), vessel_ids=(\"vessel_ids\", \"sum\"))\n", + " .sort_values(by=\"hours\", ascending=False)\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "87289a41-0d54-44c9-a17a-f82b318af293", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
gear_typehoursvessel_ids
7trawlers46704.79722226
3inconclusive30496.17361127
1fishing20929.56333321
8tuna_purse_seines5146.62388923
5pole_and_line3481.5091675
0drifting_longlines593.1383333
4other_purse_seines26.5811111
6purse_seines6.3405561
2fixed_gear0.1636111
\n", + "
" + ], + "text/plain": [ + " gear_type hours vessel_ids\n", + "7 trawlers 46704.797222 26\n", + "3 inconclusive 30496.173611 27\n", + "1 fishing 20929.563333 21\n", + "8 tuna_purse_seines 5146.623889 23\n", + "5 pole_and_line 3481.509167 5\n", + "0 drifting_longlines 593.138333 3\n", + "4 other_purse_seines 26.581111 1\n", + "6 purse_seines 6.340556 1\n", + "2 fixed_gear 0.163611 1" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_agg_report_df" + ] + }, + { + "cell_type": "markdown", + "id": "09252564-51c1-4ed1-b938-76688a670cc6", + "metadata": {}, + "source": [ + "### What We have Learned from Step 1" + ] + }, + { + "cell_type": "markdown", + "id": "79fee5f2-f217-40e4-be1d-235190de64b5", + "metadata": {}, + "source": [ + "1. Kwame now has apparent fishing effort data for multiple gear types.\n", + "2. There are **potential 3 vessels** operating as a **longliners (i.e., drifting_longlines)** in **[Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400)** with `593.138333 hours` logged." + ] + }, + { + "cell_type": "markdown", + "id": "80289282-d160-4901-9bf8-a7996785c898", + "metadata": {}, + "source": [ + "## Step 2: Retrieve Vessel IDs for Longliners" + ] + }, + { + "cell_type": "markdown", + "id": "33209132-cc4a-4711-8e96-0846a71b9c34", + "metadata": {}, + "source": [ + "Kwame refines his **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** request to group by **vessel ID**, and filtering only for **longliners** in **[Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400)**." + ] + }, + { + "cell_type": "markdown", + "id": "293c479b-497c-4472-9ce6-c813985b7533", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **[Region ID](https://globalfishingwatch.org/our-apis/documentation#regions)** - [8400 Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400)\n", + "2. **[Date Range](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Last 12 Months\n", + "3. **[Grouped By](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Vessel ID " + ] + }, + { + "cell_type": "markdown", + "id": "f55f1862-ae0d-4ad5-b281-6a514ae9dcce", + "metadata": {}, + "source": [ + "**Why Use group-by=VESSEL_ID?**\n", + "\n", + "Grouping by **VESSEL_ID** allows **individual vessel identification** in the response. This is crucial for **tracking vessel activity** and, more importantly, linking each detected vessel to the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** in the next step. By structuring the query this way, we can fetch vessel details such as **flag, name, and ownership records** in **Step 3 below**.\n" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "0797f962-6582-4d3b-bfba-3597d5513a73", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", + " spatial_resolution=\"LOW\",\n", + " group_by=\"VESSEL_ID\",\n", + " temporal_resolution=\"ENTIRE\",\n", + " filters=[\"geartype in ('drifting_longlines')\"],\n", + " start_date=\"2024-01-01\",\n", + " end_date=\"2025-01-01\",\n", + " spatial_aggregation=True,\n", + " region={\n", + " \"dataset\": \"public-eez-areas\",\n", + " \"id\": \"8400\",\n", + " },\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "8be53e48-4b93-4140-ae0e-aa910a993da7", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_report_df = step_2_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "061b9fbf-88cf-47d8-9b30-b878c0b867cf", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 3 entries, 0 to 2\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 3 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 3 non-null object \n", + " 3 gear_type 3 non-null object \n", + " 4 hours 3 non-null float64 \n", + " 5 vessel_ids 0 non-null object \n", + " 6 vessel_id 3 non-null object \n", + " 7 vessel_type 3 non-null object \n", + " 8 entry_timestamp 3 non-null datetime64[ns, UTC]\n", + " 9 exit_timestamp 3 non-null datetime64[ns, UTC]\n", + " 10 first_transmission_date 3 non-null datetime64[ns, UTC]\n", + " 11 last_transmission_date 3 non-null datetime64[ns, UTC]\n", + " 12 imo 3 non-null object \n", + " 13 mmsi 3 non-null object \n", + " 14 call_sign 3 non-null object \n", + " 15 dataset 3 non-null object \n", + " 16 report_dataset 3 non-null object \n", + " 17 ship_name 3 non-null object \n", + " 18 lat 0 non-null object \n", + " 19 lon 0 non-null object \n", + "dtypes: datetime64[ns, UTC](4), float64(1), object(15)\n", + "memory usage: 612.0+ bytes\n" + ] + } + ], + "source": [ + "step_2_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "932bd692-c689-4e1d-985c-18eeccdf9ec3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typehoursmmsiship_name
0CHNDRIFTING_LONGLINES2.750556412331032
1JPNDRIFTING_LONGLINES588.879722431100690SENSHU MARU NO.3
2TWNDRIFTING_LONGLINES1.508056416007496HUNG CHUAN SHUN
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours mmsi ship_name\n", + "0 CHN DRIFTING_LONGLINES 2.750556 412331032 \n", + "1 JPN DRIFTING_LONGLINES 588.879722 431100690 SENSHU MARU NO.3\n", + "2 TWN DRIFTING_LONGLINES 1.508056 416007496 HUNG CHUAN SHUN" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_report_df[[\"flag\", \"gear_type\", \"hours\", \"mmsi\", \"ship_name\"]].head()" + ] + }, + { + "cell_type": "markdown", + "id": "e54e9165-3f02-46a5-b4ef-74dbfc618766", + "metadata": {}, + "source": [ + "### What We have Learned from Step 2" + ] + }, + { + "cell_type": "markdown", + "id": "72a9efeb-ae54-4bbd-ab85-77845f928376", + "metadata": {}, + "source": [ + "1. Kwame identifies `3 vessels` operating as longliners within **[Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400)**.\n", + "2. The vessel `(mmsi: 431100690, ship_name: SENSHU MARU NO.3)` shows significant activity with `588.879722 hours` logged.\n", + "3. Other vessels `(mmsi: 416007496, ship_name: HUNG CHUAN SHUN)` and `(mmsi: 412331032)` shows apparent fishing effort over a short duration.\n", + "4. This response is based on **AIS self-reported** data and should be further validated.\n" + ] + }, + { + "cell_type": "markdown", + "id": "06b8fa5a-b2fd-415c-9bea-d8ef4902cbe6", + "metadata": {}, + "source": [ + "## Step 3: Retrieve Vessel Details Using the Vessels API" + ] + }, + { + "cell_type": "markdown", + "id": "f491fac4-0825-4c6b-aba2-d889d2ec678e", + "metadata": {}, + "source": [ + "Kwame queries the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** to **get detailed vessel identity and ownership records**. Please [learn more about Vessels API here](https://globalfishingwatch.org/our-apis/documentation#vessels-api) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)." + ] + }, + { + "cell_type": "markdown", + "id": "0ed8adac-33da-4168-90a6-5381e9b628f6", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **Vessel IDs** from 4Wings API, **Step 2 above**.\n", + "2. **[Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset)** - `public-global-vessel-identity:latest`.\n", + "3. **[Includes](https://globalfishingwatch.org/our-apis/documentation#get-vessels-by-ids-url-parameters)** - `POTENTIAL_RELATED_SELF_REPORTED_INFO`." + ] + }, + { + "cell_type": "markdown", + "id": "fa782e3d-3c9d-4236-a0e4-157e22e6aeed", + "metadata": {}, + "source": [ + "**Note:** Vessels may change identifiers over time, such as their `Maritime Mobile Service Identity (MMSI)`,` International Maritime Organization (IMO) number)`, `call sign`, or even their `name`. These changes can occur due to `re-registration`, `changes in ownership`, or other `operational reasons` within the `AIS transponder`. Parameter (`includes = POTENTIAL_RELATED_SELF_REPORTED_INFO`) helps group all **vessel ids** that are **potentially related** as part of the **same physical vessel** based on publicly available registry information." + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "15889e5c-dea7-499d-bd77-68a12aca8d98", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_vessel_ids = list(step_2_report_df[\"vessel_id\"].unique())" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "8477d36f-27ea-4ca9-aaad-dfaf8d94cd80", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['f37ebdc1b-be44-0740-7904-49397360e29d',\n", + " 'b1dad8628-8c9c-2ee7-258b-3d8fb747f1c8',\n", + " '60f7bb972-2c90-4553-650b-23c38f9521bf']" + ] + }, + "execution_count": 16, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_vessel_ids" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "33d970d9-1321-46ec-87bc-91aed1f446ff", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_vessels_result = await gfw_client.vessels.get_vessels_by_ids(\n", + " ids=step_2_vessel_ids,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "c1b9a6e9-683f-44fe-bb47-98825cf9d150", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_vessels_df = step_3_vessels_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "d87c1cef-92d1-462d-a86e-c2af11912ed9", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 3 entries, 0 to 2\n", + "Data columns (total 7 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 dataset 3 non-null object\n", + " 1 registry_info_total_records 3 non-null int64 \n", + " 2 registry_info 3 non-null object\n", + " 3 registry_owners 3 non-null object\n", + " 4 registry_public_authorizations 3 non-null object\n", + " 5 combined_sources_info 3 non-null object\n", + " 6 self_reported_info 3 non-null object\n", + "dtypes: int64(1), object(6)\n", + "memory usage: 300.0+ bytes\n" + ] + } + ], + "source": [ + "step_3_vessels_df.info()" + ] + }, + { + "cell_type": "markdown", + "id": "9a64a937-59af-414d-8fcc-28948c423117", + "metadata": {}, + "source": [ + "**Understanding Vessel Details Response Data**\n", + "\n", + "- **registryInfoTotalRecords** – This represents the **number of registry records** found for the vessels.\n", + "- **registryInfo** – Contains **public registry data**. This data is sourced from official **vessel registries**.\n", + "- **registryOwners** – Lists the **registered owners** of the vessel based on public sources.\n", + "- **registryPublicAuthorizations** – Represents known **fishing authorizations** from public sources. Users should verify against national registries and RFMO records for additional context.\n", + "- **combinedSourcesInfo** – Provides inferred data from multiple sources, including. This is not explicitly reported by vessels but determined through **GFW's classification methods**.\n", + "- **selfReportedInfo** – Contains **AIS self-reported** data, including `MMSI`, `ship name`, and `flag` as broadcast by the **vessel itself**. Self-reported data may not always align with registry data and should be cross-checked." + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "348301a7-c290-4684-bb03-23298e8bc7e0", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
registry_inforegistry_ownersself_reported_info
0[{'id': '0b0dec977c1aad4ae6652c4076572cc7', 's...[{'name': 'TOMIOKA FISHERIES', 'flag': 'JPN', ...[{'id': 'c86d138c5-5d51-3620-fe01-a9e0ed37fb91...
1[][][{'id': 'f37ebdc1b-be44-0740-7904-49397360e29d...
2[{'id': '02eda7d2da02943eecd48813fb7d562a', 's...[{'name': 'HER RONG SHUN FISHERIES', 'flag': '...[{'id': '60f7bb972-2c90-4553-650b-23c38f9521bf...
\n", + "
" + ], + "text/plain": [ + " registry_info \\\n", + "0 [{'id': '0b0dec977c1aad4ae6652c4076572cc7', 's... \n", + "1 [] \n", + "2 [{'id': '02eda7d2da02943eecd48813fb7d562a', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'TOMIOKA FISHERIES', 'flag': 'JPN', ... \n", + "1 [] \n", + "2 [{'name': 'HER RONG SHUN FISHERIES', 'flag': '... \n", + "\n", + " self_reported_info \n", + "0 [{'id': 'c86d138c5-5d51-3620-fe01-a9e0ed37fb91... \n", + "1 [{'id': 'f37ebdc1b-be44-0740-7904-49397360e29d... \n", + "2 [{'id': '60f7bb972-2c90-4553-650b-23c38f9521bf... " + ] + }, + "execution_count": 20, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_vessels_df[[\"registry_info\", \"registry_owners\", \"self_reported_info\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "44ae4527-da01-4845-be11-b46ddd5575fc", + "metadata": {}, + "source": [ + "### Explore Vessels Registry Info" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "7e5cf6db-8f45-4c7e-a8c8-ccdb312eca7d", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_registry_info_df = pd.json_normalize(\n", + " step_3_vessels_df[\"registry_info\"].explode()\n", + ")\n", + "step_3_registry_info_df = step_3_registry_info_df.dropna()" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "b350572a-93ec-434f-8f6f-d0418f693b46", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namegear_typessource_code
0431100690JPNSENSHU MARU NO.3SENSHUMARU3[DRIFTING_LONGLINES][CCSBT, GFCM, IATTC, ICCAT, IMO, IOTC, OPRT, R...
2416007496TWNHUNG CHUAN SHUNHUNGCHUANSHUN[DRIFTING_LONGLINES][ICCAT, IMO, ISSF, OPRT, TMT_ICCAT, TMT_OTHER_...
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name gear_types \\\n", + "0 431100690 JPN SENSHU MARU NO.3 SENSHUMARU3 [DRIFTING_LONGLINES] \n", + "2 416007496 TWN HUNG CHUAN SHUN HUNGCHUANSHUN [DRIFTING_LONGLINES] \n", + "\n", + " source_code \n", + "0 [CCSBT, GFCM, IATTC, ICCAT, IMO, IOTC, OPRT, R... \n", + "2 [ICCAT, IMO, ISSF, OPRT, TMT_ICCAT, TMT_OTHER_... " + ] + }, + "execution_count": 22, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_registry_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"gear_types\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "5e0fb205-ea78-4074-b3bb-266d624d5f86", + "metadata": {}, + "source": [ + "### Explore Registry Owners" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "0ed351c2-104c-4132-bcae-a3c757ac2465", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_registry_owners_df = pd.json_normalize(\n", + " step_3_vessels_df[\"registry_owners\"].explode()\n", + ")\n", + "step_3_registry_owners_df = step_3_registry_owners_df.dropna()" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "d6bbbc39-1928-42cd-9866-71fa95a601d8", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagnamesource_code
0431100690JPNTOMIOKA FISHERIES[TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF...
1431100690JPNTOMIOKA[TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF...
2431100690JPNYAMAMOTO YUUKI[TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF...
3431100690JPNYAMAMOTO HIROKI[TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF...
5416007496TWNHER RONG SHUN FISHERIES[TMT_ICCAT, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag name \\\n", + "0 431100690 JPN TOMIOKA FISHERIES \n", + "1 431100690 JPN TOMIOKA \n", + "2 431100690 JPN YAMAMOTO YUUKI \n", + "3 431100690 JPN YAMAMOTO HIROKI \n", + "5 416007496 TWN HER RONG SHUN FISHERIES \n", + "\n", + " source_code \n", + "0 [TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF... \n", + "1 [TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF... \n", + "2 [TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF... \n", + "3 [TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF... \n", + "5 [TMT_ICCAT, TMT_OTHER_OFFICIAL] " + ] + }, + "execution_count": 24, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_registry_owners_df[[\"ssvid\", \"flag\", \"name\", \"source_code\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "e355771a-ec2a-41b2-ab51-801baf15fab1", + "metadata": {}, + "source": [ + "### Explore Vessels Self Reported Info" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "add8a66e-9736-4cdb-a74d-0607fcc530a2", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_self_reported_info_df = pd.json_normalize(\n", + " step_3_vessels_df[\"self_reported_info\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "fd0831dc-e29e-4ccc-864f-704eebee2686", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namesource_code
0431100690JPNNoneNone[AIS]
1431100690JPNSENSHU MARU NO.3SENSHUMARU3[AIS]
2431100690JPNSENSHU MARU NO3SENSHUMARU3[AIS]
3412331032CHNNoneNone[AIS]
4416007496TWNHUNG CHUAN SHUNHUNGCHUANSHUN[AIS]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name source_code\n", + "0 431100690 JPN None None [AIS]\n", + "1 431100690 JPN SENSHU MARU NO.3 SENSHUMARU3 [AIS]\n", + "2 431100690 JPN SENSHU MARU NO3 SENSHUMARU3 [AIS]\n", + "3 412331032 CHN None None [AIS]\n", + "4 416007496 TWN HUNG CHUAN SHUN HUNGCHUANSHUN [AIS]" + ] + }, + "execution_count": 26, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_self_reported_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "a4e08576-803c-482f-afa5-3fbf4a86837d", + "metadata": {}, + "source": [ + "### What We have Learned from Step 3" + ] + }, + { + "cell_type": "markdown", + "id": "37e54952-ec16-4c85-a6c3-ee7e844d007b", + "metadata": {}, + "source": [ + "- The vessel `mmsi/ssvid: 412331032` appears to be a drifting longliner flagged under China.\n", + "- No public registry data is found for this vessel.\n", + "- The vessel's identity information is based on `AIS self-reported data`, which may not always align with official registries.\n", + "- The vessel appears to have been active since `2014`, based on `self-reported AIS records`.\n", + "- This vessel's data needs further validation against official public sources" + ] + }, + { + "cell_type": "markdown", + "id": "2dc21e2c-a261-44ee-a3b6-2065d4095bcb", + "metadata": {}, + "source": [ + "## Step 4: Detect Fleet Activity (Port Visits)" + ] + }, + { + "cell_type": "markdown", + "id": "ce91f54f-8938-428c-bb22-21c54c8b51f5", + "metadata": {}, + "source": [ + "Now that Kwame has identified vessels in the fleet, he examines their activity further by querying the **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)**. This allows him to detect `port visits`, `encounters (Potential Transshipment)` and `apparent fishing activity` based on vessel movement patterns. Please [learn more about Events API here](https://globalfishingwatch.org/our-apis/documentation#events-api) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#how-are-the-events-estimated)." + ] + }, + { + "cell_type": "markdown", + "id": "af80cd9c-fe29-4650-9052-dbe7b623eb8d", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **Vessel ID** from 4Wings API\n", + "2. **[Event Types](https://globalfishingwatch.org/our-apis/documentation#events-post-body-parameters)** - Port visits, encounters (potential transshipment), and fishing events.\n", + "3. **Time Range** - Last 6 months.\n", + "4. **[Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset)**:\n", + " - `public-global-port-visits-events::latest` (Port Visits)\n", + " - `public-global-encounters-events:latest` (Encounters between vessels)\n", + " - `public-global-fishing-events:latest` (Fishing activity)\n", + "5. **[Encounter Types](https://globalfishingwatch.org/our-apis/documentation#events-post-body-parameters)** - FISHING-FISHING" + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "ae1567e5-0594-4eb3-a78a-5e8902deb2ac", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_events_result = await gfw_client.events.get_all_events(\n", + " datasets=[\n", + " \"public-global-encounters-events:latest\",\n", + " \"public-global-fishing-events:latest\",\n", + " \"public-global-port-visits-events:latest\",\n", + " ],\n", + " vessels=step_2_vessel_ids,\n", + " types=[\"ENCOUNTER\", \"FISHING\", \"PORT_VISIT\"],\n", + " start_date=\"2024-08-01\",\n", + " end_date=\"2025-01-31\",\n", + " encounter_types=[\"FISHING-FISHING\"],\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "904c3745-e999-4fc7-a3fe-dd639c6a87c2", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_events_df = step_4_events_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "7f2ef6a8-6eed-47c5-bb44-253bad118956", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 418 entries, 0 to 417\n", + "Data columns (total 14 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 start 418 non-null datetime64[ns, UTC]\n", + " 1 end 418 non-null datetime64[ns, UTC]\n", + " 2 id 418 non-null object \n", + " 3 type 418 non-null object \n", + " 4 position 418 non-null object \n", + " 5 regions 418 non-null object \n", + " 6 bounding_box 418 non-null object \n", + " 7 distances 418 non-null object \n", + " 8 vessel 418 non-null object \n", + " 9 encounter 0 non-null object \n", + " 10 fishing 414 non-null object \n", + " 11 gap 0 non-null object \n", + " 12 loitering 0 non-null object \n", + " 13 port_visit 4 non-null object \n", + "dtypes: datetime64[ns, UTC](2), object(12)\n", + "memory usage: 45.8+ KB\n" + ] + } + ], + "source": [ + "step_4_events_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "39b4f990-1da9-4862-b9fc-554f7b4c7dc0", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "type\n", + "fishing 414\n", + "port_visit 4\n", + "Name: count, dtype: int64" + ] + }, + "execution_count": 30, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_events_df[\"type\"].value_counts()" + ] + }, + { + "cell_type": "markdown", + "id": "ccb71753-df83-4ca1-8a43-89fa2cb344d4", + "metadata": {}, + "source": [ + "### Explore Apparent Fishing Events" + ] + }, + { + "cell_type": "code", + "execution_count": 31, + "id": "87b32f2a-29ea-4f11-87c2-a16655ac5005", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_fishing_events_df = step_4_events_df[step_4_events_df[\"fishing\"].notna()]" + ] + }, + { + "cell_type": "code", + "execution_count": 32, + "id": "7ee57f28-eff1-40d7-865a-e3ad04103b4c", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_fishing_df = pd.concat(\n", + " [\n", + " pd.json_normalize(step_4_fishing_events_df[\"vessel\"], sep=\"_\"),\n", + " pd.json_normalize(step_4_fishing_events_df[\"fishing\"], sep=\"_\"),\n", + " ],\n", + " axis=1,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "id": "4a8deceb-aaef-4fe3-8a43-88b4c34d2a70", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 414 entries, 0 to 413\n", + "Data columns (total 12 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 414 non-null object \n", + " 1 name 389 non-null object \n", + " 2 ssvid 414 non-null object \n", + " 3 flag 414 non-null object \n", + " 4 type 414 non-null object \n", + " 5 public_authorizations 414 non-null object \n", + " 6 nextPort 0 non-null object \n", + " 7 total_distance_km 414 non-null float64\n", + " 8 average_speed_knots 414 non-null float64\n", + " 9 average_duration_hours 0 non-null object \n", + " 10 potential_risk 414 non-null bool \n", + " 11 vessel_public_authorization_status 414 non-null object \n", + "dtypes: bool(1), float64(2), object(9)\n", + "memory usage: 36.1+ KB\n" + ] + } + ], + "source": [ + "step_4_fishing_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 34, + "id": "0b95e76a-7fe8-45ba-87a3-ffab7d15c7d1", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
namessvidtotal_distance_kmaverage_speed_knots
0HUNG CHUAN SHUN41600749618.4810568.841667
1HUNG CHUAN SHUN41600749634.8675598.240000
2HUNG CHUAN SHUN41600749611.0868508.208333
3HUNG CHUAN SHUN41600749612.6996508.266667
4HUNG CHUAN SHUN41600749656.7880346.248000
...............
409SENSHU MARU NO.343110069012.1644945.083333
410SENSHU MARU NO.343110069013.1911243.986957
411SENSHU MARU NO.34311006908.6856593.850000
412SENSHU MARU NO.343110069015.7219873.686667
413SENSHU MARU NO.343110069028.5537793.728571
\n", + "

414 rows × 4 columns

\n", + "
" + ], + "text/plain": [ + " name ssvid total_distance_km average_speed_knots\n", + "0 HUNG CHUAN SHUN 416007496 18.481056 8.841667\n", + "1 HUNG CHUAN SHUN 416007496 34.867559 8.240000\n", + "2 HUNG CHUAN SHUN 416007496 11.086850 8.208333\n", + "3 HUNG CHUAN SHUN 416007496 12.699650 8.266667\n", + "4 HUNG CHUAN SHUN 416007496 56.788034 6.248000\n", + ".. ... ... ... ...\n", + "409 SENSHU MARU NO.3 431100690 12.164494 5.083333\n", + "410 SENSHU MARU NO.3 431100690 13.191124 3.986957\n", + "411 SENSHU MARU NO.3 431100690 8.685659 3.850000\n", + "412 SENSHU MARU NO.3 431100690 15.721987 3.686667\n", + "413 SENSHU MARU NO.3 431100690 28.553779 3.728571\n", + "\n", + "[414 rows x 4 columns]" + ] + }, + "execution_count": 34, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_fishing_df[\n", + " [\n", + " \"name\",\n", + " \"ssvid\",\n", + " \"total_distance_km\",\n", + " \"average_speed_knots\",\n", + " ]\n", + "]" + ] + }, + { + "cell_type": "code", + "execution_count": 35, + "id": "2416d761-b334-4995-ba67-81ff96c3dd57", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "ssvid\n", + "416007496 363\n", + "431100690 26\n", + "412331032 25\n", + "Name: count, dtype: int64" + ] + }, + "execution_count": 35, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_fishing_df[\"ssvid\"].value_counts()" + ] + }, + { + "cell_type": "markdown", + "id": "dfdc826c-d854-4f1c-bf0b-82560d23a2f4", + "metadata": {}, + "source": [ + "### Explore Port Visit Events" + ] + }, + { + "cell_type": "code", + "execution_count": 36, + "id": "337ddf63-42ba-4ea7-a56d-2d8d602f5a22", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_port_visit_events_df = step_4_events_df[step_4_events_df[\"port_visit\"].notna()]" + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "id": "a77465d1-02ce-42bb-a0b3-7c243cf02a40", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_port_visits_df = pd.concat(\n", + " [\n", + " pd.json_normalize(step_4_port_visit_events_df[\"vessel\"], sep=\"_\"),\n", + " pd.json_normalize(step_4_port_visit_events_df[\"port_visit\"], sep=\"_\"),\n", + " ],\n", + " axis=1,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 38, + "id": "566e8a67-8fff-4d10-9749-83c6dae727b7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 4 entries, 0 to 3\n", + "Data columns (total 37 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 4 non-null object \n", + " 1 name 3 non-null object \n", + " 2 ssvid 4 non-null object \n", + " 3 flag 4 non-null object \n", + " 4 type 4 non-null object \n", + " 5 public_authorizations 4 non-null object \n", + " 6 nextPort 0 non-null object \n", + " 7 visit_id 4 non-null object \n", + " 8 confidence 4 non-null object \n", + " 9 duration_hrs 4 non-null float64\n", + " 10 start_anchorage_anchorage_id 4 non-null object \n", + " 11 start_anchorage_at_dock 4 non-null bool \n", + " 12 start_anchorage_distance_from_shore_km 4 non-null float64\n", + " 13 start_anchorage_flag 4 non-null object \n", + " 14 start_anchorage_id 4 non-null object \n", + " 15 start_anchorage_lat 4 non-null float64\n", + " 16 start_anchorage_lon 4 non-null float64\n", + " 17 start_anchorage_name 4 non-null object \n", + " 18 start_anchorage_top_destination 4 non-null object \n", + " 19 intermediate_anchorage_anchorage_id 4 non-null object \n", + " 20 intermediate_anchorage_at_dock 4 non-null bool \n", + " 21 intermediate_anchorage_distance_from_shore_km 4 non-null float64\n", + " 22 intermediate_anchorage_flag 4 non-null object \n", + " 23 intermediate_anchorage_id 4 non-null object \n", + " 24 intermediate_anchorage_lat 4 non-null float64\n", + " 25 intermediate_anchorage_lon 4 non-null float64\n", + " 26 intermediate_anchorage_name 4 non-null object \n", + " 27 intermediate_anchorage_top_destination 4 non-null object \n", + " 28 end_anchorage_anchorage_id 4 non-null object \n", + " 29 end_anchorage_at_dock 4 non-null bool \n", + " 30 end_anchorage_distance_from_shore_km 4 non-null float64\n", + " 31 end_anchorage_flag 4 non-null object \n", + " 32 end_anchorage_id 4 non-null object \n", + " 33 end_anchorage_lat 4 non-null float64\n", + " 34 end_anchorage_lon 4 non-null float64\n", + " 35 end_anchorage_name 4 non-null object \n", + " 36 end_anchorage_top_destination 4 non-null object \n", + "dtypes: bool(3), float64(10), object(24)\n", + "memory usage: 1.2+ KB\n" + ] + } + ], + "source": [ + "step_4_port_visits_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 39, + "id": "0381a7bd-cf81-4b58-9f8d-f01601121ad2", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
namessvidconfidencestart_anchorage_nameintermediate_anchorage_nameend_anchorage_name
0HUNG CHUAN SHUN4160074964TEMATEMATEMA
1SENSHU MARU NO.34311006904TEMATEMATEMA
2None4123310324DAKARDAKARDAKAR
3SENSHU MARU NO.34311006904TEMATEMATEMA
\n", + "
" + ], + "text/plain": [ + " name ssvid confidence start_anchorage_name \\\n", + "0 HUNG CHUAN SHUN 416007496 4 TEMA \n", + "1 SENSHU MARU NO.3 431100690 4 TEMA \n", + "2 None 412331032 4 DAKAR \n", + "3 SENSHU MARU NO.3 431100690 4 TEMA \n", + "\n", + " intermediate_anchorage_name end_anchorage_name \n", + "0 TEMA TEMA \n", + "1 TEMA TEMA \n", + "2 DAKAR DAKAR \n", + "3 TEMA TEMA " + ] + }, + "execution_count": 39, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_port_visits_df[\n", + " [\n", + " \"name\",\n", + " \"ssvid\",\n", + " \"confidence\",\n", + " \"start_anchorage_name\",\n", + " \"intermediate_anchorage_name\",\n", + " \"end_anchorage_name\",\n", + " ]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "2d340b6b-3d88-4c48-a699-305a75e706a4", + "metadata": {}, + "source": [ + "### What We’ve Learned from Step 4" + ] + }, + { + "cell_type": "markdown", + "id": "709d2a5c-5246-4995-ab68-0997adf62349", + "metadata": {}, + "source": [ + "- `4: port visits`, `0: encounters`, and `414: fishing` events were found for the queried vessels in the given date range.\n", + "- Some events were missed due to **AIS data coverage gaps**.\n", + "- Different filters may need to be applied to refine results." + ] + }, + { + "cell_type": "markdown", + "id": "be4b21a0-f3ea-4f10-a61f-cf121cbe078e", + "metadata": {}, + "source": [ + "**Caveats & Considerations**" + ] + }, + { + "cell_type": "markdown", + "id": "c7625234-6210-4701-91b2-cca2cfe43494", + "metadata": {}, + "source": [ + "- **A lack of recorded encounters or any other events does not confirm the absence of such activities**—AIS coverage, reporting behavior, and dataset updates can impact results.\n", + "- **Further investigation may be required**, including manual validation using historical data or consulting additional sources." + ] + }, + { + "cell_type": "markdown", + "id": "8b951044-6905-4e38-9885-13a98cf3a7cf", + "metadata": {}, + "source": [ + "## Summary of API Flow" + ] + }, + { + "cell_type": "markdown", + "id": "c8f86731-be44-4b89-8abb-cf2f6693b4c9", + "metadata": {}, + "source": [ + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** - Identify fishing effort by **gear type** in Ghanaian EEZ.\n", + "2. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** - Retrieve vessel IDs for potential **longliners**.\n", + "3. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** - Fetch detailed **vessel identity** & **ownership**.\n", + "4. **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)** - Attempt to detect fleet activity (**port visits**, **encounters**, and **apparent fishing** events)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/usage-guides/4wings-api.ipynb b/notebooks/usage-guides/4wings-api.ipynb index d825bef..6c4d5df 100644 --- a/notebooks/usage-guides/4wings-api.ipynb +++ b/notebooks/usage-guides/4wings-api.ipynb @@ -36,7 +36,7 @@ "id": "3d31e934-e291-453d-aad9-6e0e61d1318e", "metadata": {}, "source": [ - "**Note:** See the [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat) 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 [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), 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." ] }, { diff --git a/notebooks/workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez.ipynb b/notebooks/workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez.ipynb new file mode 100644 index 0000000..c37fb6a --- /dev/null +++ b/notebooks/workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez.ipynb @@ -0,0 +1,1260 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "1b582ffc-7477-46c3-b5bf-2caf9d028bf2", + "metadata": {}, + "source": [ + "\"Open" + ] + }, + { + "cell_type": "markdown", + "id": "87eddf13-ac9c-45b0-ae10-24eb1620e07e", + "metadata": {}, + "source": [ + "# Analyze apparent fishing effort in Senegalese EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "d79f0ab4-ab4d-4098-82b0-b6a5c772e101", + "metadata": {}, + "source": [ + "This guide provides detailed instructions to on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to **Analyze apparent fishing effort in [Senegalese EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8371) region and monitor vessel activities** using **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)**, and **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)**." + ] + }, + { + "cell_type": "markdown", + "id": "7ac25ecf-ffd7-40d7-9ea0-a6514c9fcd85", + "metadata": {}, + "source": [ + "**Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), 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." + ] + }, + { + "cell_type": "markdown", + "id": "71018cec-10c0-4619-9a7d-838a9f43cb15", + "metadata": {}, + "source": [ + "## Prerequisites" + ] + }, + { + "cell_type": "markdown", + "id": "996ca24b-99e4-4546-805b-697e4c2eb321", + "metadata": {}, + "source": [ + "Before using the `gfw-api-python-client`, ensure it is installed (see the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html) guide) and that you have obtained an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)." + ] + }, + { + "cell_type": "markdown", + "id": "6be16f6f-19fc-4d19-a0ed-ba370c844fa6", + "metadata": {}, + "source": [ + "## Installation" + ] + }, + { + "cell_type": "markdown", + "id": "af48cf4e-e24c-47aa-a2c5-64cf87be9c33", + "metadata": {}, + "source": [ + "The `gfw-api-python-client` can be easily installed using pip:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "88c09924-87d2-4c86-ad60-aed623416193", + "metadata": {}, + "outputs": [], + "source": [ + "# %pip install gfw-api-python-client" + ] + }, + { + "cell_type": "markdown", + "id": "eafaa9d1-2143-452c-813c-75b21fd2198c", + "metadata": {}, + "source": [ + "## Usage" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "cc98323c-c9e4-401c-8f26-f551968c003a", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "import datetime\n", + "import pandas as pd\n", + "import gfwapiclient as gfw" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "047ff069-3c87-47fe-bb4a-acb920df2137", + "metadata": {}, + "outputs": [], + "source": [ + "try:\n", + " from google.colab import userdata\n", + "\n", + " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", + "except Exception as exc:\n", + " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", + "\n", + "access_token = access_token or \"\"" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "708e137f-6aa0-461e-b1af-33512a2093fc", + "metadata": {}, + "outputs": [], + "source": [ + "gfw_client = gfw.Client(\n", + " access_token=access_token,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b08a0e2c-3b9d-4c5e-b3a0-a5663fa32637", + "metadata": {}, + "source": [ + "## Introduction" + ] + }, + { + "cell_type": "markdown", + "id": "62fe47aa-ed77-4815-b08d-8c96f2480b04", + "metadata": {}, + "source": [ + "**Use Case: A Port Inspector Monitoring Vessel Activity**" + ] + }, + { + "cell_type": "markdown", + "id": "5109f67f-aaae-4a7d-9a15-4db740542694", + "metadata": {}, + "source": [ + "Mamadou, a port inspector in Dakar, Senegal, monitors vessel activity within **[Senegalese Exclusive Economic Zone (EEZ)]((https://www.marineregions.org/gazetteer.php?p=details&id=8371))**. His goal is to:\n", + "\n", + "1. Analyzing apparent fishing effort, specifically for **trawlers** in Senegalese EEZ.\n", + "2. Identifying vessels involved in **apparent trawling activity** and determining their reported **flag states**.\n", + "3. Checking vessel history, including prior **encounters (or potential transshipment)** or **port visits**.\n", + "4. Generating reports for enforcement authorities to assess risks." + ] + }, + { + "cell_type": "markdown", + "id": "b16b1b52-6b68-494a-9d76-ca7a7ab485a0", + "metadata": {}, + "source": [ + "**APIs Used:**\n", + "️\n", + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** – To retrieve **apparent fishing effort** data for trawlers operating in Senegalese EEZ over the past 3 months.\n", + "2. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** – To retrieve **detailed vessel information**, including `flag`, `ownership history`, and `authorizations`." + ] + }, + { + "cell_type": "markdown", + "id": "a6006ce5-675f-4d1f-89a5-69130ff1ed5b", + "metadata": {}, + "source": [ + "**Important:** In order to avoid any misinterpretation of **GFW data**, please refer to our official **data caveats** documentations:\n", + "- [Apparent fishing effort](https://globalfishingwatch.org/dataset-and-code-fishing-effort/) \n", + "- [Exclusive economic zone boundaries definition](https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition)\n", + "- [Vessel ID](https://globalfishingwatch.org/our-apis/documentation#vessel-id)\n", + "- [Vessel API - Vessel identity information](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)" + ] + }, + { + "cell_type": "markdown", + "id": "5413d78e-e745-4f74-a062-f303c7a1669f", + "metadata": {}, + "source": [ + "**Important Caveats:**\n", + "\n", + "1. The [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api) only supports **one active report per user at a time**.\n", + "2. **Sending multiple requests simultaneously** results in a **429 Too Many Requests** error.\n", + "3. If a report takes over **100 seconds** to generate, it may return a **524 Gateway Timeout** error." + ] + }, + { + "cell_type": "markdown", + "id": "2c1e1858-c328-4719-8f10-40ae5b43ecb0", + "metadata": {}, + "source": [ + "## Step 0: Identify the Region of Interest (ROI) - Senegalese EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "7d5e3571-f47f-4c2f-8d0d-0c89baae4411", + "metadata": {}, + "source": [ + "Before making API requests, Mamadou must specify the geographic area for analysis using a **Region ID**:" + ] + }, + { + "cell_type": "markdown", + "id": "75a985b1-3803-48d9-b2f3-f12b29bd29e7", + "metadata": {}, + "source": [ + "**Options to Define the Region:**\n", + "\n", + "1. **Using Region ID** - Each EEZ has a unique ID in the **[public-eez-areas](https://globalfishingwatch.org/our-apis/documentation#regions)** dataset.\n", + "2. **Custom Geometries** - Users can define a custom area using GeoJSON.\n", + " \n", + "For **[Senegalese EEZ, the region ID is 8371](https://www.marineregions.org/gazetteer.php?p=details&id=8371)** (public-eez-areas dataset)." + ] + }, + { + "cell_type": "markdown", + "id": "6fe5edf3-8e96-4147-8c59-a6bc8982662d", + "metadata": {}, + "source": [ + "## Step 1: Retrieve Apparent Fishing Effort in Senegalese EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "4bede3c0-3d01-4661-8b88-467244417d20", + "metadata": {}, + "source": [ + "Mamadou **first queries** the **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** to get **apparent fishing effort for all vessels**, grouping them by **vessel ID** in **[Senegalese EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8371)**. Please [learn more about apparent fishing effort here](https://globalfishingwatch.org/our-apis/documentation#ais-apparent-fishing-effort) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort)." + ] + }, + { + "cell_type": "markdown", + "id": "2e2e42d9-1b9e-4115-b601-72d0e86ab91d", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **[Region ID](https://globalfishingwatch.org/our-apis/documentation#regions)** - [8371 Senegalese EEZ]((https://www.marineregions.org/gazetteer.php?p=details&id=8371))\n", + "2. **[Date Range](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Last 3 Months\n", + "3. **[Grouped By](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Vessel ID\n", + "4. **[Gear Type](https://globalfishingwatch.org/our-apis/documentation#gear-types-supported)** - Trawlers " + ] + }, + { + "cell_type": "markdown", + "id": "849f6157-fa79-456f-8974-d294c77a0729", + "metadata": {}, + "source": [ + "**Why Use group-by=VESSEL_ID?**\n", + "\n", + "Grouping by **VESSEL_ID** allows **individual vessel identification** in the response. This is crucial for **tracking vessel activity** and, more importantly, linking each detected vessel to the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** in the next step. By structuring the query this way, we can fetch vessel details such as **flag, name, and ownership records** in **Step 2 below**.\n" + ] + }, + { + "cell_type": "markdown", + "id": "cf72ff2d-afd7-45bb-8350-aceaebc154d4", + "metadata": {}, + "source": [ + "**Explanation of Parameters & Considerations**\n", + "\n", + "- Gear types, such as **trawlers**, are inferred based on **Global Fishing Watch’s vessel classification system**, which relies on **AIS data and vessel public registries**. The **gear type associated with each vessel is not always 100% accurate**, as it may be derived from historical sources or inferred from movement patterns. See more details on [supported gear types here](https://globalfishingwatch.org/our-apis/documentation#gear-types-supported).\n", + "- Also, please see data caveats regarding [vessel types and their classification here](https://globalfishingwatch.org/our-apis/documentation#vessel-types).\n", + "- See more details on retrieving [Region IDs here](https://globalfishingwatch.org/our-apis/documentation#regions)." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "db35d1b2-ba32-4a58-97f3-17059b3de164", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", + " spatial_resolution=\"HIGH\",\n", + " group_by=\"VESSEL_ID\",\n", + " temporal_resolution=\"MONTHLY\",\n", + " filters=[\"geartype in ('trawlers')\"],\n", + " start_date=\"2024-11-01\",\n", + " end_date=\"2025-01-31\",\n", + " spatial_aggregation=True,\n", + " region={\n", + " \"dataset\": \"public-eez-areas\",\n", + " \"id\": \"8371\",\n", + " },\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "301f888e-3b7e-4946-a7aa-496e05b53cbd", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_df = step_1_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "866f84fb-50c4-47e2-95fa-43fbc06d17cd", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 170 entries, 0 to 169\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 170 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 170 non-null object \n", + " 3 gear_type 170 non-null object \n", + " 4 hours 170 non-null float64 \n", + " 5 vessel_ids 0 non-null object \n", + " 6 vessel_id 170 non-null object \n", + " 7 vessel_type 170 non-null object \n", + " 8 entry_timestamp 170 non-null datetime64[ns, UTC]\n", + " 9 exit_timestamp 170 non-null datetime64[ns, UTC]\n", + " 10 first_transmission_date 170 non-null datetime64[ns, UTC]\n", + " 11 last_transmission_date 170 non-null datetime64[ns, UTC]\n", + " 12 imo 170 non-null object \n", + " 13 mmsi 170 non-null object \n", + " 14 call_sign 170 non-null object \n", + " 15 dataset 170 non-null object \n", + " 16 report_dataset 170 non-null object \n", + " 17 ship_name 170 non-null object \n", + " 18 lat 0 non-null object \n", + " 19 lon 0 non-null object \n", + "dtypes: datetime64[ns, UTC](4), float64(1), object(15)\n", + "memory usage: 26.7+ KB\n" + ] + } + ], + "source": [ + "step_1_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "c76de7b9-260b-4469-aea5-0ad8fe2f25a4", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typehoursmmsiship_name
0CHNTRAWLERS31.888889412444322MIN LONG YU61146
1SENTRAWLERS524.815556663093000AMINE
2CHNTRAWLERS0.368056412209175MENGXIN24
3ESPTRAWLERS1.306389225987981CIUDAD DE HUELVA
4CHNTRAWLERS216.545000412549331YUAN YU 886
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours mmsi ship_name\n", + "0 CHN TRAWLERS 31.888889 412444322 MIN LONG YU61146\n", + "1 SEN TRAWLERS 524.815556 663093000 AMINE\n", + "2 CHN TRAWLERS 0.368056 412209175 MENGXIN24\n", + "3 ESP TRAWLERS 1.306389 225987981 CIUDAD DE HUELVA\n", + "4 CHN TRAWLERS 216.545000 412549331 YUAN YU 886" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_report_df[[\"flag\", \"gear_type\", \"hours\", \"mmsi\", \"ship_name\"]].head()" + ] + }, + { + "cell_type": "markdown", + "id": "792a7b37-50c6-4218-afc9-1e2d1bcdfdb6", + "metadata": {}, + "source": [ + "### Explore Vessels Potentially Engaged in Trawling Activity in the Senegalese EEZ" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "c44d3d72-ebe5-4fe0-85fb-8e8675bd1922", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_agg_report_df = (\n", + " step_1_report_df.groupby([\"flag\", \"gear_type\", \"mmsi\", \"ship_name\"], as_index=False)\n", + " .agg(hours=(\"hours\", \"sum\"))\n", + " .sort_values(by=\"hours\", ascending=False)\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "545d63f0-e3b6-4e81-8c5c-55990eeec9b0", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typemmsiship_namehours
66SENTRAWLERS663178000NUEVONOSOLAR1678.888333
52SENTRAWLERS663115000BETTY1648.771944
49SENTRAWLERS663112000TADORNE1610.828611
42SENTRAWLERS663039000SEGUNDO SAN RAFAEL1595.538333
74SENTRAWLERS663250000PRAIA DA MAROSA1573.587500
\n", + "
" + ], + "text/plain": [ + " flag gear_type mmsi ship_name hours\n", + "66 SEN TRAWLERS 663178000 NUEVONOSOLAR 1678.888333\n", + "52 SEN TRAWLERS 663115000 BETTY 1648.771944\n", + "49 SEN TRAWLERS 663112000 TADORNE 1610.828611\n", + "42 SEN TRAWLERS 663039000 SEGUNDO SAN RAFAEL 1595.538333\n", + "74 SEN TRAWLERS 663250000 PRAIA DA MAROSA 1573.587500" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_agg_report_df.head()" + ] + }, + { + "cell_type": "markdown", + "id": "3f948958-ebce-4478-8b17-d6143c38956b", + "metadata": {}, + "source": [ + "### What We have Learned from Step 1" + ] + }, + { + "cell_type": "markdown", + "id": "7d51287d-263b-4ff5-a40a-5efa7e7ea0a4", + "metadata": {}, + "source": [ + "- There are vessels appear to have been engaged in potential trawling activity in Senegalese EEZ over the past 3 months i.e.,:\n", + " - `NUEVONOSOLAR (mmsi: 663178000, flag: SEN)`\n", + " - `BETTY (mmsi: 663115000, flag: SEN)`\n", + "- We will retrieve these vessels' `ownership`, `flag history`, and `authorizations` in **Step 2 to validate** them." + ] + }, + { + "cell_type": "markdown", + "id": "80289282-d160-4901-9bf8-a7996785c898", + "metadata": {}, + "source": [ + "## Step 2: Retrieve Vessel Details Using the Vessels API" + ] + }, + { + "cell_type": "markdown", + "id": "dcbde755-0e9c-48d9-babe-aaee3179b88d", + "metadata": {}, + "source": [ + "Mamadou queries the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** to **get detailed vessel identity and ownership records**. Please [learn more about Vessels API here](https://globalfishingwatch.org/our-apis/documentation#vessels-api) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)." + ] + }, + { + "cell_type": "markdown", + "id": "ba645e15-f111-48f3-96a4-7e091f27669e", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **Vessel IDs** from [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api), **Step 1 above**.\n", + "2. **[Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset)** - `public-global-vessel-identity:latest`.\n", + "3. **[Includes](https://globalfishingwatch.org/our-apis/documentation#get-vessels-by-ids-url-parameters)** - `POTENTIAL_RELATED_SELF_REPORTED_INFO`." + ] + }, + { + "cell_type": "markdown", + "id": "42a309da-6a56-46a0-aa86-2a148d21d855", + "metadata": {}, + "source": [ + "**Note:** Vessels may change identifiers over time, such as their `Maritime Mobile Service Identity (MMSI)`,` International Maritime Organization (IMO) number)`, `call sign`, or even their `name`. These changes can occur due to `re-registration`, `changes in ownership`, or other `operational reasons` within the `AIS transponder`. Parameter (`includes = POTENTIAL_RELATED_SELF_REPORTED_INFO`) helps group all **vessel ids** that are **potentially related** as part of the **same physical vessel** based on publicly available registry information." + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "5b507df7-99fe-4bb2-82da-7ed4ad4cfa8e", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_vessel_mmsis = list(step_1_agg_report_df[\"mmsi\"].head(n=2))" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "f87106f0-b2a0-482c-bd1f-d11119ee53a3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['663178000', '663115000']" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_vessel_mmsis" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "1eb89d2a-4d53-4d67-a668-0cbb233e950c", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_vessel_ids = list(\n", + " step_1_report_df[step_1_report_df[\"mmsi\"].isin(step_1_vessel_mmsis)][\n", + " \"vessel_id\"\n", + " ].unique()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "e670a688-3af0-410d-b93b-ec1e06ec4e09", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['894bc3ec6-6ade-f09c-e792-ff2e947508d8',\n", + " 'bf28c5a58-8c83-8690-8689-7f2d520f926e']" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_vessel_ids" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "428889bd-4761-4301-b21e-fbc37eba5622", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_vessels_result = await gfw_client.vessels.get_vessels_by_ids(\n", + " ids=step_1_vessel_ids,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "c64d68dc-b952-412f-827c-df5236c98bd7", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_vessels_df = step_2_vessels_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "757e6c3c-d0df-4b8f-839d-1e31518d42d7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 2 entries, 0 to 1\n", + "Data columns (total 7 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 dataset 2 non-null object\n", + " 1 registry_info_total_records 2 non-null int64 \n", + " 2 registry_info 2 non-null object\n", + " 3 registry_owners 2 non-null object\n", + " 4 registry_public_authorizations 2 non-null object\n", + " 5 combined_sources_info 2 non-null object\n", + " 6 self_reported_info 2 non-null object\n", + "dtypes: int64(1), object(6)\n", + "memory usage: 244.0+ bytes\n" + ] + } + ], + "source": [ + "step_2_vessels_df.info()" + ] + }, + { + "cell_type": "markdown", + "id": "7746d027-fb76-41dd-86e9-b949284ec19c", + "metadata": {}, + "source": [ + "**Understanding Vessel Details Response Data**\n", + "\n", + "- **registryInfoTotalRecords** – This represents the **number of registry records** found for the vessels.\n", + "- **registryInfo** – Contains **public registry data**. This data is sourced from official **vessel registries**.\n", + "- **registryOwners** – Lists the **registered owners** of the vessel based on public sources.\n", + "- **registryPublicAuthorizations** – Represents known **fishing authorizations** from public sources. Users should verify against national registries and RFMO records for additional context.\n", + "- **combinedSourcesInfo** – Provides inferred data from multiple sources, including. This is not explicitly reported by vessels but determined through **GFW's classification methods**.\n", + "- **selfReportedInfo** – Contains **AIS self-reported** data, including `MMSI`, `ship name`, and `flag` as broadcast by the **vessel itself**. Self-reported data may not always align with registry data and should be cross-checked." + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "4767e025-e26e-4a61-8971-8f2cc90385cc", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
registry_inforegistry_ownersself_reported_info
0[{'id': '199483471cd2da3717552fddb1a3172a', 's...[{'name': 'ARMEMENT SOPASEN', 'flag': 'SEN', '...[{'id': '894bc3ec6-6ade-f09c-e792-ff2e947508d8...
1[{'id': '29fef17154387858d8d4c777311c57f7', 's...[{'name': 'SENEVISA', 'flag': 'ESP', 'ssvid': ...[{'id': 'bf28c5a58-8c83-8690-8689-7f2d520f926e...
\n", + "
" + ], + "text/plain": [ + " registry_info \\\n", + "0 [{'id': '199483471cd2da3717552fddb1a3172a', 's... \n", + "1 [{'id': '29fef17154387858d8d4c777311c57f7', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'ARMEMENT SOPASEN', 'flag': 'SEN', '... \n", + "1 [{'name': 'SENEVISA', 'flag': 'ESP', 'ssvid': ... \n", + "\n", + " self_reported_info \n", + "0 [{'id': '894bc3ec6-6ade-f09c-e792-ff2e947508d8... \n", + "1 [{'id': 'bf28c5a58-8c83-8690-8689-7f2d520f926e... " + ] + }, + "execution_count": 18, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_vessels_df[[\"registry_info\", \"registry_owners\", \"self_reported_info\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "46760bde-049d-433c-817d-ae63b1c58924", + "metadata": {}, + "source": [ + "### Explore Vessels Registry Info" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "7efdc6d6-52d8-40bb-9537-e09f242fdb25", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_registry_info_df = pd.json_normalize(\n", + " step_2_vessels_df[\"registry_info\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "27ab60a9-6496-4406-9ae4-57a7aa97f6fa", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namegear_typessource_code
0663115000SENBETTYBETTY[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
1663178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
2762178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
3552178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name gear_types \\\n", + "0 663115000 SEN BETTY BETTY [TRAWLERS] \n", + "1 663178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "2 762178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "3 552178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "\n", + " source_code \n", + "0 [IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL] \n", + "1 [IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL] \n", + "2 [IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL] \n", + "3 [IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL] " + ] + }, + "execution_count": 20, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_registry_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"gear_types\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "db341dcf-c0a4-48df-bcc9-1e8fa78d3b25", + "metadata": {}, + "source": [ + "### Explore Registry Owners" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "24cec6f2-3e70-4396-a779-13ace779733f", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_registry_owners_df = pd.json_normalize(\n", + " step_2_vessels_df[\"registry_owners\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "16f804f4-ea4f-4a07-8c53-497e09deddfd", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagnamesource_code
0663115000SENARMEMENT SOPASEN[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
1663178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
2663176000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
3762178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
4552178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag name source_code\n", + "0 663115000 SEN ARMEMENT SOPASEN [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "1 663178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "2 663176000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "3 762178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "4 552178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]" + ] + }, + "execution_count": 22, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_registry_owners_df[[\"ssvid\", \"flag\", \"name\", \"source_code\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "7a22580f-7c7a-4181-9a80-e37687cc0471", + "metadata": {}, + "source": [ + "### Explore Vessels Self Reported Info" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "c2fa4bdd-1b51-4b37-abf5-aa18a1cab3e5", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_self_reported_info_df = pd.json_normalize(\n", + " step_2_vessels_df[\"self_reported_info\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "d1b559c7-4587-4019-a843-181017dd3f07", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namesource_code
0663115000SENBETTYBETTY[AIS]
1663178000SENNUEVONOSOLARNUEVONOSOLAR[AIS]
2663178000SENNUEVO=NOSOLAR+3&!U.?NUEVONOSOLAR3U[AIS]
3762178000NoneNUEVO NOSOLARNUEVONOSOLAR[AIS]
4552178000NoneNUEVO NOSOLARNUEVONOSOLAR[AIS]
5663178000SENNUEVO NOSOLARNUEVONOSOLAR[AIS]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name source_code\n", + "0 663115000 SEN BETTY BETTY [AIS]\n", + "1 663178000 SEN NUEVONOSOLAR NUEVONOSOLAR [AIS]\n", + "2 663178000 SEN NUEVO=NOSOLAR+3&!U.? NUEVONOSOLAR3U [AIS]\n", + "3 762178000 None NUEVO NOSOLAR NUEVONOSOLAR [AIS]\n", + "4 552178000 None NUEVO NOSOLAR NUEVONOSOLAR [AIS]\n", + "5 663178000 SEN NUEVO NOSOLAR NUEVONOSOLAR [AIS]" + ] + }, + "execution_count": 24, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_self_reported_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "6a6bcbcd-49a8-4575-9003-d8495deeb2d3", + "metadata": {}, + "source": [ + "### What We have Learned from Step 2" + ] + }, + { + "cell_type": "markdown", + "id": "53b4b694-b730-451c-b853-01485b6ca38c", + "metadata": {}, + "source": [ + "- **Vessel Identity:**\n", + " - `NUEVONOSOLAR (mmsi: 663178000, flag: SEN)`- appears to be registered under Senegal (SEN)\n", + " - `BETTY (mmsi: 663115000, flag: SEN)` - appears to be registered under Senegal (SEN)\n", + "- **Ownership & Historical Changes:**\n", + " - `NUEVONOSOLAR (mmsi: 663178000, flag: SEN)` - **SENEVISA** appears to be listed as the registered owner.\n", + " - `BETTY (mmsi: 663115000, flag: SEN)`- **ARMEMENT SOPASEN** appears to be listed as the registered owner." + ] + }, + { + "cell_type": "markdown", + "id": "e35fec91-477e-4fb5-99f2-766b3a5dbeff", + "metadata": {}, + "source": [ + "**Next Steps:**\n", + "\n", + "- Further, **validate ownership history** using official registry sources.\n", + "- Assess whether any **historical changes** in `flag`, `name`, or `ownership` are relevant for enforcement.\n", + "- Generate an **apparent activity report** with all available details." + ] + }, + { + "cell_type": "markdown", + "id": "8b951044-6905-4e38-9885-13a98cf3a7cf", + "metadata": {}, + "source": [ + "## Summary of API Flow" + ] + }, + { + "cell_type": "markdown", + "id": "c8f86731-be44-4b89-8abb-cf2f6693b4c9", + "metadata": {}, + "source": [ + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** - Retrieve apparent fishing effort for **trawlers** within Senegalese EEZ.\n", + "2. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** - Fetch detailed **vessel identity**, **ownership history**, and **public authorizations** for vessels detected in **Step 1**.\n", + "3. **Analyze vessel history** - Compare **registry records**, **AIS self-reported** data, and inferred information to identify potential flag-hopping or historical changes in vessel identity.\n", + "4. **Assess authorizations** - Cross-check whether vessels have publicly available fishing authorizations and consider external official sources for further verification.\n", + "5. **Generate an analysis report** - Provide enforcement authorities with a structured report highlighting vessel activity, identity records, and any notable discrepancies for further investigation." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez.ipynb b/notebooks/workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez.ipynb new file mode 100644 index 0000000..0953cfe --- /dev/null +++ b/notebooks/workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez.ipynb @@ -0,0 +1,2173 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "1b582ffc-7477-46c3-b5bf-2caf9d028bf2", + "metadata": {}, + "source": [ + "\"Open" + ] + }, + { + "cell_type": "markdown", + "id": "87eddf13-ac9c-45b0-ae10-24eb1620e07e", + "metadata": {}, + "source": [ + "# Analyze apparent fishing effort in Argentinian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "d79f0ab4-ab4d-4098-82b0-b6a5c772e101", + "metadata": {}, + "source": [ + "This guide provides detailed instructions to on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to **Analyze apparent fishing effort in [Argentinian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8466) region and monitor industrial trawlers** using **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)**, **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)**, and **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)**." + ] + }, + { + "cell_type": "markdown", + "id": "7ac25ecf-ffd7-40d7-9ea0-a6514c9fcd85", + "metadata": {}, + "source": [ + "**Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), 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." + ] + }, + { + "cell_type": "markdown", + "id": "71018cec-10c0-4619-9a7d-838a9f43cb15", + "metadata": {}, + "source": [ + "## Prerequisites" + ] + }, + { + "cell_type": "markdown", + "id": "996ca24b-99e4-4546-805b-697e4c2eb321", + "metadata": {}, + "source": [ + "Before using the `gfw-api-python-client`, ensure it is installed (see the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html) guide) and that you have obtained an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)." + ] + }, + { + "cell_type": "markdown", + "id": "6be16f6f-19fc-4d19-a0ed-ba370c844fa6", + "metadata": {}, + "source": [ + "## Installation" + ] + }, + { + "cell_type": "markdown", + "id": "af48cf4e-e24c-47aa-a2c5-64cf87be9c33", + "metadata": {}, + "source": [ + "The `gfw-api-python-client` can be easily installed using pip:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "88c09924-87d2-4c86-ad60-aed623416193", + "metadata": {}, + "outputs": [], + "source": [ + "# %pip install gfw-api-python-client" + ] + }, + { + "cell_type": "markdown", + "id": "eafaa9d1-2143-452c-813c-75b21fd2198c", + "metadata": {}, + "source": [ + "## Usage" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "cc98323c-c9e4-401c-8f26-f551968c003a", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "import datetime\n", + "import pandas as pd\n", + "import gfwapiclient as gfw" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "047ff069-3c87-47fe-bb4a-acb920df2137", + "metadata": {}, + "outputs": [], + "source": [ + "try:\n", + " from google.colab import userdata\n", + "\n", + " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", + "except Exception as exc:\n", + " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", + "\n", + "access_token = access_token or \"\"" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "708e137f-6aa0-461e-b1af-33512a2093fc", + "metadata": {}, + "outputs": [], + "source": [ + "gfw_client = gfw.Client(\n", + " access_token=access_token,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b08a0e2c-3b9d-4c5e-b3a0-a5663fa32637", + "metadata": {}, + "source": [ + "## Introduction" + ] + }, + { + "cell_type": "markdown", + "id": "62fe47aa-ed77-4815-b08d-8c96f2480b04", + "metadata": {}, + "source": [ + "**Use Case: A Fisheries Enforcement Officer Monitoring Industrial Trawlers**" + ] + }, + { + "cell_type": "markdown", + "id": "5109f67f-aaae-4a7d-9a15-4db740542694", + "metadata": {}, + "source": [ + "Maria, a fisheries enforcement officer in Argentina, monitors industrial trawlers operating within **[Argentinian Exclusive Economic Zone (EEZ)](https://www.marineregions.org/gazetteer.php?p=details&id=8466)**. His goal is to:\n", + "\n", + "1. Analyzing apparent fishing effort for **trawlers** operating in Argentinian EEZ.\n", + "2. Identifying vessels involved in **apparent trawling activity** and determining their reported **flag states**.\n", + "3. Checking vessel history, including **potential transshipment** and **port visits**.\n", + "4. Generating reports to support fisheries enforcement decisions." + ] + }, + { + "cell_type": "markdown", + "id": "b16b1b52-6b68-494a-9d76-ca7a7ab485a0", + "metadata": {}, + "source": [ + "**APIs Used:**\n", + "️\n", + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** – Retrieve **apparent fishing effort** data for trawlers.\n", + "2. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** – Group vessels by ID that are involved in **trawling activity**.\n", + "3. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** – Retrieve **vessel identity** & **ownership** details.\n", + "4. **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)** – Fetch **port visits** & **potential transshipment** history. " + ] + }, + { + "cell_type": "markdown", + "id": "c93924be-f36e-4f6c-830f-4d06c03d08f7", + "metadata": {}, + "source": [ + "**Important:** In order to avoid any misinterpretation of **GFW data**, please refer to our official **data caveats** documentations:\n", + "- [Apparent fishing effort](https://globalfishingwatch.org/dataset-and-code-fishing-effort/) \n", + "- [Exclusive economic zone boundaries definition](https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition)\n", + "- [Vessel ID](https://globalfishingwatch.org/our-apis/documentation#vessel-id)\n", + "- [Vessel API - Vessel identity information](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)" + ] + }, + { + "cell_type": "markdown", + "id": "01169672-36d5-4b2b-969d-471070d75f8c", + "metadata": {}, + "source": [ + "**Important Caveats:**\n", + "\n", + "1. The [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api) only supports **one active report per user at a time**.\n", + "2. **Sending multiple requests simultaneously** results in a **429 Too Many Requests** error.\n", + "3. If a report takes over **100 seconds** to generate, it may return a **524 Gateway Timeout** error." + ] + }, + { + "cell_type": "markdown", + "id": "2c1e1858-c328-4719-8f10-40ae5b43ecb0", + "metadata": {}, + "source": [ + "## Step 0: Identify the Region of Interest (ROI) - Argentinian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "88789a27-1e15-44af-ba81-7d07ded02e4b", + "metadata": {}, + "source": [ + "Before making API requests, Maria must specify the geographic area for analysis using a **Region ID**:" + ] + }, + { + "cell_type": "markdown", + "id": "75a985b1-3803-48d9-b2f3-f12b29bd29e7", + "metadata": {}, + "source": [ + "**Options to Define the Region:**\n", + "\n", + "1. **Using Region ID** - Each EEZ has a unique ID in the **[public-eez-areas](https://globalfishingwatch.org/our-apis/documentation#regions)** dataset.\n", + "2. **Custom Geometries** - Users can define a custom area using GeoJSON.\n", + " \n", + "For **[Argentinian EEZ, the region ID is 8466](https://www.marineregions.org/gazetteer.php?p=details&id=8466)** (public-eez-areas dataset)." + ] + }, + { + "cell_type": "markdown", + "id": "35a0691d-b747-48e6-8b02-5c2f54a5d536", + "metadata": {}, + "source": [ + "## Step 1: Retrieve Apparent Fishing Effort in Argentinian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "d57cd039-a667-44f7-b785-8d0e50530333", + "metadata": {}, + "source": [ + "Maria **first queries** the **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** to get **apparent fishing effort for all vessels**, grouping them by **gear type** in **[Argentinian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8466)**. Please [learn more about apparent fishing effort here](https://globalfishingwatch.org/our-apis/documentation#ais-apparent-fishing-effort) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort)." + ] + }, + { + "cell_type": "markdown", + "id": "6229af14-613a-4809-96f5-9cb3d6bd3461", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **[Region ID](https://globalfishingwatch.org/our-apis/documentation#regions)** - 8466 Argentinian EEZ\n", + "2. **[Date Range](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Last 6 Months\n", + "3. **[Grouped By](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Gear Type" + ] + }, + { + "cell_type": "markdown", + "id": "b945aa10-40c3-490a-84e7-89092badd783", + "metadata": {}, + "source": [ + "**Why This Step?**\n", + "\n", + "- Identifies which gear types (e.g., `trawlers`, `squid jiggers` etc.) are most active in the Argentinian EEZ.\n", + "- Establishes baseline fishing activity trends before narrowing the search to specific vessels." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "62b9b9e5-4170-40d0-9aef-7579beb89bc0", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", + " spatial_resolution=\"HIGH\",\n", + " group_by=\"GEARTYPE\",\n", + " temporal_resolution=\"MONTHLY\",\n", + " start_date=\"2024-08-01\",\n", + " end_date=\"2025-01-31\",\n", + " spatial_aggregation=True,\n", + " region={\n", + " \"dataset\": \"public-eez-areas\",\n", + " \"id\": \"8466\",\n", + " },\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "4d6190fc-a8fa-4d59-914e-ebae41943381", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_df = step_1_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "d98ca51f-bb46-4edc-9a61-3e26c56bbcc8", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 40 entries, 0 to 39\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 40 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 0 non-null object \n", + " 3 gear_type 40 non-null object \n", + " 4 hours 40 non-null float64\n", + " 5 vessel_ids 40 non-null int64 \n", + " 6 vessel_id 0 non-null object \n", + " 7 vessel_type 0 non-null object \n", + " 8 entry_timestamp 0 non-null object \n", + " 9 exit_timestamp 0 non-null object \n", + " 10 first_transmission_date 0 non-null object \n", + " 11 last_transmission_date 0 non-null object \n", + " 12 imo 0 non-null object \n", + " 13 mmsi 0 non-null object \n", + " 14 call_sign 0 non-null object \n", + " 15 dataset 0 non-null object \n", + " 16 report_dataset 40 non-null object \n", + " 17 ship_name 0 non-null object \n", + " 18 lat 0 non-null object \n", + " 19 lon 0 non-null object \n", + "dtypes: float64(1), int64(1), object(18)\n", + "memory usage: 6.4+ KB\n" + ] + } + ], + "source": [ + "step_1_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "ce844c77-6cf0-4648-bdfb-3a72589c0785", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
gear_typehoursvessel_ids
0inconclusive215.6238892
1set_longlines17.9258331
2inconclusive98.1558332
3other_purse_seines57.3775001
4set_longlines153.9602783
\n", + "
" + ], + "text/plain": [ + " gear_type hours vessel_ids\n", + "0 inconclusive 215.623889 2\n", + "1 set_longlines 17.925833 1\n", + "2 inconclusive 98.155833 2\n", + "3 other_purse_seines 57.377500 1\n", + "4 set_longlines 153.960278 3" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_report_df[[\"gear_type\", \"hours\", \"vessel_ids\"]].head()" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "45319c2a-e82e-4a9a-8a2d-2ea6d9cdada4", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_agg_report_df = (\n", + " step_1_report_df.groupby([\"gear_type\"], as_index=False)\n", + " .agg(hours=(\"hours\", \"sum\"), vessel_ids=(\"vessel_ids\", \"sum\"))\n", + " .sort_values(by=\"hours\", ascending=False)\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "121465c6-65ef-4efa-9d8a-4a0a136564bd", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
gear_typehoursvessel_ids
8trawlers240642.4144441315
1fishing16023.20138994
7squid_jigger6124.06222244
2fixed_gear1948.32555616
3inconclusive1072.35138914
\n", + "
" + ], + "text/plain": [ + " gear_type hours vessel_ids\n", + "8 trawlers 240642.414444 1315\n", + "1 fishing 16023.201389 94\n", + "7 squid_jigger 6124.062222 44\n", + "2 fixed_gear 1948.325556 16\n", + "3 inconclusive 1072.351389 14" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_agg_report_df.head()" + ] + }, + { + "cell_type": "markdown", + "id": "449828f2-dda7-422c-8cfb-770ced828ca6", + "metadata": {}, + "source": [ + "### What We have Learned from Step 1" + ] + }, + { + "cell_type": "markdown", + "id": "e83e24d9-edb1-45d3-af4a-fa60b155ecab", + "metadata": {}, + "source": [ + "- Multiple **gear types** were potentially detected in Argentinian EEZ.\n", + "- `Trawlers` appear to be operating, but further **vessel-level investigation** is needed." + ] + }, + { + "cell_type": "markdown", + "id": "6fe5edf3-8e96-4147-8c59-a6bc8982662d", + "metadata": {}, + "source": [ + "## Step 2: Retrieve Vessel IDs for Trawlers" + ] + }, + { + "cell_type": "markdown", + "id": "4bede3c0-3d01-4661-8b88-467244417d20", + "metadata": {}, + "source": [ + "Maria refines her **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** request to group by **vessel ID**, and filtering only for **trawlers** in **[Argentinian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8466)**. Please [learn more about apparent fishing effort here](https://globalfishingwatch.org/our-apis/documentation#ais-apparent-fishing-effort) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort)." + ] + }, + { + "cell_type": "markdown", + "id": "2e2e42d9-1b9e-4115-b601-72d0e86ab91d", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **[Region ID](https://globalfishingwatch.org/our-apis/documentation#regions)** - [8466 Argentinian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8466)\n", + "2. **[Date Range](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Last 6 Months\n", + "3. **[Grouped By](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Vessel ID\n", + "4. **[Gear Type](https://globalfishingwatch.org/our-apis/documentation#gear-types-supported)** - Trawlers " + ] + }, + { + "cell_type": "markdown", + "id": "849f6157-fa79-456f-8974-d294c77a0729", + "metadata": {}, + "source": [ + "**Why Use group-by=VESSEL_ID?**\n", + "\n", + "Grouping by **VESSEL_ID** allows **individual vessel identification** in the response. This is crucial for **tracking vessel activity** and, more importantly, linking each detected vessel to the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** in the next step. By structuring the query this way, we can fetch vessel details such as **flag, name, and ownership records** in **Step 3 below**.\n" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "db35d1b2-ba32-4a58-97f3-17059b3de164", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", + " spatial_resolution=\"HIGH\",\n", + " group_by=\"VESSEL_ID\",\n", + " temporal_resolution=\"ENTIRE\",\n", + " filters=[\"geartype in ('trawlers')\"],\n", + " start_date=\"2024-08-01\",\n", + " end_date=\"2025-01-31\",\n", + " spatial_aggregation=True,\n", + " region={\n", + " \"dataset\": \"public-eez-areas\",\n", + " \"id\": \"8466\",\n", + " },\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "301f888e-3b7e-4946-a7aa-496e05b53cbd", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_report_df = step_2_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "866f84fb-50c4-47e2-95fa-43fbc06d17cd", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 385 entries, 0 to 384\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 385 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 385 non-null object \n", + " 3 gear_type 385 non-null object \n", + " 4 hours 385 non-null float64 \n", + " 5 vessel_ids 0 non-null object \n", + " 6 vessel_id 385 non-null object \n", + " 7 vessel_type 385 non-null object \n", + " 8 entry_timestamp 385 non-null datetime64[ns, UTC]\n", + " 9 exit_timestamp 385 non-null datetime64[ns, UTC]\n", + " 10 first_transmission_date 385 non-null datetime64[ns, UTC]\n", + " 11 last_transmission_date 385 non-null datetime64[ns, UTC]\n", + " 12 imo 385 non-null object \n", + " 13 mmsi 385 non-null object \n", + " 14 call_sign 385 non-null object \n", + " 15 dataset 385 non-null object \n", + " 16 report_dataset 385 non-null object \n", + " 17 ship_name 385 non-null object \n", + " 18 lat 0 non-null object \n", + " 19 lon 0 non-null object \n", + "dtypes: datetime64[ns, UTC](4), float64(1), object(15)\n", + "memory usage: 60.3+ KB\n" + ] + } + ], + "source": [ + "step_2_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "82a786a1-c437-430e-aeb5-f61d02a5f900", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typehoursmmsiship_name
0URYTRAWLERS10.023056770576463KALATXORI
1ARGTRAWLERS326.160833701079000ENTRENA UNO
2ARGTRAWLERS714.842500701000882FELIX AUGUSTO
3ARGTRAWLERS641.522222701000932ANTONIO ALVAREZ
4ARGTRAWLERS295.007500701000820CORAJE
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours mmsi ship_name\n", + "0 URY TRAWLERS 10.023056 770576463 KALATXORI\n", + "1 ARG TRAWLERS 326.160833 701079000 ENTRENA UNO\n", + "2 ARG TRAWLERS 714.842500 701000882 FELIX AUGUSTO\n", + "3 ARG TRAWLERS 641.522222 701000932 ANTONIO ALVAREZ\n", + "4 ARG TRAWLERS 295.007500 701000820 CORAJE" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_report_df[[\"flag\", \"gear_type\", \"hours\", \"mmsi\", \"ship_name\"]].head()" + ] + }, + { + "cell_type": "markdown", + "id": "630d95dd-8f82-407f-b223-f55e981e3593", + "metadata": {}, + "source": [ + "### Explore Vessels Potentially Engaged in Trawling Activity in the Argentinian EEZ" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "984052a3-3920-4fce-8894-4b67af4a8a69", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_agg_report_df = (\n", + " step_2_report_df.groupby([\"flag\", \"gear_type\", \"mmsi\", \"ship_name\"], as_index=False)\n", + " .agg(hours=(\"hours\", \"sum\"))\n", + " .sort_values(by=\"hours\", ascending=False)\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "83e4dafb-4491-40c9-9f4d-f4cc1e2b7766", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typemmsiship_namehours
297ARGTRAWLERS701024000ATLANTIC SURF III3151.855278
247ARGTRAWLERS701006605CAPESANTE2270.097500
22ARGTRAWLERS701000577MISS TIDE2244.895833
296ARGTRAWLERS701023000CAROLINA P2065.586944
301ARGTRAWLERS701037000DON PEDRO1807.146111
\n", + "
" + ], + "text/plain": [ + " flag gear_type mmsi ship_name hours\n", + "297 ARG TRAWLERS 701024000 ATLANTIC SURF III 3151.855278\n", + "247 ARG TRAWLERS 701006605 CAPESANTE 2270.097500\n", + "22 ARG TRAWLERS 701000577 MISS TIDE 2244.895833\n", + "296 ARG TRAWLERS 701023000 CAROLINA P 2065.586944\n", + "301 ARG TRAWLERS 701037000 DON PEDRO 1807.146111" + ] + }, + "execution_count": 16, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_agg_report_df.head()" + ] + }, + { + "cell_type": "markdown", + "id": "3f948958-ebce-4478-8b17-d6143c38956b", + "metadata": {}, + "source": [ + "### What We have Learned from Step 2" + ] + }, + { + "cell_type": "markdown", + "id": "d4fb7cba-a577-45fe-88fa-8e5001bb9869", + "metadata": {}, + "source": [ + "- There are vessels appear to have been engaged in potential trawling activity in Argentinian EEZ over the past 6 months i.e.,:\n", + " - `ATLANTIC SURF III (mmsi: 701024000, flag: ARG)`\n", + " - `CAPESANTE (mmsi: 701006605, flag: ARG)`\n", + "- We will retrieve these vessels' `ownership`, `flag history`, and `authorizations` in **Step 3 to validate** them." + ] + }, + { + "cell_type": "markdown", + "id": "80289282-d160-4901-9bf8-a7996785c898", + "metadata": {}, + "source": [ + "## Step 3: Retrieve Vessel Details Using the Vessels API" + ] + }, + { + "cell_type": "markdown", + "id": "dcbde755-0e9c-48d9-babe-aaee3179b88d", + "metadata": {}, + "source": [ + "Maria queries the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** to **get detailed vessel identity and ownership records**. Please [learn more about Vessels API here](https://globalfishingwatch.org/our-apis/documentation#vessels-api) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)." + ] + }, + { + "cell_type": "markdown", + "id": "ba645e15-f111-48f3-96a4-7e091f27669e", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **Vessel IDs** from [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api), **Step 2 above**.\n", + "2. **[Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset)** - `public-global-vessel-identity:latest`.\n", + "3. **[Includes](https://globalfishingwatch.org/our-apis/documentation#get-vessels-by-ids-url-parameters)** - `POTENTIAL_RELATED_SELF_REPORTED_INFO`." + ] + }, + { + "cell_type": "markdown", + "id": "42a309da-6a56-46a0-aa86-2a148d21d855", + "metadata": {}, + "source": [ + "**Note:** Vessels may change identifiers over time, such as their `Maritime Mobile Service Identity (MMSI)`,` International Maritime Organization (IMO) number)`, `call sign`, or even their `name`. These changes can occur due to `re-registration`, `changes in ownership`, or other `operational reasons` within the `AIS transponder`. Parameter (`includes = POTENTIAL_RELATED_SELF_REPORTED_INFO`) helps group all **vessel ids** that are **potentially related** as part of the **same physical vessel** based on publicly available registry information." + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "24e8452f-7848-4c88-89db-66e4bf182cd1", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_vessel_mmsis = list(step_2_agg_report_df[\"mmsi\"].head(n=2))" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "f25ceec0-3188-4584-bb95-f76c9e0ac578", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['701024000', '701006605']" + ] + }, + "execution_count": 18, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_vessel_mmsis" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "446b506a-a19f-49cd-9110-ed8b9103af8b", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_vessel_ids = list(\n", + " step_2_report_df[step_2_report_df[\"mmsi\"].isin(step_2_vessel_mmsis)][\n", + " \"vessel_id\"\n", + " ].unique()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "6233b1eb-ed4b-4ba9-bce8-faa1ee027dcc", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['de8a03acd-dc6c-8e08-2867-24e55ffc0017',\n", + " '8e930bac5-594b-aa3f-081d-d12668819e1f']" + ] + }, + "execution_count": 20, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_vessel_ids" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "428889bd-4761-4301-b21e-fbc37eba5622", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_vessels_result = await gfw_client.vessels.get_vessels_by_ids(\n", + " ids=step_2_vessel_ids,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "c64d68dc-b952-412f-827c-df5236c98bd7", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_vessels_df = step_3_vessels_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "757e6c3c-d0df-4b8f-839d-1e31518d42d7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 2 entries, 0 to 1\n", + "Data columns (total 7 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 dataset 2 non-null object\n", + " 1 registry_info_total_records 2 non-null int64 \n", + " 2 registry_info 2 non-null object\n", + " 3 registry_owners 2 non-null object\n", + " 4 registry_public_authorizations 2 non-null object\n", + " 5 combined_sources_info 2 non-null object\n", + " 6 self_reported_info 2 non-null object\n", + "dtypes: int64(1), object(6)\n", + "memory usage: 244.0+ bytes\n" + ] + } + ], + "source": [ + "step_3_vessels_df.info()" + ] + }, + { + "cell_type": "markdown", + "id": "c2d30f1a-352b-42cb-8ee8-acd67f16103f", + "metadata": {}, + "source": [ + "**Understanding Vessel Details Response Data**\n", + "\n", + "- **registryInfoTotalRecords** – This represents the **number of registry records** found for the vessels.\n", + "- **registryInfo** – Contains **public registry data**. This data is sourced from official **vessel registries**.\n", + "- **registryOwners** – Lists the **registered owners** of the vessel based on public sources.\n", + "- **registryPublicAuthorizations** – Represents known **fishing authorizations** from public sources. Users should verify against national registries and RFMO records for additional context.\n", + "- **combinedSourcesInfo** – Provides inferred data from multiple sources, including. This is not explicitly reported by vessels but determined through **GFW's classification methods**.\n", + "- **selfReportedInfo** – Contains **AIS self-reported** data, including `MMSI`, `ship name`, and `flag` as broadcast by the **vessel itself**. Self-reported data may not always align with registry data and should be cross-checked." + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "4767e025-e26e-4a61-8971-8f2cc90385cc", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
registry_inforegistry_ownersself_reported_info
0[{'id': '45502524c9a150e77869ee647423dba1', 's...[{'name': 'GLACIAR PESQUERA', 'flag': 'ARG', '...[{'id': '8e930bac5-594b-aa3f-081d-d12668819e1f...
1[{'id': '2d939efefd3f45788ed103ff0723f564', 's...[{'name': 'CLEARWATER SEAFOODS', 'flag': 'CAN'...[{'id': 'de8a03acd-dc6c-8e08-2867-24e55ffc0017...
\n", + "
" + ], + "text/plain": [ + " registry_info \\\n", + "0 [{'id': '45502524c9a150e77869ee647423dba1', 's... \n", + "1 [{'id': '2d939efefd3f45788ed103ff0723f564', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'GLACIAR PESQUERA', 'flag': 'ARG', '... \n", + "1 [{'name': 'CLEARWATER SEAFOODS', 'flag': 'CAN'... \n", + "\n", + " self_reported_info \n", + "0 [{'id': '8e930bac5-594b-aa3f-081d-d12668819e1f... \n", + "1 [{'id': 'de8a03acd-dc6c-8e08-2867-24e55ffc0017... " + ] + }, + "execution_count": 24, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_vessels_df[[\"registry_info\", \"registry_owners\", \"self_reported_info\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "46760bde-049d-433c-817d-ae63b1c58924", + "metadata": {}, + "source": [ + "### Explore Vessels Registry Info" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "7efdc6d6-52d8-40bb-9537-e09f242fdb25", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_registry_info_df = pd.json_normalize(\n", + " step_3_vessels_df[\"registry_info\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "27ab60a9-6496-4406-9ae4-57a7aa97f6fa", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namegear_typessource_code
0701024000ARGATLANTIC SURF IIIATLANTICSURF3[TRAWLERS][IMO, TMT_OTHER_OFFICIAL]
1701006605ARGCAPESANTECAPESANTE[TRAWLERS][GFW-REVIEW, IMO, RESEARCH-PAPER, TMT_OTHER_OF...
2316003980CANATLANTICLEADERATLANTICLEADER[TRAWLERS][IMO, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name gear_types \\\n", + "0 701024000 ARG ATLANTIC SURF III ATLANTICSURF3 [TRAWLERS] \n", + "1 701006605 ARG CAPESANTE CAPESANTE [TRAWLERS] \n", + "2 316003980 CAN ATLANTICLEADER ATLANTICLEADER [TRAWLERS] \n", + "\n", + " source_code \n", + "0 [IMO, TMT_OTHER_OFFICIAL] \n", + "1 [GFW-REVIEW, IMO, RESEARCH-PAPER, TMT_OTHER_OF... \n", + "2 [IMO, TMT_OTHER_OFFICIAL] " + ] + }, + "execution_count": 26, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_registry_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"gear_types\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "5787e4ee-69e0-4769-ba05-9a57254c7289", + "metadata": {}, + "source": [ + "### Explore Registry Owners" + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "afe07c2a-81cb-45b3-9e86-c23b4ef67fe9", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_registry_owners_df = pd.json_normalize(\n", + " step_3_vessels_df[\"registry_owners\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "df7e0b65-0ab0-4722-aaec-3d11c7674b8f", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagnamesource_code
0701024000ARGGLACIAR PESQUERA[TMT_OTHER_OFFICIAL]
1701006605CANCLEARWATER SEAFOODS[RESEARCH-PAPER]
2316003980CANCS MANPAR[TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag name source_code\n", + "0 701024000 ARG GLACIAR PESQUERA [TMT_OTHER_OFFICIAL]\n", + "1 701006605 CAN CLEARWATER SEAFOODS [RESEARCH-PAPER]\n", + "2 316003980 CAN CS MANPAR [TMT_OTHER_OFFICIAL]" + ] + }, + "execution_count": 28, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_registry_owners_df[[\"ssvid\", \"flag\", \"name\", \"source_code\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "7a22580f-7c7a-4181-9a80-e37687cc0471", + "metadata": {}, + "source": [ + "### Explore Vessels Self Reported Info" + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "c2fa4bdd-1b51-4b37-abf5-aa18a1cab3e5", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_self_reported_info_df = pd.json_normalize(\n", + " step_3_vessels_df[\"self_reported_info\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "d1b559c7-4587-4019-a843-181017dd3f07", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namesource_code
0701024000ARGATLANTIC SURF IIIATLANTICSURF3[AIS]
1701006605ARGCAPESANTECAPESANTE[AIS]
2316003980CANATLANTIC LEADERATLANTICLEADER[AIS]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name source_code\n", + "0 701024000 ARG ATLANTIC SURF III ATLANTICSURF3 [AIS]\n", + "1 701006605 ARG CAPESANTE CAPESANTE [AIS]\n", + "2 316003980 CAN ATLANTIC LEADER ATLANTICLEADER [AIS]" + ] + }, + "execution_count": 30, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_self_reported_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "6a6bcbcd-49a8-4575-9003-d8495deeb2d3", + "metadata": {}, + "source": [ + "### What We have Learned from Step 3" + ] + }, + { + "cell_type": "markdown", + "id": "da9c80ea-94d7-4945-8e90-9f5ec4bad8f1", + "metadata": {}, + "source": [ + "- **Vessel Identity:**\n", + " - `ATLANTIC SURF III (mmsi: 701024000, flag: ARG)`- appears to be registered under Argentina (ARG)\n", + " - `CAPESANTE (mmsi: 701006605, flag: ARG)` - appears to be registered under Argentina (ARG)\n", + "- **Ownership & Historical Changes:**\n", + " - `ATLANTIC SURF III (mmsi: 701024000, flag: ARG)` - **GLACIAR PESQUERA** appears to be listed as the registered owner.\n", + " - `CAPESANTE (mmsi: 701006605, flag: ARG)`- **CLEARWATER SEAFOODS** appears to be listed as the registered owner." + ] + }, + { + "cell_type": "markdown", + "id": "4803ae37-3f96-40dc-8db8-690b51710735", + "metadata": {}, + "source": [ + "## Step 4: Detect Potential Port Visits, Encounters, or Fishing Events" + ] + }, + { + "cell_type": "markdown", + "id": "058cc09a-64dc-4913-a90c-cadc7d38439a", + "metadata": {}, + "source": [ + "Now Maria checks `port visits`, `encounters`, and `fishing events` using the **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)**, which allows **monitoring of vessel activities** such as `potential transshipments`, `unauthorized port entries`, or `fishing activity patterns`." + ] + }, + { + "cell_type": "markdown", + "id": "c8ee8f1c-7e5e-487f-ba45-7f7f609ba389", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **Vessel ID** from 4Wings API\n", + "2. **[Event Types](https://globalfishingwatch.org/our-apis/documentation#events-post-body-parameters)** - Port visits, encounters (potential transshipment), and fishing events.\n", + "3. **Time Range** - Last 6 months.\n", + "4. **[Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset)**:\n", + " - `public-global-port-visits-events::latest` (Port Visits)\n", + " - `public-global-encounters-events:latest` (Encounters between vessels)\n", + " - `public-global-fishing-events:latest` (Fishing activity)\n", + "5. **[Encounter Types](https://globalfishingwatch.org/our-apis/documentation#events-post-body-parameters)** - CARRIER-FISHING" + ] + }, + { + "cell_type": "code", + "execution_count": 31, + "id": "87c3b592-e431-457c-a5f4-5ce07711d52f", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_events_result = await gfw_client.events.get_all_events(\n", + " datasets=[\n", + " \"public-global-encounters-events:latest\",\n", + " \"public-global-fishing-events:latest\",\n", + " \"public-global-port-visits-events:latest\",\n", + " ],\n", + " vessels=step_2_vessel_ids,\n", + " types=[\"ENCOUNTER\", \"FISHING\", \"PORT_VISIT\"],\n", + " start_date=\"2024-08-01\",\n", + " end_date=\"2025-01-31\",\n", + " encounter_types=[\"CARRIER-FISHING\"],\n", + " sort=\"-start\",\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 32, + "id": "64cb0776-7f0d-481e-be98-da00b448c720", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_events_df = step_4_events_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "id": "4c82d647-3870-4a54-979b-7f586575e5c1", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 359 entries, 0 to 358\n", + "Data columns (total 14 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 start 359 non-null datetime64[ns, UTC]\n", + " 1 end 359 non-null datetime64[ns, UTC]\n", + " 2 id 359 non-null object \n", + " 3 type 359 non-null object \n", + " 4 position 359 non-null object \n", + " 5 regions 359 non-null object \n", + " 6 bounding_box 359 non-null object \n", + " 7 distances 359 non-null object \n", + " 8 vessel 359 non-null object \n", + " 9 encounter 0 non-null object \n", + " 10 fishing 351 non-null object \n", + " 11 gap 0 non-null object \n", + " 12 loitering 0 non-null object \n", + " 13 port_visit 8 non-null object \n", + "dtypes: datetime64[ns, UTC](2), object(12)\n", + "memory usage: 39.4+ KB\n" + ] + } + ], + "source": [ + "step_4_events_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 34, + "id": "17d89920-cda2-497d-9797-1e05a84a0daa", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "type\n", + "fishing 351\n", + "port_visit 8\n", + "Name: count, dtype: int64" + ] + }, + "execution_count": 34, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_events_df[\"type\"].value_counts()" + ] + }, + { + "cell_type": "markdown", + "id": "1b472de1-8fef-41a1-a76c-057406d86ee1", + "metadata": {}, + "source": [ + "### Explore Apparent Fishing Events" + ] + }, + { + "cell_type": "code", + "execution_count": 35, + "id": "4d360bc4-9762-4ae6-b5b1-1b937e2d2ed0", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_fishing_events_df = step_4_events_df[step_4_events_df[\"fishing\"].notna()]" + ] + }, + { + "cell_type": "code", + "execution_count": 36, + "id": "18ff38d6-9442-4742-9dc9-accfb1299e43", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_fishing_df = pd.concat(\n", + " [\n", + " pd.json_normalize(step_4_fishing_events_df[\"vessel\"], sep=\"_\"),\n", + " pd.json_normalize(step_4_fishing_events_df[\"fishing\"], sep=\"_\"),\n", + " ],\n", + " axis=1,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "id": "fc6ebae0-eba2-4a8a-892c-6dfc38822bd7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 351 entries, 0 to 350\n", + "Data columns (total 12 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 351 non-null object \n", + " 1 name 351 non-null object \n", + " 2 ssvid 351 non-null object \n", + " 3 flag 351 non-null object \n", + " 4 type 351 non-null object \n", + " 5 public_authorizations 351 non-null object \n", + " 6 nextPort 0 non-null object \n", + " 7 total_distance_km 351 non-null float64\n", + " 8 average_speed_knots 351 non-null float64\n", + " 9 average_duration_hours 0 non-null object \n", + " 10 potential_risk 351 non-null bool \n", + " 11 vessel_public_authorization_status 351 non-null object \n", + "dtypes: bool(1), float64(2), object(9)\n", + "memory usage: 30.6+ KB\n" + ] + } + ], + "source": [ + "step_4_fishing_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 38, + "id": "8799e988-56a2-41d5-b472-bc83064e1807", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
namessvidtotal_distance_kmaverage_speed_knots
0ATLANTIC SURF III701024000117.5454504.351747
1ATLANTIC SURF III70102400010.4088513.791667
2ATLANTIC SURF III70102400061.3669114.448980
3ATLANTIC SURF III70102400092.1807044.485407
4ATLANTIC SURF III701024000974.7618714.051429
...............
346CAPESANTE70100660595.1280594.202542
347CAPESANTE701006605205.8262824.136848
348CAPESANTE701006605369.3366033.938255
349ATLANTIC SURF III701024000256.9088424.186333
350CAPESANTE701006605208.0719853.971505
\n", + "

351 rows × 4 columns

\n", + "
" + ], + "text/plain": [ + " name ssvid total_distance_km average_speed_knots\n", + "0 ATLANTIC SURF III 701024000 117.545450 4.351747\n", + "1 ATLANTIC SURF III 701024000 10.408851 3.791667\n", + "2 ATLANTIC SURF III 701024000 61.366911 4.448980\n", + "3 ATLANTIC SURF III 701024000 92.180704 4.485407\n", + "4 ATLANTIC SURF III 701024000 974.761871 4.051429\n", + ".. ... ... ... ...\n", + "346 CAPESANTE 701006605 95.128059 4.202542\n", + "347 CAPESANTE 701006605 205.826282 4.136848\n", + "348 CAPESANTE 701006605 369.336603 3.938255\n", + "349 ATLANTIC SURF III 701024000 256.908842 4.186333\n", + "350 CAPESANTE 701006605 208.071985 3.971505\n", + "\n", + "[351 rows x 4 columns]" + ] + }, + "execution_count": 38, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_fishing_df[\n", + " [\n", + " \"name\",\n", + " \"ssvid\",\n", + " \"total_distance_km\",\n", + " \"average_speed_knots\",\n", + " ]\n", + "]" + ] + }, + { + "cell_type": "code", + "execution_count": 39, + "id": "3659c048-c8bf-463c-a6cb-fc29f818ed77", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "ssvid\n", + "701024000 245\n", + "701006605 106\n", + "Name: count, dtype: int64" + ] + }, + "execution_count": 39, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_fishing_df[\"ssvid\"].value_counts()" + ] + }, + { + "cell_type": "markdown", + "id": "5da05a04-947e-4f87-b61e-bad015796e5f", + "metadata": {}, + "source": [ + "### Explore Port Visit Events" + ] + }, + { + "cell_type": "code", + "execution_count": 40, + "id": "e806616b-6ed7-4c0c-9bf4-2b4a23de2046", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_port_visit_events_df = step_4_events_df[step_4_events_df[\"port_visit\"].notna()]" + ] + }, + { + "cell_type": "code", + "execution_count": 41, + "id": "58a68605-9432-43fe-b8eb-4d0393f95f60", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_port_visits_df = pd.concat(\n", + " [\n", + " pd.json_normalize(step_4_port_visit_events_df[\"vessel\"], sep=\"_\"),\n", + " pd.json_normalize(step_4_port_visit_events_df[\"port_visit\"], sep=\"_\"),\n", + " ],\n", + " axis=1,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 42, + "id": "685a746e-8091-4321-b851-79a5f3ca0f81", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 8 entries, 0 to 7\n", + "Data columns (total 37 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 8 non-null object \n", + " 1 name 8 non-null object \n", + " 2 ssvid 8 non-null object \n", + " 3 flag 8 non-null object \n", + " 4 type 8 non-null object \n", + " 5 public_authorizations 8 non-null object \n", + " 6 nextPort 0 non-null object \n", + " 7 visit_id 8 non-null object \n", + " 8 confidence 8 non-null object \n", + " 9 duration_hrs 8 non-null float64\n", + " 10 start_anchorage_anchorage_id 8 non-null object \n", + " 11 start_anchorage_at_dock 8 non-null bool \n", + " 12 start_anchorage_distance_from_shore_km 8 non-null float64\n", + " 13 start_anchorage_flag 8 non-null object \n", + " 14 start_anchorage_id 8 non-null object \n", + " 15 start_anchorage_lat 8 non-null float64\n", + " 16 start_anchorage_lon 8 non-null float64\n", + " 17 start_anchorage_name 8 non-null object \n", + " 18 start_anchorage_top_destination 8 non-null object \n", + " 19 intermediate_anchorage_anchorage_id 8 non-null object \n", + " 20 intermediate_anchorage_at_dock 8 non-null bool \n", + " 21 intermediate_anchorage_distance_from_shore_km 8 non-null float64\n", + " 22 intermediate_anchorage_flag 8 non-null object \n", + " 23 intermediate_anchorage_id 8 non-null object \n", + " 24 intermediate_anchorage_lat 8 non-null float64\n", + " 25 intermediate_anchorage_lon 8 non-null float64\n", + " 26 intermediate_anchorage_name 8 non-null object \n", + " 27 intermediate_anchorage_top_destination 8 non-null object \n", + " 28 end_anchorage_anchorage_id 8 non-null object \n", + " 29 end_anchorage_at_dock 8 non-null bool \n", + " 30 end_anchorage_distance_from_shore_km 8 non-null float64\n", + " 31 end_anchorage_flag 8 non-null object \n", + " 32 end_anchorage_id 8 non-null object \n", + " 33 end_anchorage_lat 8 non-null float64\n", + " 34 end_anchorage_lon 8 non-null float64\n", + " 35 end_anchorage_name 8 non-null object \n", + " 36 end_anchorage_top_destination 8 non-null object \n", + "dtypes: bool(3), float64(10), object(24)\n", + "memory usage: 2.3+ KB\n" + ] + } + ], + "source": [ + "step_4_port_visits_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 43, + "id": "0e77b956-f0f8-4fbd-8a49-0116e4401c12", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
namessvidconfidencestart_anchorage_nameintermediate_anchorage_nameend_anchorage_name
0ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
1CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
2CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
3ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
4CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
5ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
6CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
7ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
\n", + "
" + ], + "text/plain": [ + " name ssvid confidence start_anchorage_name \\\n", + "0 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "1 CAPESANTE 701006605 4 USHUAIA \n", + "2 CAPESANTE 701006605 4 USHUAIA \n", + "3 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "4 CAPESANTE 701006605 4 USHUAIA \n", + "5 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "6 CAPESANTE 701006605 4 USHUAIA \n", + "7 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "\n", + " intermediate_anchorage_name end_anchorage_name \n", + "0 MAR DEL PLATA MAR DEL PLATA \n", + "1 USHUAIA USHUAIA \n", + "2 USHUAIA USHUAIA \n", + "3 MAR DEL PLATA MAR DEL PLATA \n", + "4 USHUAIA USHUAIA \n", + "5 MAR DEL PLATA MAR DEL PLATA \n", + "6 USHUAIA USHUAIA \n", + "7 MAR DEL PLATA MAR DEL PLATA " + ] + }, + "execution_count": 43, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_port_visits_df[\n", + " [\n", + " \"name\",\n", + " \"ssvid\",\n", + " \"confidence\",\n", + " \"start_anchorage_name\",\n", + " \"intermediate_anchorage_name\",\n", + " \"end_anchorage_name\",\n", + " ]\n", + "]" + ] + }, + { + "cell_type": "code", + "execution_count": 44, + "id": "32ee1871-f1c7-4561-9384-5a681293e7e5", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "ssvid\n", + "701024000 4\n", + "701006605 4\n", + "Name: count, dtype: int64" + ] + }, + "execution_count": 44, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_port_visits_df[\"ssvid\"].value_counts()" + ] + }, + { + "cell_type": "markdown", + "id": "61d59d0c-8919-40c4-ac30-bb9ab35a4d53", + "metadata": {}, + "source": [ + "### What We have learned from step 4" + ] + }, + { + "cell_type": "markdown", + "id": "4771fe04-5984-4576-b774-a83f104d7194", + "metadata": {}, + "source": [ + "- **Apparent Fishing Events:**\n", + " - `ATLANTIC SURF III (mmsi: 701024000, flag: ARG)`- has been detected in multiple apparent fishing events during the analyzed timeframe (August 2024 – January 2025)\n", + " - `CAPESANTE (mmsi: 701006605, flag: ARG)` - has been detected in multiple apparent fishing events during the analyzed timeframe (August 2024 – January 2025)\n", + "- **Port Visit Events:**\n", + " - `ATLANTIC SURF III (mmsi: 701024000, flag: ARG)`- potentially made multiple port visits, including stops at `MAR DEL PLATA`\n", + " - `CAPESANTE (mmsi: 701006605, flag: ARG)` - potentially made multiple port visits, including stops at `USHUAIA`\n", + "- **ENCOUNTER Events:** No explicit **ENCOUNTER** events were returned in the response dataset. Check more details [here](https://globalfishingwatch.org/faqs/what-is-a-vessel-encounter/). You can read more about transshipment behavior from our [report](https://globalfishingwatch.org/wp-content/uploads/GlobalViewOfTransshipment_Aug2017.pdf) or [scientific publication](https://www.frontiersin.org/articles/10.3389/fmars.2018.00240/full)." + ] + }, + { + "cell_type": "markdown", + "id": "f0cf3958-fb92-49c0-ba2f-2cfe971bcbc5", + "metadata": {}, + "source": [ + "**Potential Considerations:**\n", + "\n", + "- The vessel's fishing activities appear near the EEZ boundary, requiring further assessment of compliance with national or RFMO regulations.\n", + "- The absence of matching public authorizations in the RFMO registry does not necessarily indicate illegality, but it suggests that authorities may need to verify through national databases or official sources." + ] + }, + { + "cell_type": "markdown", + "id": "8b951044-6905-4e38-9885-13a98cf3a7cf", + "metadata": {}, + "source": [ + "### Summary of API Flow" + ] + }, + { + "cell_type": "markdown", + "id": "c8f86731-be44-4b89-8abb-cf2f6693b4c9", + "metadata": {}, + "source": [ + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** - Retrieve apparent fishing effort for **trawlers** within Argentinian EEZ.\n", + "2. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** - Fetch **vessel identity**, **ownership history**, and **public authorizations**.\n", + "3. **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)** - Detect potential **port visits**, **encounters**, and **apparent fishing** events to analyze operational patterns.\n", + "4. **Assess potential risks** - Compare registry records, AIS data, and inferred vessel activity for enforcement follow-ups.\n", + "5. **Generate a report** - Provide a structured analysis for relevant authorities." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez.ipynb b/notebooks/workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez.ipynb new file mode 100644 index 0000000..a894429 --- /dev/null +++ b/notebooks/workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez.ipynb @@ -0,0 +1,1996 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "1b582ffc-7477-46c3-b5bf-2caf9d028bf2", + "metadata": {}, + "source": [ + "\"Open" + ] + }, + { + "cell_type": "markdown", + "id": "87eddf13-ac9c-45b0-ae10-24eb1620e07e", + "metadata": {}, + "source": [ + "# Analyze a fleet in Ghanaian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "2006da5f-b6dc-491b-b64d-ad332e89e814", + "metadata": {}, + "source": [ + "This guide provides detailed instructions to on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to **Monitor a Fleet (a group of vessels) of Tuna Longliners in [Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400) region for Compliance** using **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)**, **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)**, and **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)**." + ] + }, + { + "cell_type": "markdown", + "id": "7ac25ecf-ffd7-40d7-9ea0-a6514c9fcd85", + "metadata": {}, + "source": [ + "**Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), 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." + ] + }, + { + "cell_type": "markdown", + "id": "71018cec-10c0-4619-9a7d-838a9f43cb15", + "metadata": {}, + "source": [ + "## Prerequisites" + ] + }, + { + "cell_type": "markdown", + "id": "996ca24b-99e4-4546-805b-697e4c2eb321", + "metadata": {}, + "source": [ + "Before using the `gfw-api-python-client`, ensure it is installed (see the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html) guide) and that you have obtained an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)." + ] + }, + { + "cell_type": "markdown", + "id": "6be16f6f-19fc-4d19-a0ed-ba370c844fa6", + "metadata": {}, + "source": [ + "## Installation" + ] + }, + { + "cell_type": "markdown", + "id": "af48cf4e-e24c-47aa-a2c5-64cf87be9c33", + "metadata": {}, + "source": [ + "The `gfw-api-python-client` can be easily installed using pip:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "88c09924-87d2-4c86-ad60-aed623416193", + "metadata": {}, + "outputs": [], + "source": [ + "# %pip install gfw-api-python-client" + ] + }, + { + "cell_type": "markdown", + "id": "b7a03d8d-8dec-4096-8395-d8cfc599db69", + "metadata": {}, + "source": [ + "## Usage" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "d93d57ae-0ec7-4d97-8fea-f679e89fc3b1", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "import datetime\n", + "import pandas as pd\n", + "import gfwapiclient as gfw" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "0b398f94-cd59-49c8-95a3-0ee46cf17e77", + "metadata": {}, + "outputs": [], + "source": [ + "try:\n", + " from google.colab import userdata\n", + "\n", + " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", + "except Exception as exc:\n", + " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", + "\n", + "access_token = access_token or \"\"" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "f5884635-6941-4f97-8b1a-5fd485a95bc4", + "metadata": {}, + "outputs": [], + "source": [ + "gfw_client = gfw.Client(\n", + " access_token=access_token,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b08a0e2c-3b9d-4c5e-b3a0-a5663fa32637", + "metadata": {}, + "source": [ + "## Introduction" + ] + }, + { + "cell_type": "markdown", + "id": "62fe47aa-ed77-4815-b08d-8c96f2480b04", + "metadata": {}, + "source": [ + "**Use Case: Monitoring a Fleet of Tuna Longliners for Compliance**" + ] + }, + { + "cell_type": "markdown", + "id": "5109f67f-aaae-4a7d-9a15-4db740542694", + "metadata": {}, + "source": [ + "Kwame is a fisheries compliance officer in Ghana, responsible for monitoring a fleet of tuna longliners operating within **[Ghanaian Exclusive Economic Zone (EEZ)](https://www.marineregions.org/gazetteer.php?p=details&id=8400)**. His goal is to:\n", + "\n", + "1. Track apparent fishing effort for **longliners** over the last 12 months.\n", + "2. Identify potential vessels in this fleet, their operational patterns, and their activity levels.\n", + "3. Retrieve vessel details, including **flag state**, **ownership history**, and **authorizations**.\n", + "4. Analyze events such as **port visits** and **encounters (potential transshipment)** activities." + ] + }, + { + "cell_type": "markdown", + "id": "b16b1b52-6b68-494a-9d76-ca7a7ab485a0", + "metadata": {}, + "source": [ + "**APIs Used:**\n", + "️\n", + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** – Retrieve apparent fishing effort grouped by vessel ID in Ghanaian EEZ.\n", + "2. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** – Get vessel identity, ownership, and compliance details.\n", + "3. **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)** – Identify port visits and potential transshipment activities for vessels in the fleet." + ] + }, + { + "cell_type": "markdown", + "id": "0ebc365c-2c5c-413e-80a5-36a4825f3032", + "metadata": {}, + "source": [ + "**Important:** In order to avoid any misinterpretation of **GFW data**, please refer to our official **data caveats** documentations:\n", + "- [Apparent fishing effort](https://globalfishingwatch.org/dataset-and-code-fishing-effort/) \n", + "- [Exclusive economic zone boundaries definition](https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition)\n", + "- [Vessel ID](https://globalfishingwatch.org/our-apis/documentation#vessel-id)\n", + "- [Vessel API - Vessel identity information](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)" + ] + }, + { + "cell_type": "markdown", + "id": "379460dd-ed9f-49ee-9c9b-e428ad5f4522", + "metadata": {}, + "source": [ + "**Important Caveats:**\n", + "\n", + "1. The [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api) only supports **one active report per user at a time**.\n", + "2. **Sending multiple requests simultaneously** results in a **429 Too Many Requests** error.\n", + "3. If a report takes over **100 seconds** to generate, it may return a **524 Gateway Timeout** error." + ] + }, + { + "cell_type": "markdown", + "id": "2c1e1858-c328-4719-8f10-40ae5b43ecb0", + "metadata": {}, + "source": [ + "## Step 0: Identify the Region of Interest (ROI) - Ghanaian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "64b1bbab-9780-4821-ae4f-ccff0a4bb100", + "metadata": {}, + "source": [ + "Before making API requests, Kwame must specify the geographic area for analysis using a **Region ID**:" + ] + }, + { + "cell_type": "markdown", + "id": "362137ce-97eb-4965-a649-a038bd5d167f", + "metadata": {}, + "source": [ + "**Options to Define the Region:**\n", + "\n", + "1. **Using Region ID** - Each EEZ has a unique ID in the **[public-eez-areas](https://globalfishingwatch.org/our-apis/documentation#regions)** dataset.\n", + "2. **Custom Geometries** - Users can define a custom area using GeoJSON.\n", + " \n", + "For **[Ghanaian EEZ, the region ID is 8400](https://www.marineregions.org/gazetteer.php?p=details&id=8400)** (public-eez-areas dataset)." + ] + }, + { + "cell_type": "markdown", + "id": "6fe5edf3-8e96-4147-8c59-a6bc8982662d", + "metadata": {}, + "source": [ + "## Step 1: Retrieve Fishing Effort in Ghanaian EEZ" + ] + }, + { + "cell_type": "markdown", + "id": "eba86e0d-90f7-4494-857c-261f9b734dc0", + "metadata": {}, + "source": [ + "Kwame **first queries** the **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** to get **fishing effort for all vessels**, grouping them by **gear type** in **[Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400)**. Please [learn more about apparent fishing effort here](https://globalfishingwatch.org/our-apis/documentation#ais-apparent-fishing-effort) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort)." + ] + }, + { + "cell_type": "markdown", + "id": "8816740a-4871-49e8-862c-049e0a3d02d3", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **[Region ID](https://globalfishingwatch.org/our-apis/documentation#regions)** - 8400 Ghanaian EEZ\n", + "2. **[Date Range](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Last 12 Months\n", + "3. **[Grouped By](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Gear Type" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "38c3bc74-e0f6-4f81-b830-3e3393d6b3d0", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", + " spatial_resolution=\"LOW\",\n", + " group_by=\"GEARTYPE\",\n", + " temporal_resolution=\"ENTIRE\",\n", + " start_date=\"2024-01-01\",\n", + " end_date=\"2025-01-01\",\n", + " spatial_aggregation=True,\n", + " region={\n", + " \"dataset\": \"public-eez-areas\",\n", + " \"id\": \"8400\",\n", + " },\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "5ee5daa3-6696-4552-8d1a-61df417b8873", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_report_df = step_1_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "35dac242-6479-437a-a35f-249ad22cf191", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 9 entries, 0 to 8\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 9 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 0 non-null object \n", + " 3 gear_type 9 non-null object \n", + " 4 hours 9 non-null float64\n", + " 5 vessel_ids 9 non-null int64 \n", + " 6 vessel_id 0 non-null object \n", + " 7 vessel_type 0 non-null object \n", + " 8 entry_timestamp 0 non-null object \n", + " 9 exit_timestamp 0 non-null object \n", + " 10 first_transmission_date 0 non-null object \n", + " 11 last_transmission_date 0 non-null object \n", + " 12 imo 0 non-null object \n", + " 13 mmsi 0 non-null object \n", + " 14 call_sign 0 non-null object \n", + " 15 dataset 0 non-null object \n", + " 16 report_dataset 9 non-null object \n", + " 17 ship_name 0 non-null object \n", + " 18 lat 0 non-null object \n", + " 19 lon 0 non-null object \n", + "dtypes: float64(1), int64(1), object(18)\n", + "memory usage: 1.5+ KB\n" + ] + } + ], + "source": [ + "step_1_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "6a245cc8-0236-4554-b4c8-d9bbc11db235", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typehoursvessel_ids
0Nonedrifting_longlines593.1383333
1Nonepurse_seines6.3405561
2Nonefishing20929.56333321
3Noneinconclusive30496.17361127
4Nonepole_and_line3481.5091675
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours vessel_ids\n", + "0 None drifting_longlines 593.138333 3\n", + "1 None purse_seines 6.340556 1\n", + "2 None fishing 20929.563333 21\n", + "3 None inconclusive 30496.173611 27\n", + "4 None pole_and_line 3481.509167 5" + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_report_df[[\"flag\", \"gear_type\", \"hours\", \"vessel_ids\"]].head()" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "b56ec0e4-5f85-4a10-bd94-39ea55128920", + "metadata": {}, + "outputs": [], + "source": [ + "step_1_agg_report_df = (\n", + " step_1_report_df.groupby([\"gear_type\"], as_index=False)\n", + " .agg(hours=(\"hours\", \"sum\"), vessel_ids=(\"vessel_ids\", \"sum\"))\n", + " .sort_values(by=\"hours\", ascending=False)\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "87289a41-0d54-44c9-a17a-f82b318af293", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
gear_typehoursvessel_ids
7trawlers46704.79722226
3inconclusive30496.17361127
1fishing20929.56333321
8tuna_purse_seines5146.62388923
5pole_and_line3481.5091675
0drifting_longlines593.1383333
4other_purse_seines26.5811111
6purse_seines6.3405561
2fixed_gear0.1636111
\n", + "
" + ], + "text/plain": [ + " gear_type hours vessel_ids\n", + "7 trawlers 46704.797222 26\n", + "3 inconclusive 30496.173611 27\n", + "1 fishing 20929.563333 21\n", + "8 tuna_purse_seines 5146.623889 23\n", + "5 pole_and_line 3481.509167 5\n", + "0 drifting_longlines 593.138333 3\n", + "4 other_purse_seines 26.581111 1\n", + "6 purse_seines 6.340556 1\n", + "2 fixed_gear 0.163611 1" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_1_agg_report_df" + ] + }, + { + "cell_type": "markdown", + "id": "09252564-51c1-4ed1-b938-76688a670cc6", + "metadata": {}, + "source": [ + "### What We have Learned from Step 1" + ] + }, + { + "cell_type": "markdown", + "id": "79fee5f2-f217-40e4-be1d-235190de64b5", + "metadata": {}, + "source": [ + "1. Kwame now has apparent fishing effort data for multiple gear types.\n", + "2. There are **potential 3 vessels** operating as a **longliners (i.e., drifting_longlines)** in **[Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400)** with `593.138333 hours` logged." + ] + }, + { + "cell_type": "markdown", + "id": "80289282-d160-4901-9bf8-a7996785c898", + "metadata": {}, + "source": [ + "## Step 2: Retrieve Vessel IDs for Longliners" + ] + }, + { + "cell_type": "markdown", + "id": "33209132-cc4a-4711-8e96-0846a71b9c34", + "metadata": {}, + "source": [ + "Kwame refines his **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** request to group by **vessel ID**, and filtering only for **longliners** in **[Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400)**." + ] + }, + { + "cell_type": "markdown", + "id": "293c479b-497c-4472-9ce6-c813985b7533", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **[Region ID](https://globalfishingwatch.org/our-apis/documentation#regions)** - [8400 Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400)\n", + "2. **[Date Range](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Last 12 Months\n", + "3. **[Grouped By](https://globalfishingwatch.org/our-apis/documentation#report-url-parameters-for-both-post-and-get-requests)** - Vessel ID " + ] + }, + { + "cell_type": "markdown", + "id": "f55f1862-ae0d-4ad5-b281-6a514ae9dcce", + "metadata": {}, + "source": [ + "**Why Use group-by=VESSEL_ID?**\n", + "\n", + "Grouping by **VESSEL_ID** allows **individual vessel identification** in the response. This is crucial for **tracking vessel activity** and, more importantly, linking each detected vessel to the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** in the next step. By structuring the query this way, we can fetch vessel details such as **flag, name, and ownership records** in **Step 3 below**.\n" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "0797f962-6582-4d3b-bfba-3597d5513a73", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", + " spatial_resolution=\"LOW\",\n", + " group_by=\"VESSEL_ID\",\n", + " temporal_resolution=\"ENTIRE\",\n", + " filters=[\"geartype in ('drifting_longlines')\"],\n", + " start_date=\"2024-01-01\",\n", + " end_date=\"2025-01-01\",\n", + " spatial_aggregation=True,\n", + " region={\n", + " \"dataset\": \"public-eez-areas\",\n", + " \"id\": \"8400\",\n", + " },\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "8be53e48-4b93-4140-ae0e-aa910a993da7", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_report_df = step_2_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "061b9fbf-88cf-47d8-9b30-b878c0b867cf", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 3 entries, 0 to 2\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 3 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 3 non-null object \n", + " 3 gear_type 3 non-null object \n", + " 4 hours 3 non-null float64 \n", + " 5 vessel_ids 0 non-null object \n", + " 6 vessel_id 3 non-null object \n", + " 7 vessel_type 3 non-null object \n", + " 8 entry_timestamp 3 non-null datetime64[ns, UTC]\n", + " 9 exit_timestamp 3 non-null datetime64[ns, UTC]\n", + " 10 first_transmission_date 3 non-null datetime64[ns, UTC]\n", + " 11 last_transmission_date 3 non-null datetime64[ns, UTC]\n", + " 12 imo 3 non-null object \n", + " 13 mmsi 3 non-null object \n", + " 14 call_sign 3 non-null object \n", + " 15 dataset 3 non-null object \n", + " 16 report_dataset 3 non-null object \n", + " 17 ship_name 3 non-null object \n", + " 18 lat 0 non-null object \n", + " 19 lon 0 non-null object \n", + "dtypes: datetime64[ns, UTC](4), float64(1), object(15)\n", + "memory usage: 612.0+ bytes\n" + ] + } + ], + "source": [ + "step_2_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "932bd692-c689-4e1d-985c-18eeccdf9ec3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
flaggear_typehoursmmsiship_name
0CHNDRIFTING_LONGLINES2.750556412331032
1JPNDRIFTING_LONGLINES588.879722431100690SENSHU MARU NO.3
2TWNDRIFTING_LONGLINES1.508056416007496HUNG CHUAN SHUN
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours mmsi ship_name\n", + "0 CHN DRIFTING_LONGLINES 2.750556 412331032 \n", + "1 JPN DRIFTING_LONGLINES 588.879722 431100690 SENSHU MARU NO.3\n", + "2 TWN DRIFTING_LONGLINES 1.508056 416007496 HUNG CHUAN SHUN" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_report_df[[\"flag\", \"gear_type\", \"hours\", \"mmsi\", \"ship_name\"]].head()" + ] + }, + { + "cell_type": "markdown", + "id": "e54e9165-3f02-46a5-b4ef-74dbfc618766", + "metadata": {}, + "source": [ + "### What We have Learned from Step 2" + ] + }, + { + "cell_type": "markdown", + "id": "72a9efeb-ae54-4bbd-ab85-77845f928376", + "metadata": {}, + "source": [ + "1. Kwame identifies `3 vessels` operating as longliners within **[Ghanaian EEZ](https://www.marineregions.org/gazetteer.php?p=details&id=8400)**.\n", + "2. The vessel `(mmsi: 431100690, ship_name: SENSHU MARU NO.3)` shows significant activity with `588.879722 hours` logged.\n", + "3. Other vessels `(mmsi: 416007496, ship_name: HUNG CHUAN SHUN)` and `(mmsi: 412331032)` shows apparent fishing effort over a short duration.\n", + "4. This response is based on **AIS self-reported** data and should be further validated.\n" + ] + }, + { + "cell_type": "markdown", + "id": "06b8fa5a-b2fd-415c-9bea-d8ef4902cbe6", + "metadata": {}, + "source": [ + "## Step 3: Retrieve Vessel Details Using the Vessels API" + ] + }, + { + "cell_type": "markdown", + "id": "f491fac4-0825-4c6b-aba2-d889d2ec678e", + "metadata": {}, + "source": [ + "Kwame queries the **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** to **get detailed vessel identity and ownership records**. Please [learn more about Vessels API here](https://globalfishingwatch.org/our-apis/documentation#vessels-api) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information)." + ] + }, + { + "cell_type": "markdown", + "id": "0ed8adac-33da-4168-90a6-5381e9b628f6", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **Vessel IDs** from 4Wings API, **Step 2 above**.\n", + "2. **[Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset)** - `public-global-vessel-identity:latest`.\n", + "3. **[Includes](https://globalfishingwatch.org/our-apis/documentation#get-vessels-by-ids-url-parameters)** - `POTENTIAL_RELATED_SELF_REPORTED_INFO`." + ] + }, + { + "cell_type": "markdown", + "id": "fa782e3d-3c9d-4236-a0e4-157e22e6aeed", + "metadata": {}, + "source": [ + "**Note:** Vessels may change identifiers over time, such as their `Maritime Mobile Service Identity (MMSI)`,` International Maritime Organization (IMO) number)`, `call sign`, or even their `name`. These changes can occur due to `re-registration`, `changes in ownership`, or other `operational reasons` within the `AIS transponder`. Parameter (`includes = POTENTIAL_RELATED_SELF_REPORTED_INFO`) helps group all **vessel ids** that are **potentially related** as part of the **same physical vessel** based on publicly available registry information." + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "15889e5c-dea7-499d-bd77-68a12aca8d98", + "metadata": {}, + "outputs": [], + "source": [ + "step_2_vessel_ids = list(step_2_report_df[\"vessel_id\"].unique())" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "8477d36f-27ea-4ca9-aaad-dfaf8d94cd80", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['f37ebdc1b-be44-0740-7904-49397360e29d',\n", + " 'b1dad8628-8c9c-2ee7-258b-3d8fb747f1c8',\n", + " '60f7bb972-2c90-4553-650b-23c38f9521bf']" + ] + }, + "execution_count": 16, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_2_vessel_ids" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "33d970d9-1321-46ec-87bc-91aed1f446ff", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_vessels_result = await gfw_client.vessels.get_vessels_by_ids(\n", + " ids=step_2_vessel_ids,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "c1b9a6e9-683f-44fe-bb47-98825cf9d150", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_vessels_df = step_3_vessels_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "d87c1cef-92d1-462d-a86e-c2af11912ed9", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 3 entries, 0 to 2\n", + "Data columns (total 7 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 dataset 3 non-null object\n", + " 1 registry_info_total_records 3 non-null int64 \n", + " 2 registry_info 3 non-null object\n", + " 3 registry_owners 3 non-null object\n", + " 4 registry_public_authorizations 3 non-null object\n", + " 5 combined_sources_info 3 non-null object\n", + " 6 self_reported_info 3 non-null object\n", + "dtypes: int64(1), object(6)\n", + "memory usage: 300.0+ bytes\n" + ] + } + ], + "source": [ + "step_3_vessels_df.info()" + ] + }, + { + "cell_type": "markdown", + "id": "9a64a937-59af-414d-8fcc-28948c423117", + "metadata": {}, + "source": [ + "**Understanding Vessel Details Response Data**\n", + "\n", + "- **registryInfoTotalRecords** – This represents the **number of registry records** found for the vessels.\n", + "- **registryInfo** – Contains **public registry data**. This data is sourced from official **vessel registries**.\n", + "- **registryOwners** – Lists the **registered owners** of the vessel based on public sources.\n", + "- **registryPublicAuthorizations** – Represents known **fishing authorizations** from public sources. Users should verify against national registries and RFMO records for additional context.\n", + "- **combinedSourcesInfo** – Provides inferred data from multiple sources, including. This is not explicitly reported by vessels but determined through **GFW's classification methods**.\n", + "- **selfReportedInfo** – Contains **AIS self-reported** data, including `MMSI`, `ship name`, and `flag` as broadcast by the **vessel itself**. Self-reported data may not always align with registry data and should be cross-checked." + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "348301a7-c290-4684-bb03-23298e8bc7e0", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
registry_inforegistry_ownersself_reported_info
0[{'id': '0b0dec977c1aad4ae6652c4076572cc7', 's...[{'name': 'TOMIOKA FISHERIES', 'flag': 'JPN', ...[{'id': 'c86d138c5-5d51-3620-fe01-a9e0ed37fb91...
1[][][{'id': 'f37ebdc1b-be44-0740-7904-49397360e29d...
2[{'id': '02eda7d2da02943eecd48813fb7d562a', 's...[{'name': 'HER RONG SHUN FISHERIES', 'flag': '...[{'id': '60f7bb972-2c90-4553-650b-23c38f9521bf...
\n", + "
" + ], + "text/plain": [ + " registry_info \\\n", + "0 [{'id': '0b0dec977c1aad4ae6652c4076572cc7', 's... \n", + "1 [] \n", + "2 [{'id': '02eda7d2da02943eecd48813fb7d562a', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'TOMIOKA FISHERIES', 'flag': 'JPN', ... \n", + "1 [] \n", + "2 [{'name': 'HER RONG SHUN FISHERIES', 'flag': '... \n", + "\n", + " self_reported_info \n", + "0 [{'id': 'c86d138c5-5d51-3620-fe01-a9e0ed37fb91... \n", + "1 [{'id': 'f37ebdc1b-be44-0740-7904-49397360e29d... \n", + "2 [{'id': '60f7bb972-2c90-4553-650b-23c38f9521bf... " + ] + }, + "execution_count": 20, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_vessels_df[[\"registry_info\", \"registry_owners\", \"self_reported_info\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "44ae4527-da01-4845-be11-b46ddd5575fc", + "metadata": {}, + "source": [ + "### Explore Vessels Registry Info" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "7e5cf6db-8f45-4c7e-a8c8-ccdb312eca7d", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_registry_info_df = pd.json_normalize(\n", + " step_3_vessels_df[\"registry_info\"].explode()\n", + ")\n", + "step_3_registry_info_df = step_3_registry_info_df.dropna()" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "b350572a-93ec-434f-8f6f-d0418f693b46", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namegear_typessource_code
0431100690JPNSENSHU MARU NO.3SENSHUMARU3[DRIFTING_LONGLINES][CCSBT, GFCM, IATTC, ICCAT, IMO, IOTC, OPRT, R...
2416007496TWNHUNG CHUAN SHUNHUNGCHUANSHUN[DRIFTING_LONGLINES][ICCAT, IMO, ISSF, OPRT, TMT_ICCAT, TMT_OTHER_...
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name gear_types \\\n", + "0 431100690 JPN SENSHU MARU NO.3 SENSHUMARU3 [DRIFTING_LONGLINES] \n", + "2 416007496 TWN HUNG CHUAN SHUN HUNGCHUANSHUN [DRIFTING_LONGLINES] \n", + "\n", + " source_code \n", + "0 [CCSBT, GFCM, IATTC, ICCAT, IMO, IOTC, OPRT, R... \n", + "2 [ICCAT, IMO, ISSF, OPRT, TMT_ICCAT, TMT_OTHER_... " + ] + }, + "execution_count": 22, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_registry_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"gear_types\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "5e0fb205-ea78-4074-b3bb-266d624d5f86", + "metadata": {}, + "source": [ + "### Explore Registry Owners" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "0ed351c2-104c-4132-bcae-a3c757ac2465", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_registry_owners_df = pd.json_normalize(\n", + " step_3_vessels_df[\"registry_owners\"].explode()\n", + ")\n", + "step_3_registry_owners_df = step_3_registry_owners_df.dropna()" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "d6bbbc39-1928-42cd-9866-71fa95a601d8", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagnamesource_code
0431100690JPNTOMIOKA FISHERIES[TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF...
1431100690JPNTOMIOKA[TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF...
2431100690JPNYAMAMOTO YUUKI[TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF...
3431100690JPNYAMAMOTO HIROKI[TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF...
5416007496TWNHER RONG SHUN FISHERIES[TMT_ICCAT, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag name \\\n", + "0 431100690 JPN TOMIOKA FISHERIES \n", + "1 431100690 JPN TOMIOKA \n", + "2 431100690 JPN YAMAMOTO YUUKI \n", + "3 431100690 JPN YAMAMOTO HIROKI \n", + "5 416007496 TWN HER RONG SHUN FISHERIES \n", + "\n", + " source_code \n", + "0 [TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF... \n", + "1 [TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF... \n", + "2 [TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF... \n", + "3 [TMT_CCSBT, TMT_IATTC, TMT_ICCAT, TMT_OTHER_OF... \n", + "5 [TMT_ICCAT, TMT_OTHER_OFFICIAL] " + ] + }, + "execution_count": 24, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_registry_owners_df[[\"ssvid\", \"flag\", \"name\", \"source_code\"]]" + ] + }, + { + "cell_type": "markdown", + "id": "e355771a-ec2a-41b2-ab51-801baf15fab1", + "metadata": {}, + "source": [ + "### Explore Vessels Self Reported Info" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "add8a66e-9736-4cdb-a74d-0607fcc530a2", + "metadata": {}, + "outputs": [], + "source": [ + "step_3_self_reported_info_df = pd.json_normalize(\n", + " step_3_vessels_df[\"self_reported_info\"].explode()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "fd0831dc-e29e-4ccc-864f-704eebee2686", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
ssvidflagship_namen_ship_namesource_code
0431100690JPNNoneNone[AIS]
1431100690JPNSENSHU MARU NO.3SENSHUMARU3[AIS]
2431100690JPNSENSHU MARU NO3SENSHUMARU3[AIS]
3412331032CHNNoneNone[AIS]
4416007496TWNHUNG CHUAN SHUNHUNGCHUANSHUN[AIS]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name source_code\n", + "0 431100690 JPN None None [AIS]\n", + "1 431100690 JPN SENSHU MARU NO.3 SENSHUMARU3 [AIS]\n", + "2 431100690 JPN SENSHU MARU NO3 SENSHUMARU3 [AIS]\n", + "3 412331032 CHN None None [AIS]\n", + "4 416007496 TWN HUNG CHUAN SHUN HUNGCHUANSHUN [AIS]" + ] + }, + "execution_count": 26, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_3_self_reported_info_df[\n", + " [\"ssvid\", \"flag\", \"ship_name\", \"n_ship_name\", \"source_code\"]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "a4e08576-803c-482f-afa5-3fbf4a86837d", + "metadata": {}, + "source": [ + "### What We have Learned from Step 3" + ] + }, + { + "cell_type": "markdown", + "id": "37e54952-ec16-4c85-a6c3-ee7e844d007b", + "metadata": {}, + "source": [ + "- The vessel `mmsi/ssvid: 412331032` appears to be a drifting longliner flagged under China.\n", + "- No public registry data is found for this vessel.\n", + "- The vessel's identity information is based on `AIS self-reported data`, which may not always align with official registries.\n", + "- The vessel appears to have been active since `2014`, based on `self-reported AIS records`.\n", + "- This vessel's data needs further validation against official public sources" + ] + }, + { + "cell_type": "markdown", + "id": "2dc21e2c-a261-44ee-a3b6-2065d4095bcb", + "metadata": {}, + "source": [ + "## Step 4: Detect Fleet Activity (Port Visits)" + ] + }, + { + "cell_type": "markdown", + "id": "ce91f54f-8938-428c-bb22-21c54c8b51f5", + "metadata": {}, + "source": [ + "Now that Kwame has identified vessels in the fleet, he examines their activity further by querying the **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)**. This allows him to detect `port visits`, `encounters (Potential Transshipment)` and `apparent fishing activity` based on vessel movement patterns. Please [learn more about Events API here](https://globalfishingwatch.org/our-apis/documentation#events-api) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#how-are-the-events-estimated)." + ] + }, + { + "cell_type": "markdown", + "id": "af80cd9c-fe29-4650-9052-dbe7b623eb8d", + "metadata": {}, + "source": [ + "**Filters Used:**\n", + "\n", + "1. **Vessel ID** from 4Wings API\n", + "2. **[Event Types](https://globalfishingwatch.org/our-apis/documentation#events-post-body-parameters)** - Port visits, encounters (potential transshipment), and fishing events.\n", + "3. **Time Range** - Last 6 months.\n", + "4. **[Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset)**:\n", + " - `public-global-port-visits-events::latest` (Port Visits)\n", + " - `public-global-encounters-events:latest` (Encounters between vessels)\n", + " - `public-global-fishing-events:latest` (Fishing activity)\n", + "5. **[Encounter Types](https://globalfishingwatch.org/our-apis/documentation#events-post-body-parameters)** - FISHING-FISHING" + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "ae1567e5-0594-4eb3-a78a-5e8902deb2ac", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_events_result = await gfw_client.events.get_all_events(\n", + " datasets=[\n", + " \"public-global-encounters-events:latest\",\n", + " \"public-global-fishing-events:latest\",\n", + " \"public-global-port-visits-events:latest\",\n", + " ],\n", + " vessels=step_2_vessel_ids,\n", + " types=[\"ENCOUNTER\", \"FISHING\", \"PORT_VISIT\"],\n", + " start_date=\"2024-08-01\",\n", + " end_date=\"2025-01-31\",\n", + " encounter_types=[\"FISHING-FISHING\"],\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "904c3745-e999-4fc7-a3fe-dd639c6a87c2", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_events_df = step_4_events_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "7f2ef6a8-6eed-47c5-bb44-253bad118956", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 418 entries, 0 to 417\n", + "Data columns (total 14 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 start 418 non-null datetime64[ns, UTC]\n", + " 1 end 418 non-null datetime64[ns, UTC]\n", + " 2 id 418 non-null object \n", + " 3 type 418 non-null object \n", + " 4 position 418 non-null object \n", + " 5 regions 418 non-null object \n", + " 6 bounding_box 418 non-null object \n", + " 7 distances 418 non-null object \n", + " 8 vessel 418 non-null object \n", + " 9 encounter 0 non-null object \n", + " 10 fishing 414 non-null object \n", + " 11 gap 0 non-null object \n", + " 12 loitering 0 non-null object \n", + " 13 port_visit 4 non-null object \n", + "dtypes: datetime64[ns, UTC](2), object(12)\n", + "memory usage: 45.8+ KB\n" + ] + } + ], + "source": [ + "step_4_events_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "39b4f990-1da9-4862-b9fc-554f7b4c7dc0", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "type\n", + "fishing 414\n", + "port_visit 4\n", + "Name: count, dtype: int64" + ] + }, + "execution_count": 30, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_events_df[\"type\"].value_counts()" + ] + }, + { + "cell_type": "markdown", + "id": "ccb71753-df83-4ca1-8a43-89fa2cb344d4", + "metadata": {}, + "source": [ + "### Explore Apparent Fishing Events" + ] + }, + { + "cell_type": "code", + "execution_count": 31, + "id": "87b32f2a-29ea-4f11-87c2-a16655ac5005", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_fishing_events_df = step_4_events_df[step_4_events_df[\"fishing\"].notna()]" + ] + }, + { + "cell_type": "code", + "execution_count": 32, + "id": "7ee57f28-eff1-40d7-865a-e3ad04103b4c", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_fishing_df = pd.concat(\n", + " [\n", + " pd.json_normalize(step_4_fishing_events_df[\"vessel\"], sep=\"_\"),\n", + " pd.json_normalize(step_4_fishing_events_df[\"fishing\"], sep=\"_\"),\n", + " ],\n", + " axis=1,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "id": "4a8deceb-aaef-4fe3-8a43-88b4c34d2a70", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 414 entries, 0 to 413\n", + "Data columns (total 12 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 414 non-null object \n", + " 1 name 389 non-null object \n", + " 2 ssvid 414 non-null object \n", + " 3 flag 414 non-null object \n", + " 4 type 414 non-null object \n", + " 5 public_authorizations 414 non-null object \n", + " 6 nextPort 0 non-null object \n", + " 7 total_distance_km 414 non-null float64\n", + " 8 average_speed_knots 414 non-null float64\n", + " 9 average_duration_hours 0 non-null object \n", + " 10 potential_risk 414 non-null bool \n", + " 11 vessel_public_authorization_status 414 non-null object \n", + "dtypes: bool(1), float64(2), object(9)\n", + "memory usage: 36.1+ KB\n" + ] + } + ], + "source": [ + "step_4_fishing_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 34, + "id": "0b95e76a-7fe8-45ba-87a3-ffab7d15c7d1", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
namessvidtotal_distance_kmaverage_speed_knots
0HUNG CHUAN SHUN41600749618.4810568.841667
1HUNG CHUAN SHUN41600749634.8675598.240000
2HUNG CHUAN SHUN41600749611.0868508.208333
3HUNG CHUAN SHUN41600749612.6996508.266667
4HUNG CHUAN SHUN41600749656.7880346.248000
...............
409SENSHU MARU NO.343110069012.1644945.083333
410SENSHU MARU NO.343110069013.1911243.986957
411SENSHU MARU NO.34311006908.6856593.850000
412SENSHU MARU NO.343110069015.7219873.686667
413SENSHU MARU NO.343110069028.5537793.728571
\n", + "

414 rows × 4 columns

\n", + "
" + ], + "text/plain": [ + " name ssvid total_distance_km average_speed_knots\n", + "0 HUNG CHUAN SHUN 416007496 18.481056 8.841667\n", + "1 HUNG CHUAN SHUN 416007496 34.867559 8.240000\n", + "2 HUNG CHUAN SHUN 416007496 11.086850 8.208333\n", + "3 HUNG CHUAN SHUN 416007496 12.699650 8.266667\n", + "4 HUNG CHUAN SHUN 416007496 56.788034 6.248000\n", + ".. ... ... ... ...\n", + "409 SENSHU MARU NO.3 431100690 12.164494 5.083333\n", + "410 SENSHU MARU NO.3 431100690 13.191124 3.986957\n", + "411 SENSHU MARU NO.3 431100690 8.685659 3.850000\n", + "412 SENSHU MARU NO.3 431100690 15.721987 3.686667\n", + "413 SENSHU MARU NO.3 431100690 28.553779 3.728571\n", + "\n", + "[414 rows x 4 columns]" + ] + }, + "execution_count": 34, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_fishing_df[\n", + " [\n", + " \"name\",\n", + " \"ssvid\",\n", + " \"total_distance_km\",\n", + " \"average_speed_knots\",\n", + " ]\n", + "]" + ] + }, + { + "cell_type": "code", + "execution_count": 35, + "id": "2416d761-b334-4995-ba67-81ff96c3dd57", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "ssvid\n", + "416007496 363\n", + "431100690 26\n", + "412331032 25\n", + "Name: count, dtype: int64" + ] + }, + "execution_count": 35, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_fishing_df[\"ssvid\"].value_counts()" + ] + }, + { + "cell_type": "markdown", + "id": "dfdc826c-d854-4f1c-bf0b-82560d23a2f4", + "metadata": {}, + "source": [ + "### Explore Port Visit Events" + ] + }, + { + "cell_type": "code", + "execution_count": 36, + "id": "337ddf63-42ba-4ea7-a56d-2d8d602f5a22", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_port_visit_events_df = step_4_events_df[step_4_events_df[\"port_visit\"].notna()]" + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "id": "a77465d1-02ce-42bb-a0b3-7c243cf02a40", + "metadata": {}, + "outputs": [], + "source": [ + "step_4_port_visits_df = pd.concat(\n", + " [\n", + " pd.json_normalize(step_4_port_visit_events_df[\"vessel\"], sep=\"_\"),\n", + " pd.json_normalize(step_4_port_visit_events_df[\"port_visit\"], sep=\"_\"),\n", + " ],\n", + " axis=1,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 38, + "id": "566e8a67-8fff-4d10-9749-83c6dae727b7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 4 entries, 0 to 3\n", + "Data columns (total 37 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 4 non-null object \n", + " 1 name 3 non-null object \n", + " 2 ssvid 4 non-null object \n", + " 3 flag 4 non-null object \n", + " 4 type 4 non-null object \n", + " 5 public_authorizations 4 non-null object \n", + " 6 nextPort 0 non-null object \n", + " 7 visit_id 4 non-null object \n", + " 8 confidence 4 non-null object \n", + " 9 duration_hrs 4 non-null float64\n", + " 10 start_anchorage_anchorage_id 4 non-null object \n", + " 11 start_anchorage_at_dock 4 non-null bool \n", + " 12 start_anchorage_distance_from_shore_km 4 non-null float64\n", + " 13 start_anchorage_flag 4 non-null object \n", + " 14 start_anchorage_id 4 non-null object \n", + " 15 start_anchorage_lat 4 non-null float64\n", + " 16 start_anchorage_lon 4 non-null float64\n", + " 17 start_anchorage_name 4 non-null object \n", + " 18 start_anchorage_top_destination 4 non-null object \n", + " 19 intermediate_anchorage_anchorage_id 4 non-null object \n", + " 20 intermediate_anchorage_at_dock 4 non-null bool \n", + " 21 intermediate_anchorage_distance_from_shore_km 4 non-null float64\n", + " 22 intermediate_anchorage_flag 4 non-null object \n", + " 23 intermediate_anchorage_id 4 non-null object \n", + " 24 intermediate_anchorage_lat 4 non-null float64\n", + " 25 intermediate_anchorage_lon 4 non-null float64\n", + " 26 intermediate_anchorage_name 4 non-null object \n", + " 27 intermediate_anchorage_top_destination 4 non-null object \n", + " 28 end_anchorage_anchorage_id 4 non-null object \n", + " 29 end_anchorage_at_dock 4 non-null bool \n", + " 30 end_anchorage_distance_from_shore_km 4 non-null float64\n", + " 31 end_anchorage_flag 4 non-null object \n", + " 32 end_anchorage_id 4 non-null object \n", + " 33 end_anchorage_lat 4 non-null float64\n", + " 34 end_anchorage_lon 4 non-null float64\n", + " 35 end_anchorage_name 4 non-null object \n", + " 36 end_anchorage_top_destination 4 non-null object \n", + "dtypes: bool(3), float64(10), object(24)\n", + "memory usage: 1.2+ KB\n" + ] + } + ], + "source": [ + "step_4_port_visits_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 39, + "id": "0381a7bd-cf81-4b58-9f8d-f01601121ad2", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
namessvidconfidencestart_anchorage_nameintermediate_anchorage_nameend_anchorage_name
0HUNG CHUAN SHUN4160074964TEMATEMATEMA
1SENSHU MARU NO.34311006904TEMATEMATEMA
2None4123310324DAKARDAKARDAKAR
3SENSHU MARU NO.34311006904TEMATEMATEMA
\n", + "
" + ], + "text/plain": [ + " name ssvid confidence start_anchorage_name \\\n", + "0 HUNG CHUAN SHUN 416007496 4 TEMA \n", + "1 SENSHU MARU NO.3 431100690 4 TEMA \n", + "2 None 412331032 4 DAKAR \n", + "3 SENSHU MARU NO.3 431100690 4 TEMA \n", + "\n", + " intermediate_anchorage_name end_anchorage_name \n", + "0 TEMA TEMA \n", + "1 TEMA TEMA \n", + "2 DAKAR DAKAR \n", + "3 TEMA TEMA " + ] + }, + "execution_count": 39, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "step_4_port_visits_df[\n", + " [\n", + " \"name\",\n", + " \"ssvid\",\n", + " \"confidence\",\n", + " \"start_anchorage_name\",\n", + " \"intermediate_anchorage_name\",\n", + " \"end_anchorage_name\",\n", + " ]\n", + "]" + ] + }, + { + "cell_type": "markdown", + "id": "2d340b6b-3d88-4c48-a699-305a75e706a4", + "metadata": {}, + "source": [ + "### What We’ve Learned from Step 4" + ] + }, + { + "cell_type": "markdown", + "id": "709d2a5c-5246-4995-ab68-0997adf62349", + "metadata": {}, + "source": [ + "- `4: port visits`, `0: encounters`, and `414: fishing` events were found for the queried vessels in the given date range.\n", + "- Some events were missed due to **AIS data coverage gaps**.\n", + "- Different filters may need to be applied to refine results." + ] + }, + { + "cell_type": "markdown", + "id": "be4b21a0-f3ea-4f10-a61f-cf121cbe078e", + "metadata": {}, + "source": [ + "**Caveats & Considerations**" + ] + }, + { + "cell_type": "markdown", + "id": "c7625234-6210-4701-91b2-cca2cfe43494", + "metadata": {}, + "source": [ + "- **A lack of recorded encounters or any other events does not confirm the absence of such activities**—AIS coverage, reporting behavior, and dataset updates can impact results.\n", + "- **Further investigation may be required**, including manual validation using historical data or consulting additional sources." + ] + }, + { + "cell_type": "markdown", + "id": "8b951044-6905-4e38-9885-13a98cf3a7cf", + "metadata": {}, + "source": [ + "## Summary of API Flow" + ] + }, + { + "cell_type": "markdown", + "id": "c8f86731-be44-4b89-8abb-cf2f6693b4c9", + "metadata": {}, + "source": [ + "1. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** - Identify fishing effort by **gear type** in Ghanaian EEZ.\n", + "2. **[4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api)** - Retrieve vessel IDs for potential **longliners**.\n", + "3. **[Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)** - Fetch detailed **vessel identity** & **ownership**.\n", + "4. **[Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)** - Attempt to detect fleet activity (**port visits**, **encounters**, and **apparent fishing** events)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.14" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}