diff --git a/Makefile b/Makefile index 4b65f42..4261cd7 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,6 @@ .DEFAULT_GOAL := help sources = src tests +notebooks-sources = notebooks .PHONY: install ## Install the package, dependencies, and pre-commit for local development install: @@ -14,12 +15,24 @@ format: python -m ruff check --fix $(sources) python -m ruff format $(sources) +.PHONY: format-notebooks ## Auto-format Jupyter Notebooks +format-notebooks: + python -m black $(notebooks-sources) + python -m ruff check --fix $(notebooks-sources) + python -m ruff format $(notebooks-sources) + .PHONY: lint ## Lint python source files lint: python -m ruff check $(sources) python -m ruff format --check $(sources) python -m black $(sources) --check --diff +.PHONY: lint-notebooks ## Lint Jupyter Notebooks +lint-notebooks: + python -m ruff check $(notebooks-sources) + python -m ruff format --check $(notebooks-sources) + python -m black $(notebooks-sources) --check --diff + .PHONY: codespell ## Use Codespell to do spellchecking codespell: python -m codespell_lib diff --git a/README.md b/README.md index ebc8848..c9bee5e 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ gfw_client = gfw.Client( ) ``` -For step-by-step instructions and examples, see the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html) and [Usage Guides](https://globalfishingwatch.github.io/gfw-api-python-client/usage-guides/index.html) in the documentation. +For step-by-step instructions and examples, see the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html), [Usage Guides](https://globalfishingwatch.github.io/gfw-api-python-client/usage-guides/index.html), and [Workflow Guides](https://globalfishingwatch.github.io/gfw-api-python-client/workflow-guides/index.html) in the documentation. ## Documentation @@ -82,7 +82,7 @@ The full project documentation is available at [globalfishingwatch.github.io/gfw To get started with the basics, head over to the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html) guide. -For detailed instructions and examples on interacting with the various APIs offered by Global Fishing Watch, explore the [Usage Guides](https://globalfishingwatch.github.io/gfw-api-python-client/usage-guides/index.html) section. +For detailed instructions and examples on interacting with the various APIs offered by Global Fishing Watch, explore the [Usage Guides](https://globalfishingwatch.github.io/gfw-api-python-client/usage-guides/index.html), and [Workflow Guides](https://globalfishingwatch.github.io/gfw-api-python-client/workflow-guides/index.html) sections. For a complete reference of all available classes, methods, and modules, see the [API Reference](https://globalfishingwatch.github.io/gfw-api-python-client/apidocs/index.html) section. 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..fa7d8a7 100644 --- a/docs/source/getting-started.md +++ b/docs/source/getting-started.md @@ -47,8 +47,8 @@ For more detailed installation instructions, including setting up a virtual envi Once installed, you can import and use `gfw-api-python-client` in your Python codes: ```python -import os import datetime +import os import gfwapiclient as gfw @@ -63,6 +63,10 @@ gfw_client = gfw.Client( ) ``` +> **Important:** The `gfw-api-python-client` is **async-first**: all API methods are asynchronous and must be executed using Python's `async` / `await` syntax. **Environments with built-in async support** (e.g., _Jupyter Notebook_, _Google Colab_, and async web frameworks such as _FastAPI_) can call client methods directly using `await`, with no additional setup. **Environments without built-in async support** (e.g., _plain Python scripts_, _Python modules_, or synchronous web frameworks such as _Flask_ and _Django_) must explicitly run asynchronous code using an event loop. This can be done with tools such as [`asyncio.run`](https://docs.python.org/3/library/asyncio.html), [`trio.run`](https://trio.readthedocs.io/en/stable/), [`anyio.run`](https://anyio.readthedocs.io/en/stable/), or framework-specific async integration. + +> **Tip:** Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.11+ with `python -m asyncio` to run `gfw-api-python-client` code interactively, as these environments support executing `async` / `await` expressions directly in the console. + ## Making API Requests ### Searching for a Vessel by MMSI @@ -103,6 +107,10 @@ vessel_self_reported_infos = [ for self_reported_info in vessel_item.self_reported_info ] +vessel_ids = [ + self_reported_info.id for self_reported_info in vessel_self_reported_infos +] + print(vessel_ids) ``` @@ -124,6 +132,7 @@ start_datetime = min( ] ) start_date = start_datetime.date() +start_date = max(start_date, datetime.date.fromisoformat("2020-01-01")) end_datetime = max( @@ -226,6 +235,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`, `Bulk Download`, `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..b857b62 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} @@ -48,7 +49,12 @@ To learn about how to use `gfw-api-python-client`, check out the following resou - [Events API](usage-guides/events-api) - [Insights API](usage-guides/insights-api) - [Datasets API](usage-guides/datasets-api) + - [Bulk Download API](usage-guides/bulk-downloads-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..19ff85b 100644 --- a/docs/source/usage-guides/4wings-api.md +++ b/docs/source/usage-guides/4wings-api.md @@ -2,9 +2,9 @@ Open In Colab -This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access the 4Wings API, which is designed for generating reports and statistics on activities within specified regions. This API is particularly useful for creating data visualizations related to fishing effort and other vessel activities. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/4wings-api.ipynb) version of this guide with more usage examples. +This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access the [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api), which is designed for generating reports and statistics on activities within specified regions. This API is particularly useful for creating data visualizations related to fishing effort and other vessel activities. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/4wings-api.ipynb) version of this guide with more usage examples. -> **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. +> **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [AIS Apparent Fishing Effort Data Caveats](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort), [AIS Vessel Presence Data Caveats](https://globalfishingwatch.org/our-apis/documentation#ais-vessel-presence-caveats), [SAR Vessel Detections Data Caveats](https://globalfishingwatch.org/our-apis/documentation#sar-vessel-detections-data-caveats), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits. ## Prerequisites @@ -32,6 +32,8 @@ gfw_client = gfw.Client( The `gfw_client.fourwings` object provides methods to generate reports, retrieve the last generated report, and get global fishing effort statistics. These methods return a `result` object, which offers convenient ways to access the data as Pydantic models using `.data()` or as pandas DataFrames using `.df()`. +> **Tip:** Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.11+ with `python -m asyncio` to run `gfw-api-python-client` code interactively, as these environments support executing `async` / `await` expressions directly in the console. + ## Creating a Fishing Effort Report (`create_fishing_effort_report`) Generates **AIS (Automatic Identification System) apparent fishing effort** reports to visualize fishing activity. 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). @@ -293,7 +295,11 @@ report_result = await gfw_client.fourwings.create_report( spatial_resolution="LOW", temporal_resolution="MONTHLY", group_by="FLAG", - datasets=["public-global-fishing-effort:latest"], + datasets=[ + "public-global-fishing-effort:latest", + "public-global-sar-presence:latest", + "public-global-presence:latest", + ], start_date="2022-01-01", end_date="2022-05-01", region={ @@ -324,7 +330,7 @@ print(report_item.model_dump()) **Output:** ``` -('2022-03', 'RUS', 7.109166666666667, 3, 75.8, 44.0) +('2022-03', 'RUS', 1.0, 1, 52.1, 153.2) ``` ### Access the report data as a DataFrame @@ -340,32 +346,32 @@ print(report_df[["date", "flag", "hours", "lat", "lon"]].head()) ``` -RangeIndex: 32271 entries, 0 to 32270 +RangeIndex: 310599 entries, 0 to 310598 Data columns (total 20 columns): - # Column Non-Null Count Dtype ---- ------ -------------- ----- - 0 date 32271 non-null object - 1 detections 0 non-null object - 2 flag 32271 non-null object - 3 gear_type 0 non-null object - 4 hours 32271 non-null float64 - 5 vessel_ids 32271 non-null int64 - 6 vessel_id 0 non-null object - 7 vessel_type 0 non-null object - 8 entry_timestamp 0 non-null object - 9 exit_timestamp 0 non-null object - 10 first_transmission_date 0 non-null object - 11 last_transmission_date 0 non-null object - 12 imo 0 non-null object - 13 mmsi 0 non-null object - 14 call_sign 0 non-null object - 15 dataset 0 non-null object - 16 report_dataset 32271 non-null object - 17 ship_name 0 non-null object - 18 lat 32271 non-null float64 - 19 lon 32271 non-null float64 -dtypes: float64(3), int64(1), object(16) -memory usage: 4.9+ MB + # Column Non-Null Count Dtype +--- ------ -------------- ----- + 0 date 310599 non-null object + 1 detections 3995 non-null float64 + 2 flag 310599 non-null object + 3 gear_type 0 non-null object + 4 hours 306604 non-null float64 + 5 vessel_ids 310599 non-null int64 + 6 vessel_id 0 non-null object + 7 vessel_type 0 non-null object + 8 entry_timestamp 0 non-null object + 9 exit_timestamp 0 non-null object + 10 first_transmission_date 0 non-null object + 11 last_transmission_date 0 non-null object + 12 imo 0 non-null object + 13 mmsi 0 non-null object + 14 call_sign 0 non-null object + 15 dataset 0 non-null object + 16 report_dataset 310599 non-null object + 17 ship_name 0 non-null object + 18 lat 310599 non-null float64 + 19 lon 310599 non-null float64 +dtypes: float64(4), int64(1), object(15) +memory usage: 47.4+ MB ``` ## Reference Data @@ -374,10 +380,11 @@ 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) - [Insights API](insights-api) - [Datasets API](datasets-api) +- [Bulk Download API](bulk-downloads-api) - [Reference Data API](references-data-api) diff --git a/docs/source/usage-guides/bulk-downloads-api.md b/docs/source/usage-guides/bulk-downloads-api.md new file mode 100644 index 0000000..e199643 --- /dev/null +++ b/docs/source/usage-guides/bulk-downloads-api.md @@ -0,0 +1,382 @@ +# Bulk Download API + +Open In Colab + +This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access the [Bulk Download API](https://globalfishingwatch.org/our-apis/documentation#bulk-download-api), which is designed to support workflows that require bulk access to data, including integration with platforms and tools used by data engineers and researchers. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/bulk-downloads-api.ipynb) version of this guide with more usage examples. + +> **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), [SAR (Synthetic-Aperture Radar) Data Caveats](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits. + +## Prerequisites + +- Before using the `gfw-api-python-client`, ensure it is installed (see the [Getting Started](../getting-started) guide) and that you have obtained an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens). + +## Getting Started + +To interact with the Bulk Download endpoints, you first need to instantiate the `gfw.Client` and then access the `bulk_downloads` resource: + +```python +import time +import os + +import gfwapiclient as gfw + + +access_token = os.environ.get( + "GFW_API_ACCESS_TOKEN", + "", +) + +gfw_client = gfw.Client( + access_token=access_token, +) +``` + +The `gfw_client.bulk_downloads` object provides methods to: + +- Create bulk reports based on specific filters and spatial parameters. +- Monitor previously created bulk report generation status. +- Get signed URL to download previously created bulk report data, metadata and + region geometry (in GeoJSON format) files. +- Query previously created bulk report data records in JSON format. + +These methods return a `result` object, which offers convenient ways to access the data as Pydantic models using `.data()` or as pandas DataFrames using `.df()`. + +> **Tip:** Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.11+ with `python -m asyncio` to run `gfw-api-python-client` code interactively, as these environments support executing `async` / `await` expressions directly in the console. + +## Create a Bulk Report (`create_bulk_report`) + +The `create_bulk_report()` method allows you create a bulk report based on specified filters and spatial parameters. The `name` parameter is mandatory. Please [learn more about create a bulk report here](https://globalfishingwatch.org/our-apis/documentation#create-a-bulk-report) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [here](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats). + +```python +timestamp = int(time.time() * 1000) +dataset = "public-fixed-infrastructure-data:latest" +region_dataset = "public-eez-areas" +region_id = "8466" # Argentinian Exclusive Economic Zone +name = f"{dataset.split(':')[0]}_{region_dataset}__{region_id}_{timestamp}" + +create_bulk_report_result = await gfw_client.bulk_downloads.create_bulk_report( + name=name, + dataset=dataset, + region={ + "dataset": region_dataset, + "id": region_id, + }, + filters=["label = 'oil'", "label_confidence = 'high'"], +) +``` + +### Access Create a Bulk Report Result as Pydantic models + +```python +create_bulk_report_data = create_bulk_report_result.data() +print(( + create_bulk_report_data.id, + create_bulk_report_data.name, + create_bulk_report_data.status, + create_bulk_report_data.created_at, +)) +``` + +**Output:** + +``` +('c5e32895-4374-41d2-8b2e-ac414ed6757f', + 'public-fixed-infrastructure-data_public-eez-areas__8466_1768085547174', + 'pending', + datetime.datetime(2026, 1, 10, 22, 52, 30, 9000, tzinfo=TzInfo(0))) +``` + +### Access Create a Bulk Report Result as a DataFrame + +```python +create_bulk_report_df = create_bulk_report_result.df() + +print(create_bulk_report_df.info()) +print(create_bulk_report_df.head()) +``` + +**Output:** + +``` + +RangeIndex: 1 entries, 0 to 0 +Data columns (total 12 columns): + # Column Non-Null Count Dtype +--- ------ -------------- ----- + 0 id 1 non-null object + 1 name 1 non-null object + 2 file_path 1 non-null object + 3 format 1 non-null object + 4 filters 1 non-null object + 5 geom 1 non-null object + 6 status 1 non-null object + 7 owner_id 1 non-null int64 + 8 owner_type 1 non-null object + 9 created_at 1 non-null datetime64[ns, UTC] + 10 updated_at 1 non-null datetime64[ns, UTC] + 11 file_size 0 non-null object +dtypes: datetime64[ns, UTC](2), int64(1), object(9) +memory usage: 228.0+ bytes +``` + +## Get Bulk Report by ID (`get_bulk_report_by_id`) + +The `get_bulk_report_by_id()` method allows you retrieves metadata and status of the previously created bulk report based on the provided bulk report ID. The `id` parameter is mandatory. Please [learn more about get bulk report by id report here](https://globalfishingwatch.org/our-apis/documentation#get-bulk-report-by-id) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [here](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats). + +> **Important:** We recommend to use this method to poll the status of previously created bulk report, if it takes **several minutes or hours** to generate until it status is `done` or `failed`. + +```python +bulk_report_result = await gfw_client.bulk_downloads.get_bulk_report_by_id( + id=create_bulk_report_data.id +) +``` + +### Access Get Bulk Report by ID Result as Pydantic models + +```python +bulk_report_data = bulk_report_result.data() + +print(( + create_bulk_report_data.id, + create_bulk_report_data.name, + create_bulk_report_data.status, + create_bulk_report_data.created_at, +)) +``` + +**Output:** + +``` +('c5e32895-4374-41d2-8b2e-ac414ed6757f', + 'public-fixed-infrastructure-data_public-eez-areas__8466_1768085547174', + 'pending', + datetime.datetime(2026, 1, 10, 22, 52, 30, 9000, tzinfo=TzInfo(0))) +``` + +### Access Get Bulk Report by ID Result as a DataFrame + +```python +bulk_report_df = bulk_report_result.df() + +print(bulk_report_df.info()) +print(bulk_report_df.head()) +``` + +**Output:** + +``` + +RangeIndex: 1 entries, 0 to 0 +Data columns (total 12 columns): + # Column Non-Null Count Dtype +--- ------ -------------- ----- + 0 id 1 non-null object + 1 name 1 non-null object + 2 file_path 1 non-null object + 3 format 1 non-null object + 4 filters 1 non-null object + 5 geom 1 non-null object + 6 status 1 non-null object + 7 owner_id 1 non-null int64 + 8 owner_type 1 non-null object + 9 created_at 1 non-null datetime64[ns, UTC] + 10 updated_at 1 non-null datetime64[ns, UTC] + 11 file_size 0 non-null object +dtypes: datetime64[ns, UTC](2), int64(1), object(9) +memory usage: 228.0+ bytes +``` + +## Get All Bulk Reports Created by User or Application (`get_all_bulk_reports`) + +The `get_all_bulk_reports()` method allows you retrieves a list of **metadata and status** of the previously created bulk reports based on specified pagination, sorting, and filtering criteria. Please [learn more about get all bulk reports created by user or application here](https://globalfishingwatch.org/our-apis/documentation#get-all-bulk-reports-by-user) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [here](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats). + +```python +bulk_reports_result = await gfw_client.bulk_downloads.get_all_bulk_reports( + status="done", +) +``` + +### Access All Created Bulk Reports Result as Pydantic models + +```python +bulk_reports_data = bulk_reports_result.data() +bulk_report_item = bulk_reports_data[-1] + +print(( + bulk_report_item.id, + bulk_report_item.name, + bulk_report_item.status, + bulk_report_item.created_at, +)) +``` + +**Output:** + +``` +('0c0cada1-72dd-4fb0-bdf6-7fe8c7fdb1e3', + 'sar-fixed-infrastructure-data-20241207-region-1', + 'done', + datetime.datetime(2025, 12, 7, 10, 3, 12, 371000, tzinfo=TzInfo(0))) +``` + +### Access All Created Bulk Reports Result as a DataFrame + +```python +bulk_reports_df = bulk_reports_result.df() + +print(bulk_reports_df.info()) +print(bulk_reports_df.head()) +``` + +**Output:** + +``` + +RangeIndex: 7 entries, 0 to 6 +Data columns (total 12 columns): + # Column Non-Null Count Dtype +--- ------ -------------- ----- + 0 id 7 non-null object + 1 name 7 non-null object + 2 file_path 7 non-null object + 3 format 7 non-null object + 4 filters 7 non-null object + 5 geom 4 non-null object + 6 status 7 non-null object + 7 owner_id 7 non-null int64 + 8 owner_type 7 non-null object + 9 created_at 7 non-null datetime64[ns, UTC] + 10 updated_at 7 non-null datetime64[ns, UTC] + 11 file_size 7 non-null float64 +dtypes: datetime64[ns, UTC](2), float64(1), int64(1), object(8) +memory usage: 804.0+ bytes +``` + +## Get Bulk Report File Download URL (`get_bulk_report_file_download_url`) + +The `get_bulk_report_file_download_url()` method allows you retrieves **signed URL** that points to a **downloadable file** hosted on Global Fishing Watch's cloud infrastructure to **download file(s)** (i.e., `"DATA"`, `"README"`, or `"GEOM"`) of the previously created bulk report. The `id` parameter is mandatory. Please [learn more about get bulk report file download url here](https://globalfishingwatch.org/our-apis/documentation#download-bulk-report-url-file) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [here](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats). + +```python +bulk_report_file_download_url_result = ( + await gfw_client.bulk_downloads.get_bulk_report_file_download_url( + id=bulk_reports_data[0].id, file="DATA" + ) +) +``` + +### Access Get Bulk Report File Download URL Result as Pydantic models + +```python +bulk_report_file_download_url_data = bulk_report_file_download_url_result.data() + +print(bulk_report_file_download_url_data.url) +``` + +**Output:** + +``` +'https://storage.googleapis.com/gfw-api-bulk-pro-us-central1/705f2f9a-f695-43f1-a4bf-7746f3deb091/data.json.gz?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=api-bulk-pro%40gfw-production.iam.gserviceaccount.com%2F20260110%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20260110T225232Z&X-Goog-Expires=60&X-Goog-SignedHeaders=host&X-Goog-Signature=481a4ff7244b7286f303b37bb7941c291a26d1e3502debdb7611b8cb2d5edf37bc7aa0287b15a11c2f69f72e88791da3f76873a2fd7d08f911691c35ee8e095b825615510de8256f8cd275211997141e026837e118d86e01c026c457dc1f47d43ff2cb07131c3d21e7908c847bf1e3d87cd4773f02e8e4512a7c15e93799de186b9ea004be50cd3e53292f01e9393595a81c42cc3686f65d280f4f16076759da4722c17c2a6a698393c919cdd083402421a1bbf425b618244b3a9b30e48b770a9dc7f9eed8e63af04f8e31f0b6723fdf76fa7262ded89e7a375fbaea3b031bf29db22b1961878facd79c92d633ab6aa2309c0ce3982104d9835058ecd829bee8' +``` + +### Access Get Bulk Report File Download URL Result as a DataFrame + +```python +bulk_report_file_download_url_df = bulk_report_file_download_url_result.df() + +print(bulk_report_file_download_url_df.info()) +print(bulk_report_file_download_url_df.iloc[0]["url"]) +``` + +**Output:** + +``` + +RangeIndex: 1 entries, 0 to 0 +Data columns (total 1 columns): + # Column Non-Null Count Dtype +--- ------ -------------- ----- + 0 url 1 non-null object +dtypes: object(1) +memory usage: 140.0+ bytes +``` + +## Query Bulk Fixed Infrastructure Data Report (`query_bulk_fixed_infrastructure_data_report`) + +The `query_bulk_fixed_infrastructure_data_report()` method allows you retrieves **data records** of a previously created **fixed infrastructure data** (i.e., `public-fixed-infrastructure-data:latest` dataset) bulk report data in JSON format based on specified pagination, sorting, and including criteria. The `id` parameter is mandatory. Please [learn more about query bulk fixed infrastructure data report in JSON format here](https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [here](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats). + +```python +bulk_fixed_infrastructure_data_report_result = ( + await gfw_client.bulk_downloads.query_bulk_fixed_infrastructure_data_report( + id=bulk_reports_data[0].id + ) +) +``` + +### Access Query Bulk Fixed Infrastructure Data Report Result as Pydantic models + +```python +bulk_fixed_infrastructure_data_report_data = ( + bulk_fixed_infrastructure_data_report_result.data() +) + +bulk_fixed_infrastructure_data_report_item = bulk_fixed_infrastructure_data_report_data[ + -1 +] + +print(( + bulk_fixed_infrastructure_data_report_item.structure_id, + bulk_fixed_infrastructure_data_report_item.lat, + bulk_fixed_infrastructure_data_report_item.lon, + bulk_fixed_infrastructure_data_report_item.label, + bulk_fixed_infrastructure_data_report_item.label_confidence, +)) +``` + +**Output:** + +``` +('1051638', -53.0895574340617, -67.32289149541135, 'oil', 'high') +``` + +### Access Query Bulk Fixed Infrastructure Data Report Result as a DataFrame + +```python +bulk_fixed_infrastructure_data_report_result_df = ( + bulk_fixed_infrastructure_data_report_result.df() +) + +print(bulk_fixed_infrastructure_data_report_result_df.info()) +print(bulk_fixed_infrastructure_data_report_result_df.head()) +``` + +**Output:** + +``` + +RangeIndex: 1238 entries, 0 to 1237 +Data columns (total 9 columns): + # Column Non-Null Count Dtype +--- ------ -------------- ----- + 0 detection_id 1237 non-null object + 1 detection_date 1238 non-null datetime64[ns] + 2 structure_id 1238 non-null object + 3 lat 1238 non-null float64 + 4 lon 1238 non-null float64 + 5 structure_start_date 1238 non-null datetime64[ns] + 6 structure_end_date 7 non-null datetime64[ns] + 7 label 1238 non-null object + 8 label_confidence 1238 non-null object +dtypes: datetime64[ns](3), float64(2), object(4) +memory usage: 87.2+ KB +``` + +## Next Steps + +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: + +- [4Wings API](4wings-api) +- [Vessels API](vessels-api) +- [Events API](events-api) +- [Insights API](insights-api) +- [Datasets API](datasets-api) +- [Reference Data API](references-data-api) diff --git a/docs/source/usage-guides/datasets-api.md b/docs/source/usage-guides/datasets-api.md index 0c1e96f..9babfb5 100644 --- a/docs/source/usage-guides/datasets-api.md +++ b/docs/source/usage-guides/datasets-api.md @@ -2,7 +2,7 @@ Open In Colab -This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access various datasets available through the Global Fishing Watch API. Currently, it focuses on retrieving SAR (Synthetic Aperture Radar) fixed infrastructure data. The Datasets API allows you to retrieve this information, either by specifying `tile coordinates` or a `geographic geometry`. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/datasets-api.ipynb) version of this guide with more usage examples. +This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access various datasets available through the Global Fishing Watch API. Currently, it focuses on retrieving SAR (Synthetic Aperture Radar) fixed infrastructure data. The [Datasets API](https://globalfishingwatch.org/our-apis/documentation#datasets-api) allows you to retrieve this information, either by specifying `tile coordinates` or a `geographic geometry`. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/datasets-api.ipynb) version of this guide with more usage examples. > **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [SAR (Synthetic-Aperture Radar) Data Caveats](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats), 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. @@ -32,6 +32,8 @@ gfw_client = gfw.Client( The `gfw_client.datasets` object provides methods to retrieve data from various datasets. The `get_sar_fixed_infrastructure` method allows you to access SAR fixed infrastructure data. This method returns a `result` object, which offers convenient ways to access the data as Pydantic models using `.data()` or as pandas DataFrames using `.df()`. +> **Tip:** Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.11+ with `python -m asyncio` to run `gfw-api-python-client` code interactively, as these environments support executing `async` / `await` expressions directly in the console. + ## Retrieving SAR Fixed Infrastructure Data by Tile Coordinates (`get_sar_fixed_infrastructure` with z, x, y) You can retrieve SAR fixed infrastructure data for a specific tile using its zoom level (`z`), x-coordinate (`x`), and y-coordinate (`y`). @@ -80,19 +82,19 @@ print(sar_infrastructure_df.head()) ``` -RangeIndex: 1106 entries, 0 to 1105 +RangeIndex: 1156 entries, 0 to 1155 Data columns (total 7 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- - 0 structure_id 1106 non-null int64 - 1 lat 1106 non-null float64 - 2 lon 1106 non-null float64 - 3 label 1106 non-null object - 4 structure_start_date 1106 non-null datetime64[ns, UTC] - 5 structure_end_date 831 non-null datetime64[ns, UTC] - 6 label_confidence 1106 non-null object + 0 structure_id 1156 non-null int64 + 1 lat 1156 non-null float64 + 2 lon 1156 non-null float64 + 3 label 1156 non-null object + 4 structure_start_date 1156 non-null datetime64[ns, UTC] + 5 structure_end_date 857 non-null datetime64[ns, UTC] + 6 label_confidence 1156 non-null object dtypes: datetime64[ns, UTC](2), float64(2), int64(1), object(2) -memory usage: 60.6+ KB +memory usage: 63.3+ KB ``` ## Retrieving SAR Fixed Infrastructure Data by Geometry (`get_sar_fixed_infrastructure` with geometry) @@ -152,27 +154,28 @@ print(sar_infrastructure_df.head()) ``` -RangeIndex: 1106 entries, 0 to 1105 +RangeIndex: 1156 entries, 0 to 1155 Data columns (total 7 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- - 0 structure_id 1106 non-null int64 - 1 lat 1106 non-null float64 - 2 lon 1106 non-null float64 - 3 label 1106 non-null object - 4 structure_start_date 1106 non-null datetime64[ns, UTC] - 5 structure_end_date 831 non-null datetime64[ns, UTC] - 6 label_confidence 1106 non-null object + 0 structure_id 1156 non-null int64 + 1 lat 1156 non-null float64 + 2 lon 1156 non-null float64 + 3 label 1156 non-null object + 4 structure_start_date 1156 non-null datetime64[ns, UTC] + 5 structure_end_date 857 non-null datetime64[ns, UTC] + 6 label_confidence 1156 non-null object dtypes: datetime64[ns, UTC](2), float64(2), int64(1), object(2) -memory usage: 60.6+ KB +memory usage: 63.3+ 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) - [Events API](events-api) - [Insights API](insights-api) +- [Bulk Download API](bulk-downloads-api) - [Reference Data API](references-data-api) diff --git a/docs/source/usage-guides/events-api.md b/docs/source/usage-guides/events-api.md index c570a91..1da9787 100644 --- a/docs/source/usage-guides/events-api.md +++ b/docs/source/usage-guides/events-api.md @@ -2,7 +2,7 @@ Open In Colab -This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access information about various activities of a vessel, including fishing activity, encounters, port visits, loitering, and gaps in AIS reporting. The Events API allows you to retrieve lists of events, get details for a specific event, and obtain statistics on event occurrences. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/events-api.ipynb) version of this guide with more usage examples. +This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access information about various activities of a vessel, including fishing activity, encounters, port visits, loitering, and gaps in AIS reporting. The [Events API](https://globalfishingwatch.org/our-apis/documentation#events-api) allows you to retrieve lists of events, get details for a specific event, and obtain statistics on event occurrences. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/events-api.ipynb) version of this guide with more usage examples. > **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Events Data Caveats](https://globalfishingwatch.org/our-apis/documentation#how-are-the-events-estimated), 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. @@ -32,6 +32,8 @@ gfw_client = gfw.Client( The `gfw_client.events` object provides methods to retrieve event data and statistics. Each of these methods returns a `result` object, which offers convenient ways to access the data as Pydantic models using `.data()` or as pandas DataFrames using `.df()`. +> **Tip:** Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.11+ with `python -m asyncio` to run `gfw-api-python-client` code interactively, as these environments support executing `async` / `await` expressions directly in the console. + ## Retrieving All Events (`get_all_events`) The `get_all_events()` method allows you to retrieve a list of events based on specified criteria. The `datasets` parameter is mandatory. @@ -45,7 +47,7 @@ events_result = await gfw_client.events.get_all_events( "dataset": "public-eez-areas", "id": "8371", }, - limit=1, + limit=5, ) ``` @@ -61,7 +63,7 @@ print(event.model_dump()) **Output:** ``` -('a0f5848d1a83b7f0b4b8cda6873699ba', 'fishing', '9e01144bf-f383-e634-3178-ca7e34477f34') +('bbbf5d0cfa9639e5eac0130fc2b742e9', 'fishing', '7374d1988-87f8-6037-66b4-59854a026efb') ``` ### Access the events as a DataFrame @@ -76,26 +78,26 @@ print(events_df[["id", "type"]].head()) ``` -RangeIndex: 1 entries, 0 to 0 +RangeIndex: 5 entries, 0 to 4 Data columns (total 14 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- - 0 start 1 non-null datetime64[ns, UTC] - 1 end 1 non-null datetime64[ns, UTC] - 2 id 1 non-null object - 3 type 1 non-null object - 4 position 1 non-null object - 5 regions 1 non-null object - 6 bounding_box 1 non-null object - 7 distances 1 non-null object - 8 vessel 1 non-null object + 0 start 5 non-null datetime64[ns, UTC] + 1 end 5 non-null datetime64[ns, UTC] + 2 id 5 non-null object + 3 type 5 non-null object + 4 position 5 non-null object + 5 regions 5 non-null object + 6 bounding_box 5 non-null object + 7 distances 5 non-null object + 8 vessel 5 non-null object 9 encounter 0 non-null object - 10 fishing 1 non-null object + 10 fishing 5 non-null object 11 gap 0 non-null object 12 loitering 0 non-null object 13 port_visit 0 non-null object dtypes: datetime64[ns, UTC](2), object(12) -memory usage: 244.0+ bytes +memory usage: 692.0+ bytes ``` ## Retrieving a Single Event by ID (`get_event_by_id`) @@ -120,7 +122,7 @@ print(event.model_dump()) **Output:** ``` -('a0f5848d1a83b7f0b4b8cda6873699ba', 'fishing', '9e01144bf-f383-e634-3178-ca7e34477f34') +('c2f0967e061f99a01793edac065de003', 'port_visit', '8c7304226-6c71-edbe-0b63-c246734b3c01') ``` ### Access the event as a DataFrame @@ -149,10 +151,10 @@ Data columns (total 14 columns): 7 distances 1 non-null object 8 vessel 1 non-null object 9 encounter 0 non-null object - 10 fishing 1 non-null object + 10 fishing 0 non-null object 11 gap 0 non-null object 12 loitering 0 non-null object - 13 port_visit 0 non-null object + 13 port_visit 1 non-null object dtypes: datetime64[ns, UTC](2), object(12) memory usage: 244.0+ bytes ``` @@ -185,7 +187,7 @@ print(event_stat.model_dump()) **Output:** ``` -(24786, 1, 194) +(24770, 1, 196) ``` ### Access the statistics as a DataFrame @@ -219,10 +221,11 @@ 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) - [Insights API](insights-api) - [Datasets API](datasets-api) +- [Bulk Download API](bulk-downloads-api) - [Reference Data API](references-data-api) diff --git a/docs/source/usage-guides/index.md b/docs/source/usage-guides/index.md index 00ec833..1f72ad4 100644 --- a/docs/source/usage-guides/index.md +++ b/docs/source/usage-guides/index.md @@ -12,5 +12,6 @@ vessels-api events-api insights-api datasets-api +bulk-downloads-api references-data-api ``` diff --git a/docs/source/usage-guides/insights-api.md b/docs/source/usage-guides/insights-api.md index 5208c2b..840f848 100644 --- a/docs/source/usage-guides/insights-api.md +++ b/docs/source/usage-guides/insights-api.md @@ -2,7 +2,7 @@ Open In Colab -This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access aggregated insights about vessel activities. Currently, the Insights API focuses on providing summaries related to specific vessels over a defined time range. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/insights-api.ipynb) version of this guide with more usage examples. +This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access aggregated insights about vessel activities. Currently, the [Insights API](https://globalfishingwatch.org/our-apis/documentation#insights-api) focuses on providing summaries related to specific vessels over a defined time range. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/insights-api.ipynb) version of this guide with more usage examples. > **Note:** See the [Insights Data Caveats](https://globalfishingwatch.org/our-apis/documentation#insights-api-fishing-detected-in-no-take-mpas)—it is critical to avoid misinterpreting the insights. You can find the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits. @@ -32,6 +32,10 @@ gfw_client = gfw.Client( ) ``` +The `gfw_client.insights` object provides methods for retrieving insights data for specified vessels. Each of these methods returns a `result` object, which offers convenient ways to access the data as Pydantic models using `.data()` or as pandas DataFrames using `.df()`. + +> **Tip:** Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.11+ with `python -m asyncio` to run `gfw-api-python-client` code interactively, as these environments support executing `async` / `await` expressions directly in the console. + ## Getting Insights by Vessel (`get_vessel_insights`) The `get_vessel_insights()` method allows you to retrieve aggregated insights for a specific vessel within a given time range. @@ -98,10 +102,11 @@ 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: +- [4Wings API](4wings-api) - [Vessels API](vessels-api) - [Events API](events-api) -- [4Wings API](4wings-api) - [Datasets API](datasets-api) +- [Bulk Download API](bulk-downloads-api) - [Reference Data API](references-data-api) diff --git a/docs/source/usage-guides/references-data-api.md b/docs/source/usage-guides/references-data-api.md index 1290a74..57927ba 100644 --- a/docs/source/usage-guides/references-data-api.md +++ b/docs/source/usage-guides/references-data-api.md @@ -2,7 +2,7 @@ Open In Colab -This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access reference data, specifically geographic regions. The Reference Data API offers access to static datasets, currently focusing on Exclusive Economic Zones (EEZs), Marine Protected Areas (MPAs), and Regional Fisheries Management Organizations (RFMOs). Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/references-data-api.ipynb) version of this guide with more usage examples. +This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access reference data, specifically geographic regions. The [Reference Data API](https://globalfishingwatch.org/our-apis/documentation#regions) offers access to static datasets, currently focusing on Exclusive Economic Zones (EEZs), Marine Protected Areas (MPAs), and Regional Fisheries Management Organizations (RFMOs). Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/references-data-api.ipynb) version of this guide with more usage examples. > **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Reference Data Caveats](https://globalfishingwatch.org/our-apis/documentation#reference-data), 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. @@ -32,6 +32,8 @@ gfw_client = gfw.Client( The `gfw_client.references` object provides methods to retrieve different types of geographic regions. Each of these methods returns a `result` object, which offers convenient ways to access the data as Pydantic models using `.data()` or as pandas DataFrames using `.df()`. +> **Tip:** Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.11+ with `python -m asyncio` to run `gfw-api-python-client` code interactively, as these environments support executing `async` / `await` expressions directly in the console. + ## Retrieving Exclusive Economic Zones (EEZs) To get a list of available Exclusive Economic Zone (EEZ) regions, use the `get_eez_regions()` method: @@ -52,8 +54,8 @@ print(eez_region.model_dump()) **Output:** ``` -(26523, 'public-eez-areas') -{'id': 26523, 'label': 'Turkmenistan', 'iso3': 'TKM', 'dataset': 'public-eez-areas'} +(48999, 'public-eez-areas') +{'id': 48999, 'label': 'Overlapping claim Peñón de Vélez de la Gomera: Spain / Morocco', 'iso3': None, 'dataset': 'public-eez-areas'} ``` ### Access the EEZ regions as a DataFrame @@ -67,17 +69,17 @@ print(eez_regions_df[["id", "dataset"]].head()) **Output:** ``` -class 'pandas.core.frame.DataFrame'> -RangeIndex: 282 entries, 0 to 281 + +RangeIndex: 285 entries, 0 to 284 Data columns (total 4 columns): - # Column Non-Null Count Dtype ---- ------ -------------- ----- - 0 id 281 non-null float64 - 1 label 282 non-null object - 2 iso3 282 non-null object - 3 dataset 282 non-null object -dtypes: float64(1), object(3) -memory usage: 8.9+ KB + # Column Non-Null Count Dtype +--- ------ -------------- ----- + 0 id 285 non-null int64 + 1 label 285 non-null object + 2 iso3 234 non-null object + 3 dataset 285 non-null object +dtypes: int64(1), object(3) +memory usage: 17.9+ KB ``` ## Retrieving Marine Protected Areas (MPAs) @@ -100,8 +102,8 @@ print(mpa_region.model_dump()) **Output:** ``` -('555790281', 'public-mpa-all') -{'id': '555790281', 'label': 'Iles Barren - Aire protegee', 'name': 'Iles Barren', 'dataset': 'public-mpa-all'} +('555799979', 'public-mpa-all') +{'id': '555799979', 'label': 'NAF Marine Protected Area - Marine Protected Area', 'name': None, 'dataset': 'public-mpa-all'} ``` ### Access the MPA regions as a DataFrame @@ -116,16 +118,16 @@ print(mpa_regions_df[["id", "dataset"]].head()) ``` -RangeIndex: 16621 entries, 0 to 16620 +RangeIndex: 16591 entries, 0 to 16590 Data columns (total 4 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- - 0 id 16621 non-null object - 1 label 16621 non-null object - 2 name 16621 non-null object - 3 dataset 16621 non-null object + 0 id 16591 non-null object + 1 label 16591 non-null object + 2 name 0 non-null object + 3 dataset 16591 non-null object dtypes: object(4) -memory usage: 519.5+ K +memory usage: 518.6+ KB ``` ## Retrieving Regional Fisheries Management Organizations (RFMOs) @@ -148,8 +150,9 @@ print(rfmo_region.model_dump()) **Output:** ``` -('WCPFC', 'public-rfmo') +('BOBP-IGO', 'public-rfmo') {'id': 'WCPFC', 'label': 'WCPFC', 'rfb': None, 'dataset': 'public-rfmo'} +{'id': 'BOBP-IGO', 'label': 'BOBP-IGO', 'rfb': None, 'dataset': 'public-rfmo', 'ID': 'BOBP-IGO'} ``` ### Access the RFMO regions as a DataFrame @@ -165,23 +168,25 @@ print(rfmo_regions_df[["id", "dataset"]].head()) ``` RangeIndex: 42 entries, 0 to 41 -Data columns (total 4 columns): +Data columns (total 5 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- 0 id 42 non-null object 1 label 42 non-null object - 2 rfb 35 non-null object + 2 rfb 0 non-null object 3 dataset 42 non-null object -dtypes: object(4) -memory usage: 1.4+ KB + 4 ID 42 non-null object +dtypes: object(5) +memory usage: 1.8+ 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) - [Events API](events-api) - [Insights API](insights-api) - [Datasets API](datasets-api) +- [Bulk Download API](bulk-downloads-api) diff --git a/docs/source/usage-guides/vessels-api.md b/docs/source/usage-guides/vessels-api.md index ec9ef6c..2196890 100644 --- a/docs/source/usage-guides/vessels-api.md +++ b/docs/source/usage-guides/vessels-api.md @@ -2,7 +2,7 @@ Open In Colab -This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access information about vessels. The Vessels API allows you to search for vessels, retrieve lists of vessels by their IDs, and get detailed information for a specific vessel, drawing from various datasets like identity, authorizations, and ownership. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/vessels-api.ipynb) version of this guide with more usage examples. +This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access information about vessels. The [Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api) allows you to search for vessels, retrieve lists of vessels by their IDs, and get detailed information for a specific vessel, drawing from various datasets like identity, authorizations, and ownership. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/vessels-api.ipynb) version of this guide with more usage examples. > **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Vessel Data Caveats](https://globalfishingwatch.org/our-apis/documentation#vessel-api-vessel-identity-information), 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. @@ -32,6 +32,8 @@ gfw_client = gfw.Client( The `gfw_client.vessels` object provides methods to search for and retrieve vessel information. Each of these methods returns a `result` object, which offers convenient ways to access the data as Pydantic models using `.data()` or as pandas DataFrames using `.df()`. +> **Tip:** Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.11+ with `python -m asyncio` to run `gfw-api-python-client` code interactively, as these environments support executing `async` / `await` expressions directly in the console. + ## Searching for Vessels (`search_vessels`) The `search_vessels()` method allows you to find vessels based on a query and various filters within specified datasets. @@ -39,7 +41,6 @@ The `search_vessels()` method allows you to find vessels based on a query and va ```python vessel_search_result = await gfw_client.vessels.search_vessels( where="ssvid='775998121' AND shipname='DON TITO'", - datasets=["public-global-vessel-identity:latest"], includes=["MATCH_CRITERIA", "OWNERSHIP"], ) ``` @@ -56,7 +57,7 @@ print(vessel.model_dump()) **Output:** ``` -('public-global-vessel-identity:v3.0', 'bae8f325c-cf0a-01fe-6d1a-9a275588d4ff') +('public-global-vessel-identity:v3.0', 'c54923e64-46f3-9338-9dcb-ff09724077a3') ``` ### Access the vessels as a DataFrame @@ -98,7 +99,6 @@ vessels_result = await gfw_client.vessels.get_vessels_by_ids( "6583c51e3-3626-5638-866a-f47c3bc7ef7c", "71e7da672-2451-17da-b239-857831602eca", ], - datasets=["public-global-vessel-identity:latest"], ) ``` @@ -114,7 +114,7 @@ print(vessel.model_dump()) **Output:** ``` -('public-global-vessel-identity:v3.0', '0cb77880e-ee49-2ce4-a849-c0b413b6ec89') +('public-global-vessel-identity:v3.0', 'aca119c29-95dd-f5c4-2057-ee45268dcd6f') ``` ### Access the vessels as a DataFrame @@ -151,7 +151,6 @@ The `get_vessel_by_id()` method retrieves detailed information for a specific ve ```python vessel_result = await gfw_client.vessels.get_vessel_by_id( id="c54923e64-46f3-9338-9dcb-ff09724077a3", - dataset="public-global-vessel-identity:latest", ) ``` @@ -198,10 +197,11 @@ 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) - [Insights API](insights-api) - [Datasets API](datasets-api) +- [Bulk Download API](bulk-downloads-api) - [Reference Data API](references-data-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..765071b --- /dev/null +++ b/docs/source/workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez.ipynb @@ -0,0 +1,1269 @@ +{ + "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": "markdown", + "id": "2532e150-f450-4ae6-b7a1-3433b5f25dac", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "cc98323c-c9e4-401c-8f26-f551968c003a", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "import pandas as pd\n", + "\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:\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
0CHNTRAWLERS0.368056412209175MENGXIN24
1ESPTRAWLERS1.306389225987981CIUDAD DE HUELVA
2CHNTRAWLERS216.545000412549331YUAN YU 886
3SENTRAWLERS612.825556663123000ILE AUX OISEAUX
4CHNTRAWLERS31.888889412444322MIN LONG YU61146
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours mmsi ship_name\n", + "0 CHN TRAWLERS 0.368056 412209175 MENGXIN24\n", + "1 ESP TRAWLERS 1.306389 225987981 CIUDAD DE HUELVA\n", + "2 CHN TRAWLERS 216.545000 412549331 YUAN YU 886\n", + "3 SEN TRAWLERS 612.825556 663123000 ILE AUX OISEAUX\n", + "4 CHN TRAWLERS 31.888889 412444322 MIN LONG YU61146" + ] + }, + "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': '29fef17154387858d8d4c777311c57f7', 's...[{'name': 'SENEVISA', 'flag': 'ESP', 'ssvid': ...[{'id': 'bf28c5a58-8c83-8690-8689-7f2d520f926e...
1[{'id': '199483471cd2da3717552fddb1a3172a', 's...[{'name': 'ARMEMENT SOPASEN', 'flag': 'SEN', '...[{'id': '894bc3ec6-6ade-f09c-e792-ff2e947508d8...
\n", + "
" + ], + "text/plain": [ + " registry_info \\\n", + "0 [{'id': '29fef17154387858d8d4c777311c57f7', 's... \n", + "1 [{'id': '199483471cd2da3717552fddb1a3172a', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'SENEVISA', 'flag': 'ESP', 'ssvid': ... \n", + "1 [{'name': 'ARMEMENT SOPASEN', 'flag': 'SEN', '... \n", + "\n", + " self_reported_info \n", + "0 [{'id': 'bf28c5a58-8c83-8690-8689-7f2d520f926e... \n", + "1 [{'id': '894bc3ec6-6ade-f09c-e792-ff2e947508d8... " + ] + }, + "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
0663178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
1762178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
2552178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
3663115000SENBETTYBETTY[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name gear_types \\\n", + "0 663178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "1 762178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "2 552178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "3 663115000 SEN BETTY BETTY [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
0663178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
1663176000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
2762178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
3552178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
4663115000SENARMEMENT SOPASEN[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag name source_code\n", + "0 663178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "1 663176000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "2 762178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "3 552178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "4 663115000 SEN ARMEMENT SOPASEN [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
0663178000SENNUEVONOSOLARNUEVONOSOLAR[AIS]
1663178000SENNUEVO=NOSOLAR+3&!U.?NUEVONOSOLAR3U[AIS]
2762178000NoneNUEVO NOSOLARNUEVONOSOLAR[AIS]
3552178000NoneNUEVO NOSOLARNUEVONOSOLAR[AIS]
4663178000SENNUEVO NOSOLARNUEVONOSOLAR[AIS]
5663115000SENBETTYBETTY[AIS]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name source_code\n", + "0 663178000 SEN NUEVONOSOLAR NUEVONOSOLAR [AIS]\n", + "1 663178000 SEN NUEVO=NOSOLAR+3&!U.? NUEVONOSOLAR3U [AIS]\n", + "2 762178000 None NUEVO NOSOLAR NUEVONOSOLAR [AIS]\n", + "3 552178000 None NUEVO NOSOLAR NUEVONOSOLAR [AIS]\n", + "4 663178000 SEN NUEVO NOSOLAR NUEVONOSOLAR [AIS]\n", + "5 663115000 SEN BETTY BETTY [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..a146cfc --- /dev/null +++ b/docs/source/workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez.ipynb @@ -0,0 +1,2182 @@ +{ + "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": "markdown", + "id": "420afe1c-ff77-40e2-9a07-7372dc95170c", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "cc98323c-c9e4-401c-8f26-f551968c003a", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "import pandas as pd\n", + "\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:\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
0pots_and_traps92.0297223
1inconclusive215.6238892
2inconclusive98.1558332
3set_longlines17.9258331
4other_purse_seines57.3775001
\n", + "
" + ], + "text/plain": [ + " gear_type hours vessel_ids\n", + "0 pots_and_traps 92.029722 3\n", + "1 inconclusive 215.623889 2\n", + "2 inconclusive 98.155833 2\n", + "3 set_longlines 17.925833 1\n", + "4 other_purse_seines 57.377500 1" + ] + }, + "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
0ARGTRAWLERS714.842500701000882FELIX AUGUSTO
1ARGTRAWLERS641.522222701000932ANTONIO ALVAREZ
2URYTRAWLERS10.023056770576463KALATXORI
3ARGTRAWLERS326.160833701079000ENTRENA UNO
4ARGTRAWLERS295.007500701000820CORAJE
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours mmsi ship_name\n", + "0 ARG TRAWLERS 714.842500 701000882 FELIX AUGUSTO\n", + "1 ARG TRAWLERS 641.522222 701000932 ANTONIO ALVAREZ\n", + "2 URY TRAWLERS 10.023056 770576463 KALATXORI\n", + "3 ARG TRAWLERS 326.160833 701079000 ENTRENA UNO\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': '2d939efefd3f45788ed103ff0723f564', 's...[{'name': 'CLEARWATER SEAFOODS', 'flag': 'CAN'...[{'id': 'de8a03acd-dc6c-8e08-2867-24e55ffc0017...
1[{'id': '45502524c9a150e77869ee647423dba1', 's...[{'name': 'GLACIAR PESQUERA', 'flag': 'ARG', '...[{'id': '8e930bac5-594b-aa3f-081d-d12668819e1f...
\n", + "
" + ], + "text/plain": [ + " registry_info \\\n", + "0 [{'id': '2d939efefd3f45788ed103ff0723f564', 's... \n", + "1 [{'id': '45502524c9a150e77869ee647423dba1', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'CLEARWATER SEAFOODS', 'flag': 'CAN'... \n", + "1 [{'name': 'GLACIAR PESQUERA', 'flag': 'ARG', '... \n", + "\n", + " self_reported_info \n", + "0 [{'id': 'de8a03acd-dc6c-8e08-2867-24e55ffc0017... \n", + "1 [{'id': '8e930bac5-594b-aa3f-081d-d12668819e1f... " + ] + }, + "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
0701006605ARGCAPESANTECAPESANTE[TRAWLERS][GFW-REVIEW, IMO, RESEARCH-PAPER, TMT_OTHER_OF...
1316003980CANATLANTICLEADERATLANTICLEADER[TRAWLERS][IMO, TMT_OTHER_OFFICIAL]
2701024000ARGATLANTIC SURF IIIATLANTICSURF3[TRAWLERS][IMO, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name gear_types \\\n", + "0 701006605 ARG CAPESANTE CAPESANTE [TRAWLERS] \n", + "1 316003980 CAN ATLANTICLEADER ATLANTICLEADER [TRAWLERS] \n", + "2 701024000 ARG ATLANTIC SURF III ATLANTICSURF3 [TRAWLERS] \n", + "\n", + " source_code \n", + "0 [GFW-REVIEW, IMO, RESEARCH-PAPER, TMT_OTHER_OF... \n", + "1 [IMO, TMT_OTHER_OFFICIAL] \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
0701006605CANCLEARWATER SEAFOODS[RESEARCH-PAPER]
1316003980CANCS MANPAR[TMT_OTHER_OFFICIAL]
2701024000ARGGLACIAR PESQUERA[TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag name source_code\n", + "0 701006605 CAN CLEARWATER SEAFOODS [RESEARCH-PAPER]\n", + "1 316003980 CAN CS MANPAR [TMT_OTHER_OFFICIAL]\n", + "2 701024000 ARG GLACIAR PESQUERA [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
0701006605ARGCAPESANTECAPESANTE[AIS]
1316003980CANATLANTIC LEADERATLANTICLEADER[AIS]
2701024000ARGATLANTIC SURF IIIATLANTICSURF3[AIS]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name source_code\n", + "0 701006605 ARG CAPESANTE CAPESANTE [AIS]\n", + "1 316003980 CAN ATLANTIC LEADER ATLANTICLEADER [AIS]\n", + "2 701024000 ARG ATLANTIC SURF III ATLANTICSURF3 [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 III701024000222.7216104.098386
1ATLANTIC SURF III7010240007.9053354.590909
2ATLANTIC SURF III7010240002.7946814.655555
3ATLANTIC SURF III7010240002.0123922.953846
4ATLANTIC SURF III7010240003.2600403.705556
...............
346CAPESANTE70100660525.5687964.074561
347CAPESANTE70100660545.8309803.771852
348CAPESANTE70100660574.6118304.087912
349CAPESANTE70100660582.6075253.788187
350CAPESANTE701006605205.8262824.136848
\n", + "

351 rows × 4 columns

\n", + "
" + ], + "text/plain": [ + " name ssvid total_distance_km average_speed_knots\n", + "0 ATLANTIC SURF III 701024000 222.721610 4.098386\n", + "1 ATLANTIC SURF III 701024000 7.905335 4.590909\n", + "2 ATLANTIC SURF III 701024000 2.794681 4.655555\n", + "3 ATLANTIC SURF III 701024000 2.012392 2.953846\n", + "4 ATLANTIC SURF III 701024000 3.260040 3.705556\n", + ".. ... ... ... ...\n", + "346 CAPESANTE 701006605 25.568796 4.074561\n", + "347 CAPESANTE 701006605 45.830980 3.771852\n", + "348 CAPESANTE 701006605 74.611830 4.087912\n", + "349 CAPESANTE 701006605 82.607525 3.788187\n", + "350 CAPESANTE 701006605 205.826282 4.136848\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
2ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
3CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
4ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
5CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
6ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
7CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
\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 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "3 CAPESANTE 701006605 4 USHUAIA \n", + "4 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "5 CAPESANTE 701006605 4 USHUAIA \n", + "6 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "7 CAPESANTE 701006605 4 USHUAIA \n", + "\n", + " intermediate_anchorage_name end_anchorage_name \n", + "0 MAR DEL PLATA MAR DEL PLATA \n", + "1 USHUAIA USHUAIA \n", + "2 MAR DEL PLATA MAR DEL PLATA \n", + "3 USHUAIA USHUAIA \n", + "4 MAR DEL PLATA MAR DEL PLATA \n", + "5 USHUAIA USHUAIA \n", + "6 MAR DEL PLATA MAR DEL PLATA \n", + "7 USHUAIA USHUAIA " + ] + }, + "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..76f7033 --- /dev/null +++ b/docs/source/workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez.ipynb @@ -0,0 +1,2005 @@ +{ + "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": "markdown", + "id": "53f445b9-02bb-425a-817a-2768941c7d5a", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "d93d57ae-0ec7-4d97-8fea-f679e89fc3b1", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "import pandas as pd\n", + "\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:\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
2Nonepole_and_line3481.5091675
3Noneother_purse_seines26.5811111
4Nonefishing20929.56333321
\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 pole_and_line 3481.509167 5\n", + "3 None other_purse_seines 26.581111 1\n", + "4 None fishing 20929.563333 21" + ] + }, + "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 SHUN41600749644.0268823.808824
1HUNG CHUAN SHUN4160074969.3535008.200000
2HUNG CHUAN SHUN4160074969.8680505.494444
3HUNG CHUAN SHUN41600749610.9553108.555556
4HUNG CHUAN SHUN4160074969.6306878.942857
...............
409HUNG CHUAN SHUN416007496101.4022634.041791
410HUNG CHUAN SHUN416007496115.6421594.743357
411HUNG CHUAN SHUN416007496100.0194564.402564
412HUNG CHUAN SHUN416007496155.9231384.975000
413HUNG CHUAN SHUN416007496173.2531374.869231
\n", + "

414 rows × 4 columns

\n", + "
" + ], + "text/plain": [ + " name ssvid total_distance_km average_speed_knots\n", + "0 HUNG CHUAN SHUN 416007496 44.026882 3.808824\n", + "1 HUNG CHUAN SHUN 416007496 9.353500 8.200000\n", + "2 HUNG CHUAN SHUN 416007496 9.868050 5.494444\n", + "3 HUNG CHUAN SHUN 416007496 10.955310 8.555556\n", + "4 HUNG CHUAN SHUN 416007496 9.630687 8.942857\n", + ".. ... ... ... ...\n", + "409 HUNG CHUAN SHUN 416007496 101.402263 4.041791\n", + "410 HUNG CHUAN SHUN 416007496 115.642159 4.743357\n", + "411 HUNG CHUAN SHUN 416007496 100.019456 4.402564\n", + "412 HUNG CHUAN SHUN 416007496 155.923138 4.975000\n", + "413 HUNG CHUAN SHUN 416007496 173.253137 4.869231\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
0SENSHU MARU NO.34311006904TEMATEMATEMA
1HUNG CHUAN SHUN4160074964TEMATEMATEMA
2SENSHU MARU NO.34311006904TEMATEMATEMA
3None4123310324DAKARDAKARDAKAR
\n", + "
" + ], + "text/plain": [ + " name ssvid confidence start_anchorage_name \\\n", + "0 SENSHU MARU NO.3 431100690 4 TEMA \n", + "1 HUNG CHUAN SHUN 416007496 4 TEMA \n", + "2 SENSHU MARU NO.3 431100690 4 TEMA \n", + "3 None 412331032 4 DAKAR \n", + "\n", + " intermediate_anchorage_name end_anchorage_name \n", + "0 TEMA TEMA \n", + "1 TEMA TEMA \n", + "2 TEMA TEMA \n", + "3 DAKAR DAKAR " + ] + }, + "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/getting-started.ipynb b/notebooks/getting-started.ipynb index 4be4609..d764948 100644 --- a/notebooks/getting-started.ipynb +++ b/notebooks/getting-started.ipynb @@ -120,9 +120,9 @@ }, "outputs": [], "source": [ - "import os\n", "import datetime\n", - "import pandas as pd\n", + "import os\n", + "\n", "import gfwapiclient as gfw" ] }, @@ -139,7 +139,7 @@ " from google.colab import userdata\n", "\n", " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", - "except Exception as exc:\n", + "except Exception:\n", " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", "\n", "access_token = access_token or \"\"" @@ -280,20 +280,20 @@ " []\n", " []\n", " []\n", - " [{'vessel_id': '91df2f8c7-74fd-5b5a-60f5-3d86f...\n", - " [{'id': '91df2f8c7-74fd-5b5a-60f5-3d86f9c51ff2...\n", - " [{'reference': '91df2f8c7-74fd-5b5a-60f5-3d86f...\n", + " [{'vessel_id': 'a5ef97d59-9f40-3bdc-e247-daf9c...\n", + " [{'id': 'a5ef97d59-9f40-3bdc-e247-daf9c892ceff...\n", + " [{'reference': 'a5ef97d59-9f40-3bdc-e247-daf9c...\n", " \n", " \n", " 1\n", " public-global-vessel-identity:v3.0\n", - " 1\n", - " [{'id': '4ef90bea19300c6a23f6ce627a80238b', 's...\n", - " [{'name': 'ZHOUSHAN SHUNHANG OCEAN FISHERIES',...\n", - " [{'date_from': 2017-01-04 00:00:00+00:00, 'dat...\n", - " [{'vessel_id': '755a48dd4-4bee-4bcf-7b5f-9baea...\n", - " [{'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b...\n", - " [{'reference': '755a48dd4-4bee-4bcf-7b5f-9baea...\n", + " 0\n", + " []\n", + " []\n", + " []\n", + " [{'vessel_id': '91df2f8c7-74fd-5b5a-60f5-3d86f...\n", + " [{'id': '91df2f8c7-74fd-5b5a-60f5-3d86f9c51ff2...\n", + " [{'reference': '91df2f8c7-74fd-5b5a-60f5-3d86f...\n", " \n", " \n", " 2\n", @@ -302,20 +302,20 @@ " []\n", " []\n", " []\n", - " [{'vessel_id': 'a5ef97d59-9f40-3bdc-e247-daf9c...\n", - " [{'id': 'a5ef97d59-9f40-3bdc-e247-daf9c892ceff...\n", - " [{'reference': 'a5ef97d59-9f40-3bdc-e247-daf9c...\n", + " [{'vessel_id': 'd2fbd05f5-57dd-1faa-c384-67a75...\n", + " [{'id': 'd2fbd05f5-57dd-1faa-c384-67a75f27fc80...\n", + " [{'reference': 'd2fbd05f5-57dd-1faa-c384-67a75...\n", " \n", " \n", " 3\n", " public-global-vessel-identity:v3.0\n", - " 0\n", - " []\n", - " []\n", - " []\n", - " [{'vessel_id': '108c5510b-b6aa-9cf2-8b86-0598d...\n", - " [{'id': '108c5510b-b6aa-9cf2-8b86-0598de546741...\n", - " [{'reference': '108c5510b-b6aa-9cf2-8b86-0598d...\n", + " 1\n", + " [{'id': '4ef90bea19300c6a23f6ce627a80238b', 's...\n", + " [{'name': 'ZHOUSHAN SHUNHANG OCEAN FISHERIES',...\n", + " [{'date_from': 2017-01-04 00:00:00+00:00, 'dat...\n", + " [{'vessel_id': '755a48dd4-4bee-4bcf-7b5f-9baea...\n", + " [{'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b...\n", + " [{'reference': '755a48dd4-4bee-4bcf-7b5f-9baea...\n", " \n", " \n", " 4\n", @@ -324,9 +324,9 @@ " []\n", " []\n", " []\n", - " [{'vessel_id': 'd2fbd05f5-57dd-1faa-c384-67a75...\n", - " [{'id': 'd2fbd05f5-57dd-1faa-c384-67a75f27fc80...\n", - " [{'reference': 'd2fbd05f5-57dd-1faa-c384-67a75...\n", + " [{'vessel_id': '108c5510b-b6aa-9cf2-8b86-0598d...\n", + " [{'id': '108c5510b-b6aa-9cf2-8b86-0598de546741...\n", + " [{'reference': '108c5510b-b6aa-9cf2-8b86-0598d...\n", " \n", " \n", "\n", @@ -335,52 +335,52 @@ "text/plain": [ " dataset registry_info_total_records \\\n", "0 public-global-vessel-identity:v3.0 0 \n", - "1 public-global-vessel-identity:v3.0 1 \n", + "1 public-global-vessel-identity:v3.0 0 \n", "2 public-global-vessel-identity:v3.0 0 \n", - "3 public-global-vessel-identity:v3.0 0 \n", + "3 public-global-vessel-identity:v3.0 1 \n", "4 public-global-vessel-identity:v3.0 0 \n", "\n", " registry_info \\\n", "0 [] \n", - "1 [{'id': '4ef90bea19300c6a23f6ce627a80238b', 's... \n", + "1 [] \n", "2 [] \n", - "3 [] \n", + "3 [{'id': '4ef90bea19300c6a23f6ce627a80238b', 's... \n", "4 [] \n", "\n", " registry_owners \\\n", "0 [] \n", - "1 [{'name': 'ZHOUSHAN SHUNHANG OCEAN FISHERIES',... \n", + "1 [] \n", "2 [] \n", - "3 [] \n", + "3 [{'name': 'ZHOUSHAN SHUNHANG OCEAN FISHERIES',... \n", "4 [] \n", "\n", " registry_public_authorizations \\\n", "0 [] \n", - "1 [{'date_from': 2017-01-04 00:00:00+00:00, 'dat... \n", + "1 [] \n", "2 [] \n", - "3 [] \n", + "3 [{'date_from': 2017-01-04 00:00:00+00:00, 'dat... \n", "4 [] \n", "\n", " combined_sources_info \\\n", - "0 [{'vessel_id': '91df2f8c7-74fd-5b5a-60f5-3d86f... \n", - "1 [{'vessel_id': '755a48dd4-4bee-4bcf-7b5f-9baea... \n", - "2 [{'vessel_id': 'a5ef97d59-9f40-3bdc-e247-daf9c... \n", - "3 [{'vessel_id': '108c5510b-b6aa-9cf2-8b86-0598d... \n", - "4 [{'vessel_id': 'd2fbd05f5-57dd-1faa-c384-67a75... \n", + "0 [{'vessel_id': 'a5ef97d59-9f40-3bdc-e247-daf9c... \n", + "1 [{'vessel_id': '91df2f8c7-74fd-5b5a-60f5-3d86f... \n", + "2 [{'vessel_id': 'd2fbd05f5-57dd-1faa-c384-67a75... \n", + "3 [{'vessel_id': '755a48dd4-4bee-4bcf-7b5f-9baea... \n", + "4 [{'vessel_id': '108c5510b-b6aa-9cf2-8b86-0598d... \n", "\n", " self_reported_info \\\n", - "0 [{'id': '91df2f8c7-74fd-5b5a-60f5-3d86f9c51ff2... \n", - "1 [{'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b... \n", - "2 [{'id': 'a5ef97d59-9f40-3bdc-e247-daf9c892ceff... \n", - "3 [{'id': '108c5510b-b6aa-9cf2-8b86-0598de546741... \n", - "4 [{'id': 'd2fbd05f5-57dd-1faa-c384-67a75f27fc80... \n", + "0 [{'id': 'a5ef97d59-9f40-3bdc-e247-daf9c892ceff... \n", + "1 [{'id': '91df2f8c7-74fd-5b5a-60f5-3d86f9c51ff2... \n", + "2 [{'id': 'd2fbd05f5-57dd-1faa-c384-67a75f27fc80... \n", + "3 [{'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b... \n", + "4 [{'id': '108c5510b-b6aa-9cf2-8b86-0598de546741... \n", "\n", " matchCriteria \n", - "0 [{'reference': '91df2f8c7-74fd-5b5a-60f5-3d86f... \n", - "1 [{'reference': '755a48dd4-4bee-4bcf-7b5f-9baea... \n", - "2 [{'reference': 'a5ef97d59-9f40-3bdc-e247-daf9c... \n", - "3 [{'reference': '108c5510b-b6aa-9cf2-8b86-0598d... \n", - "4 [{'reference': 'd2fbd05f5-57dd-1faa-c384-67a75... " + "0 [{'reference': 'a5ef97d59-9f40-3bdc-e247-daf9c... \n", + "1 [{'reference': '91df2f8c7-74fd-5b5a-60f5-3d86f... \n", + "2 [{'reference': 'd2fbd05f5-57dd-1faa-c384-67a75... \n", + "3 [{'reference': '755a48dd4-4bee-4bcf-7b5f-9baea... \n", + "4 [{'reference': '108c5510b-b6aa-9cf2-8b86-0598d... " ] }, "execution_count": 8, @@ -1018,85 +1018,85 @@ " \n", " \n", " 0\n", - " 2025-12-21 22:54:19+00:00\n", - " 2025-12-22 01:59:26+00:00\n", - " 20722d55b7a106978e2b55e65f7affa6\n", + " 2022-10-10 15:49:06+00:00\n", + " 2022-10-10 18:27:46+00:00\n", + " da35d28bfc433f251fe03c2ded3a5e23\n", " fishing\n", - " {'lat': -45.734, 'lon': -60.6275}\n", - " {'mpa': [], 'eez': [], 'rfmo': ['ICCAT', 'IWC'...\n", - " [-60.638205, -45.736243333333334, -60.622215, ...\n", - " {'start_distance_from_shore_km': 390.0, 'end_d...\n", - " {'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b'...\n", + " {'lat': 42.9677, 'lon': 156.9126}\n", + " {'mpa': [], 'eez': [], 'rfmo': ['ACAP', 'NPFC'...\n", + " [156.90262, 42.93749, 156.92824, 42.979495]\n", + " {'start_distance_from_shore_km': 585.0, 'end_d...\n", + " {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'...\n", " None\n", - " {'total_distance_km': 1.553408717842079, 'aver...\n", + " {'total_distance_km': 5.313381753510874, 'aver...\n", " None\n", " None\n", " None\n", " \n", " \n", " 1\n", - " 2020-05-29 15:38:07+00:00\n", - " 2020-05-29 19:22:03+00:00\n", - " aa6f570aee327010bd4714aa6e459d08\n", + " 2022-10-08 23:28:16+00:00\n", + " 2022-10-09 04:06:15+00:00\n", + " 080bcd728a84f62fe901a3e5b02c6014\n", " fishing\n", - " {'lat': 41.4151, 'lon': 165.5954}\n", - " {'mpa': [], 'eez': [], 'rfmo': ['NPAFC', 'PICE...\n", - " [165.58234666666667, 41.404185, 165.602265, 41...\n", - " {'start_distance_from_shore_km': 1213.0, 'end_...\n", + " {'lat': 43.0665, 'lon': 156.4381}\n", + " {'mpa': [], 'eez': [], 'rfmo': ['IWC', 'WCPFC'...\n", + " [156.38127166666666, 43.05014166666667, 156.49...\n", + " {'start_distance_from_shore_km': 549.0, 'end_d...\n", " {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'...\n", " None\n", - " {'total_distance_km': 3.2539329459390007, 'ave...\n", + " {'total_distance_km': 10.200405590755741, 'ave...\n", " None\n", " None\n", " None\n", " \n", " \n", " 2\n", - " 2025-12-31 23:00:02+00:00\n", - " 2026-01-01 07:57:31+00:00\n", - " 82ab07bcb2f0881dbdc2bea176f4d0eb\n", + " 2022-10-30 23:36:05+00:00\n", + " 2022-10-31 11:25:45+00:00\n", + " c79bf8fbab9e58bb3b279bf757bae197\n", " fishing\n", - " {'lat': -45.7853, 'lon': -60.6598}\n", - " {'mpa': [], 'eez': [], 'rfmo': ['ACAP', 'CCSBT...\n", - " [-60.66967666666667, -45.80526166666667, -60.6...\n", - " {'start_distance_from_shore_km': 390.0, 'end_d...\n", - " {'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b'...\n", + " {'lat': 41.0574, 'lon': 149.7023}\n", + " {'mpa': [], 'eez': ['48950'], 'rfmo': ['PICES'...\n", + " [149.66486666666665, 40.94216166666667, 149.73...\n", + " {'start_distance_from_shore_km': 392.0, 'end_d...\n", + " {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'...\n", " None\n", - " {'total_distance_km': 5.18218418253593, 'avera...\n", + " {'total_distance_km': 31.90361153133585, 'aver...\n", " None\n", " None\n", " None\n", " \n", " \n", " 3\n", - " 2021-03-23 22:31:06+00:00\n", - " 2021-03-24 06:45:12+00:00\n", - " 634e0f958283315e9850e1523e6f7a88\n", + " 2021-02-21 23:05:34+00:00\n", + " 2021-02-22 08:36:32+00:00\n", + " 3cdbebbfbf2b7c926158fa6955eecb30\n", " fishing\n", - " {'lat': -41.9474, 'lon': -57.9515}\n", - " {'mpa': [], 'eez': [], 'rfmo': ['ICCAT', 'IWC'...\n", - " [-57.89071, -41.96338333333333, -57.9833649999...\n", - " {'start_distance_from_shore_km': 377.0, 'end_d...\n", + " {'lat': -45.8329, 'lon': -60.603}\n", + " {'mpa': [], 'eez': [], 'rfmo': ['CCSBT', 'ICCA...\n", + " [-60.5669816667, -45.836216666666665, -60.6110...\n", + " {'start_distance_from_shore_km': 399.0, 'end_d...\n", " {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'...\n", " None\n", - " {'total_distance_km': 13.20298689870354, 'aver...\n", + " {'total_distance_km': 5.725649380735478, 'aver...\n", " None\n", " None\n", " None\n", " \n", " \n", " 4\n", - " 2022-06-17 12:52:22+00:00\n", - " 2022-06-17 18:55:39+00:00\n", - " 1c4ef3bc92b7a763c5f3b04d3a1a0779\n", + " 2020-05-26 16:43:39+00:00\n", + " 2020-05-26 18:25:46+00:00\n", + " 9b6a1c84d8daf3359a0d9917ff138d39\n", " fishing\n", - " {'lat': 42.8639, 'lon': 168.4996}\n", - " {'mpa': [], 'eez': [], 'rfmo': ['WCPFC', 'NPAF...\n", - " [168.47266833333333, 42.858135, 168.5181933333...\n", - " {'start_distance_from_shore_km': 1122.0, 'end_...\n", + " {'lat': 41.4176, 'lon': 165.3167}\n", + " {'mpa': [], 'eez': [], 'rfmo': ['IWC', 'NPFC',...\n", + " [165.315, 41.409706666666665, 165.31824, 41.42...\n", + " {'start_distance_from_shore_km': 1198.0, 'end_...\n", " {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'...\n", " None\n", - " {'total_distance_km': 4.430991184550807, 'aver...\n", + " {'total_distance_km': 2.3609454154613645, 'ave...\n", " None\n", " None\n", " None\n", @@ -1107,60 +1107,60 @@ ], "text/plain": [ " start end \\\n", - "0 2025-12-21 22:54:19+00:00 2025-12-22 01:59:26+00:00 \n", - "1 2020-05-29 15:38:07+00:00 2020-05-29 19:22:03+00:00 \n", - "2 2025-12-31 23:00:02+00:00 2026-01-01 07:57:31+00:00 \n", - "3 2021-03-23 22:31:06+00:00 2021-03-24 06:45:12+00:00 \n", - "4 2022-06-17 12:52:22+00:00 2022-06-17 18:55:39+00:00 \n", + "0 2022-10-10 15:49:06+00:00 2022-10-10 18:27:46+00:00 \n", + "1 2022-10-08 23:28:16+00:00 2022-10-09 04:06:15+00:00 \n", + "2 2022-10-30 23:36:05+00:00 2022-10-31 11:25:45+00:00 \n", + "3 2021-02-21 23:05:34+00:00 2021-02-22 08:36:32+00:00 \n", + "4 2020-05-26 16:43:39+00:00 2020-05-26 18:25:46+00:00 \n", "\n", " id type \\\n", - "0 20722d55b7a106978e2b55e65f7affa6 fishing \n", - "1 aa6f570aee327010bd4714aa6e459d08 fishing \n", - "2 82ab07bcb2f0881dbdc2bea176f4d0eb fishing \n", - "3 634e0f958283315e9850e1523e6f7a88 fishing \n", - "4 1c4ef3bc92b7a763c5f3b04d3a1a0779 fishing \n", + "0 da35d28bfc433f251fe03c2ded3a5e23 fishing \n", + "1 080bcd728a84f62fe901a3e5b02c6014 fishing \n", + "2 c79bf8fbab9e58bb3b279bf757bae197 fishing \n", + "3 3cdbebbfbf2b7c926158fa6955eecb30 fishing \n", + "4 9b6a1c84d8daf3359a0d9917ff138d39 fishing \n", "\n", - " position \\\n", - "0 {'lat': -45.734, 'lon': -60.6275} \n", - "1 {'lat': 41.4151, 'lon': 165.5954} \n", - "2 {'lat': -45.7853, 'lon': -60.6598} \n", - "3 {'lat': -41.9474, 'lon': -57.9515} \n", - "4 {'lat': 42.8639, 'lon': 168.4996} \n", + " position \\\n", + "0 {'lat': 42.9677, 'lon': 156.9126} \n", + "1 {'lat': 43.0665, 'lon': 156.4381} \n", + "2 {'lat': 41.0574, 'lon': 149.7023} \n", + "3 {'lat': -45.8329, 'lon': -60.603} \n", + "4 {'lat': 41.4176, 'lon': 165.3167} \n", "\n", " regions \\\n", - "0 {'mpa': [], 'eez': [], 'rfmo': ['ICCAT', 'IWC'... \n", - "1 {'mpa': [], 'eez': [], 'rfmo': ['NPAFC', 'PICE... \n", - "2 {'mpa': [], 'eez': [], 'rfmo': ['ACAP', 'CCSBT... \n", - "3 {'mpa': [], 'eez': [], 'rfmo': ['ICCAT', 'IWC'... \n", - "4 {'mpa': [], 'eez': [], 'rfmo': ['WCPFC', 'NPAF... \n", + "0 {'mpa': [], 'eez': [], 'rfmo': ['ACAP', 'NPFC'... \n", + "1 {'mpa': [], 'eez': [], 'rfmo': ['IWC', 'WCPFC'... \n", + "2 {'mpa': [], 'eez': ['48950'], 'rfmo': ['PICES'... \n", + "3 {'mpa': [], 'eez': [], 'rfmo': ['CCSBT', 'ICCA... \n", + "4 {'mpa': [], 'eez': [], 'rfmo': ['IWC', 'NPFC',... \n", "\n", " bounding_box \\\n", - "0 [-60.638205, -45.736243333333334, -60.622215, ... \n", - "1 [165.58234666666667, 41.404185, 165.602265, 41... \n", - "2 [-60.66967666666667, -45.80526166666667, -60.6... \n", - "3 [-57.89071, -41.96338333333333, -57.9833649999... \n", - "4 [168.47266833333333, 42.858135, 168.5181933333... \n", + "0 [156.90262, 42.93749, 156.92824, 42.979495] \n", + "1 [156.38127166666666, 43.05014166666667, 156.49... \n", + "2 [149.66486666666665, 40.94216166666667, 149.73... \n", + "3 [-60.5669816667, -45.836216666666665, -60.6110... \n", + "4 [165.315, 41.409706666666665, 165.31824, 41.42... \n", "\n", " distances \\\n", - "0 {'start_distance_from_shore_km': 390.0, 'end_d... \n", - "1 {'start_distance_from_shore_km': 1213.0, 'end_... \n", - "2 {'start_distance_from_shore_km': 390.0, 'end_d... \n", - "3 {'start_distance_from_shore_km': 377.0, 'end_d... \n", - "4 {'start_distance_from_shore_km': 1122.0, 'end_... \n", + "0 {'start_distance_from_shore_km': 585.0, 'end_d... \n", + "1 {'start_distance_from_shore_km': 549.0, 'end_d... \n", + "2 {'start_distance_from_shore_km': 392.0, 'end_d... \n", + "3 {'start_distance_from_shore_km': 399.0, 'end_d... \n", + "4 {'start_distance_from_shore_km': 1198.0, 'end_... \n", "\n", " vessel encounter \\\n", - "0 {'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b'... None \n", + "0 {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'... None \n", "1 {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'... None \n", - "2 {'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b'... None \n", + "2 {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'... None \n", "3 {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'... None \n", "4 {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'... None \n", "\n", " fishing gap loitering \\\n", - "0 {'total_distance_km': 1.553408717842079, 'aver... None None \n", - "1 {'total_distance_km': 3.2539329459390007, 'ave... None None \n", - "2 {'total_distance_km': 5.18218418253593, 'avera... None None \n", - "3 {'total_distance_km': 13.20298689870354, 'aver... None None \n", - "4 {'total_distance_km': 4.430991184550807, 'aver... None None \n", + "0 {'total_distance_km': 5.313381753510874, 'aver... None None \n", + "1 {'total_distance_km': 10.200405590755741, 'ave... None None \n", + "2 {'total_distance_km': 31.90361153133585, 'aver... None None \n", + "3 {'total_distance_km': 5.725649380735478, 'aver... None None \n", + "4 {'total_distance_km': 2.3609454154613645, 'ave... None None \n", "\n", " port_visit \n", "0 None \n", diff --git a/notebooks/usage-guides/4wings-api.ipynb b/notebooks/usage-guides/4wings-api.ipynb index d825bef..b523b61 100644 --- a/notebooks/usage-guides/4wings-api.ipynb +++ b/notebooks/usage-guides/4wings-api.ipynb @@ -28,7 +28,7 @@ "id": "e9ca2eda-18f1-4f9c-9717-fb1a06423958" }, "source": [ - "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access the 4Wings API, which is designed for generating reports and statistics on activities within specified regions." + "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access the [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api), which is designed for generating reports and statistics on activities within specified regions." ] }, { @@ -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), [AIS Apparent Fishing Effort Data Caveats](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort), [AIS Vessel Presence Data Caveats](https://globalfishingwatch.org/our-apis/documentation#ais-vessel-presence-caveats), [SAR Vessel Detections Data Caveats](https://globalfishingwatch.org/our-apis/documentation#sar-vessel-detections-data-caveats), 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." ] }, { @@ -101,6 +101,14 @@ "## Usage" ] }, + { + "cell_type": "markdown", + "id": "fe7df9a0-cd5e-4b99-94b4-07b2ca0481f0", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, { "cell_type": "code", "execution_count": 2, @@ -111,6 +119,7 @@ "outputs": [], "source": [ "import os\n", + "\n", "import gfwapiclient as gfw" ] }, @@ -127,7 +136,7 @@ " from google.colab import userdata\n", "\n", " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", - "except Exception as exc:\n", + "except Exception:\n", " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", "\n", "access_token = access_token or \"\"" @@ -165,7 +174,7 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": 38, "id": "338223ff-9c23-47f6-bf33-2aaaefc35081", "metadata": {}, "outputs": [], @@ -193,7 +202,7 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": 39, "id": "3bff3854-9b54-44c9-a7f8-3ef2bf1b7719", "metadata": {}, "outputs": [], @@ -203,7 +212,7 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 40, "id": "21e8b553-20dd-43bb-92c3-0e7f5f6f29c3", "metadata": {}, "outputs": [], @@ -213,7 +222,7 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": 41, "id": "29bd8b84-1f22-4a11-9861-548237926012", "metadata": {}, "outputs": [ @@ -223,7 +232,7 @@ "('2022-03', 'RUS', 7.109166666666667, 3, 75.8, 44.0)" ] }, - "execution_count": 8, + "execution_count": 41, "metadata": {}, "output_type": "execute_result" } @@ -249,7 +258,7 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": 42, "id": "a778ef19-f68d-4e0b-8b37-539db79868cb", "metadata": {}, "outputs": [], @@ -259,7 +268,51 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": 43, + "id": "271d446a-702d-42bb-93a9-e576741a3fdd", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 32271 entries, 0 to 32270\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 32271 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 32271 non-null object \n", + " 3 gear_type 0 non-null object \n", + " 4 hours 32271 non-null float64\n", + " 5 vessel_ids 32271 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 32271 non-null object \n", + " 17 ship_name 0 non-null object \n", + " 18 lat 32271 non-null float64\n", + " 19 lon 32271 non-null float64\n", + "dtypes: float64(3), int64(1), object(16)\n", + "memory usage: 4.9+ MB\n" + ] + } + ], + "source": [ + "fishing_effort_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 44, "id": "5145b645-c0fe-4780-b94f-261b534b7f04", "metadata": {}, "outputs": [ @@ -309,12 +362,12 @@ " \n", " \n", " 0\n", - " 2022-03\n", + " 2022-02\n", " None\n", " RUS\n", " None\n", - " 3.416944\n", - " 2\n", + " 58.298253\n", + " 18\n", " None\n", " None\n", " None\n", @@ -327,8 +380,8 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 75.6\n", - " 50.3\n", + " 54.5\n", + " 151.4\n", " \n", " \n", " 1\n", @@ -336,8 +389,8 @@ " None\n", " RUS\n", " None\n", - " 2.144444\n", - " 3\n", + " 53.717894\n", + " 9\n", " None\n", " None\n", " None\n", @@ -350,17 +403,17 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 51.4\n", - " 155.4\n", + " 70.4\n", + " 32.3\n", " \n", " \n", " 2\n", - " 2022-03\n", + " 2022-02\n", " None\n", " RUS\n", " None\n", - " 5.436944\n", - " 2\n", + " 1.083333\n", + " 1\n", " None\n", " None\n", " None\n", @@ -373,8 +426,8 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 58.6\n", - " 155.8\n", + " 56.2\n", + " 155.4\n", " \n", " \n", " 3\n", @@ -382,8 +435,8 @@ " None\n", " RUS\n", " None\n", - " 4.435556\n", - " 1\n", + " 5.364167\n", + " 2\n", " None\n", " None\n", " None\n", @@ -396,8 +449,8 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 45.7\n", - " 149.8\n", + " 50.0\n", + " 141.8\n", " \n", " \n", " 4\n", @@ -405,8 +458,8 @@ " None\n", " RUS\n", " None\n", - " 0.362778\n", - " 1\n", + " 2.393056\n", + " 2\n", " None\n", " None\n", " None\n", @@ -419,20 +472,20 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 46.7\n", - " 141.9\n", + " 56.2\n", + " 162.5\n", " \n", " \n", "\n", "" ], "text/plain": [ - " date detections flag gear_type hours vessel_ids vessel_id \\\n", - "0 2022-03 None RUS None 3.416944 2 None \n", - "1 2022-02 None RUS None 2.144444 3 None \n", - "2 2022-03 None RUS None 5.436944 2 None \n", - "3 2022-01 None RUS None 4.435556 1 None \n", - "4 2022-03 None RUS None 0.362778 1 None \n", + " date detections flag gear_type hours vessel_ids vessel_id \\\n", + "0 2022-02 None RUS None 58.298253 18 None \n", + "1 2022-02 None RUS None 53.717894 9 None \n", + "2 2022-02 None RUS None 1.083333 1 None \n", + "3 2022-01 None RUS None 5.364167 2 None \n", + "4 2022-03 None RUS None 2.393056 2 None \n", "\n", " vessel_type entry_timestamp exit_timestamp first_transmission_date \\\n", "0 None None None None \n", @@ -449,14 +502,14 @@ "4 None None None None None \n", "\n", " report_dataset ship_name lat lon \n", - "0 public-global-fishing-effort:v3.0 None 75.6 50.3 \n", - "1 public-global-fishing-effort:v3.0 None 51.4 155.4 \n", - "2 public-global-fishing-effort:v3.0 None 58.6 155.8 \n", - "3 public-global-fishing-effort:v3.0 None 45.7 149.8 \n", - "4 public-global-fishing-effort:v3.0 None 46.7 141.9 " + "0 public-global-fishing-effort:v3.0 None 54.5 151.4 \n", + "1 public-global-fishing-effort:v3.0 None 70.4 32.3 \n", + "2 public-global-fishing-effort:v3.0 None 56.2 155.4 \n", + "3 public-global-fishing-effort:v3.0 None 50.0 141.8 \n", + "4 public-global-fishing-effort:v3.0 None 56.2 162.5 " ] }, - "execution_count": 10, + "execution_count": 44, "metadata": {}, "output_type": "execute_result" } @@ -491,7 +544,7 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 45, "id": "0946a5ab-5090-4920-94dd-88c733528f5b", "metadata": {}, "outputs": [], @@ -519,7 +572,7 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 46, "id": "5a5d349d-f60f-4fd3-997e-f74c82d2d4f9", "metadata": {}, "outputs": [], @@ -529,7 +582,7 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 47, "id": "f4435324-5b39-40dd-897e-6a7ef7620a93", "metadata": {}, "outputs": [], @@ -539,7 +592,7 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 49, "id": "b2990454-d924-4288-8e4f-90e4ab60015b", "metadata": {}, "outputs": [ @@ -549,7 +602,7 @@ "('2022-03', 'RUS', 1.0, 1, 52.1, 153.2)" ] }, - "execution_count": 14, + "execution_count": 49, "metadata": {}, "output_type": "execute_result" } @@ -575,7 +628,7 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": 50, "id": "4ad188a4-fbaf-41ee-ab4b-6aeda56e0e57", "metadata": {}, "outputs": [], @@ -585,7 +638,51 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": 51, + "id": "71bee1f2-2316-4908-9fdf-668854cd3c49", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 274333 entries, 0 to 274332\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 274333 non-null object \n", + " 1 detections 0 non-null object \n", + " 2 flag 274333 non-null object \n", + " 3 gear_type 0 non-null object \n", + " 4 hours 274333 non-null float64\n", + " 5 vessel_ids 274333 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 274333 non-null object \n", + " 17 ship_name 0 non-null object \n", + " 18 lat 274333 non-null float64\n", + " 19 lon 274333 non-null float64\n", + "dtypes: float64(3), int64(1), object(16)\n", + "memory usage: 41.9+ MB\n" + ] + } + ], + "source": [ + "ais_presence_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 52, "id": "b8c04941-74fc-4a46-bc00-9e66afc59e10", "metadata": {}, "outputs": [ @@ -782,7 +879,7 @@ "4 public-global-presence:v3.0 None 50.0 157.0 " ] }, - "execution_count": 16, + "execution_count": 52, "metadata": {}, "output_type": "execute_result" } @@ -817,7 +914,7 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 19, "id": "45789061-c4e1-4938-b061-79122adb25da", "metadata": {}, "outputs": [], @@ -845,7 +942,7 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 53, "id": "c8f3894f-9d4a-4b2a-8f18-751c8155fddb", "metadata": {}, "outputs": [], @@ -855,7 +952,7 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": 54, "id": "c138eca3-4921-4056-8b68-6d658901fd17", "metadata": {}, "outputs": [], @@ -865,7 +962,7 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": 55, "id": "50d60501-e2c2-4b41-a341-845440c8cc8f", "metadata": {}, "outputs": [ @@ -875,7 +972,7 @@ "('2022-04', '', 1, 1, 46.6, 142.6)" ] }, - "execution_count": 20, + "execution_count": 55, "metadata": {}, "output_type": "execute_result" } @@ -901,7 +998,7 @@ }, { "cell_type": "code", - "execution_count": 21, + "execution_count": 56, "id": "05179b03-f391-45c7-86ce-c26e3f27eef0", "metadata": {}, "outputs": [], @@ -911,7 +1008,51 @@ }, { "cell_type": "code", - "execution_count": 22, + "execution_count": 72, + "id": "e8fa4e6f-efb9-4e5a-96f9-679bbc3578f8", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 3995 entries, 0 to 3994\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 3995 non-null object \n", + " 1 detections 3995 non-null int64 \n", + " 2 flag 3995 non-null object \n", + " 3 gear_type 0 non-null object \n", + " 4 hours 0 non-null object \n", + " 5 vessel_ids 3995 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 3995 non-null object \n", + " 17 ship_name 0 non-null object \n", + " 18 lat 3995 non-null float64\n", + " 19 lon 3995 non-null float64\n", + "dtypes: float64(2), int64(2), object(16)\n", + "memory usage: 624.3+ KB\n" + ] + } + ], + "source": [ + "sar_presence_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 58, "id": "6b1fee79-c5ab-42f6-98fe-7c0be9312b1e", "metadata": {}, "outputs": [ @@ -961,9 +1102,9 @@ " \n", " \n", " 0\n", - " 2022-01\n", + " 2022-02\n", " 1\n", - " \n", + " LBR\n", " None\n", " None\n", " 1\n", @@ -979,17 +1120,17 @@ " None\n", " public-global-sar-presence:v3.0\n", " None\n", - " 44.6\n", - " 38.0\n", + " 47.2\n", + " 153.0\n", " \n", " \n", " 1\n", - " 2022-03\n", - " 3\n", - " RUS\n", + " 2022-02\n", + " 1\n", + " BHS\n", " None\n", " None\n", - " 3\n", + " 1\n", " None\n", " None\n", " None\n", @@ -1002,14 +1143,14 @@ " None\n", " public-global-sar-presence:v3.0\n", " None\n", - " 46.7\n", - " 141.8\n", + " 44.2\n", + " 37.3\n", " \n", " \n", " 2\n", - " 2022-04\n", + " 2022-02\n", " 1\n", - " RUS\n", + " \n", " None\n", " None\n", " 1\n", @@ -1025,17 +1166,17 @@ " None\n", " public-global-sar-presence:v3.0\n", " None\n", - " 46.8\n", - " 141.4\n", + " 46.3\n", + " 142.4\n", " \n", " \n", " 3\n", - " 2022-02\n", - " 2\n", - " GRC\n", + " 2022-04\n", + " 17\n", + " RUS\n", " None\n", " None\n", - " 2\n", + " 14\n", " None\n", " None\n", " None\n", @@ -1048,14 +1189,14 @@ " None\n", " public-global-sar-presence:v3.0\n", " None\n", - " 44.2\n", - " 37.4\n", + " 45.5\n", + " 36.7\n", " \n", " \n", " 4\n", - " 2022-01\n", + " 2022-04\n", " 1\n", - " MLT\n", + " SGP\n", " None\n", " None\n", " 1\n", @@ -1071,8 +1212,8 @@ " None\n", " public-global-sar-presence:v3.0\n", " None\n", - " 43.8\n", - " 38.7\n", + " 46.3\n", + " 151.9\n", " \n", " \n", "\n", @@ -1080,11 +1221,11 @@ ], "text/plain": [ " date detections flag gear_type hours vessel_ids vessel_id vessel_type \\\n", - "0 2022-01 1 None None 1 None None \n", - "1 2022-03 3 RUS None None 3 None None \n", - "2 2022-04 1 RUS None None 1 None None \n", - "3 2022-02 2 GRC None None 2 None None \n", - "4 2022-01 1 MLT None None 1 None None \n", + "0 2022-02 1 LBR None None 1 None None \n", + "1 2022-02 1 BHS None None 1 None None \n", + "2 2022-02 1 None None 1 None None \n", + "3 2022-04 17 RUS None None 14 None None \n", + "4 2022-04 1 SGP None None 1 None None \n", "\n", " entry_timestamp exit_timestamp first_transmission_date \\\n", "0 None None None \n", @@ -1101,14 +1242,14 @@ "4 None None None None None \n", "\n", " report_dataset ship_name lat lon \n", - "0 public-global-sar-presence:v3.0 None 44.6 38.0 \n", - "1 public-global-sar-presence:v3.0 None 46.7 141.8 \n", - "2 public-global-sar-presence:v3.0 None 46.8 141.4 \n", - "3 public-global-sar-presence:v3.0 None 44.2 37.4 \n", - "4 public-global-sar-presence:v3.0 None 43.8 38.7 " + "0 public-global-sar-presence:v3.0 None 47.2 153.0 \n", + "1 public-global-sar-presence:v3.0 None 44.2 37.3 \n", + "2 public-global-sar-presence:v3.0 None 46.3 142.4 \n", + "3 public-global-sar-presence:v3.0 None 45.5 36.7 \n", + "4 public-global-sar-presence:v3.0 None 46.3 151.9 " ] }, - "execution_count": 22, + "execution_count": 58, "metadata": {}, "output_type": "execute_result" } @@ -1145,7 +1286,7 @@ }, { "cell_type": "code", - "execution_count": 23, + "execution_count": 26, "id": "d446f679-746a-4942-a5e0-ef1ca1324d65", "metadata": { "id": "d446f679-746a-4942-a5e0-ef1ca1324d65" @@ -1156,7 +1297,11 @@ " spatial_resolution=\"LOW\",\n", " temporal_resolution=\"MONTHLY\",\n", " group_by=\"FLAG\",\n", - " datasets=[\"public-global-fishing-effort:latest\"],\n", + " datasets=[\n", + " \"public-global-fishing-effort:latest\",\n", + " \"public-global-sar-presence:latest\",\n", + " \"public-global-presence:latest\",\n", + " ],\n", " start_date=\"2022-01-01\",\n", " end_date=\"2022-05-01\",\n", " region={\n", @@ -1178,7 +1323,7 @@ }, { "cell_type": "code", - "execution_count": 24, + "execution_count": 67, "id": "cc7947e2-d2cb-45b1-b47b-818bf4bebc95", "metadata": { "id": "cc7947e2-d2cb-45b1-b47b-818bf4bebc95" @@ -1190,7 +1335,7 @@ }, { "cell_type": "code", - "execution_count": 25, + "execution_count": 68, "id": "198ad2ee-a199-4d9e-8e76-0deb8395461f", "metadata": { "id": "198ad2ee-a199-4d9e-8e76-0deb8395461f" @@ -1202,7 +1347,7 @@ }, { "cell_type": "code", - "execution_count": 26, + "execution_count": 69, "id": "2ba5f27b-f881-40a2-a75b-f00a139f1d34", "metadata": { "colab": { @@ -1215,10 +1360,10 @@ { "data": { "text/plain": [ - "('2022-03', 'RUS', 7.109166666666667, 3, 75.8, 44.0)" + "('2022-03', 'RUS', 1.0, 1, 52.1, 153.2)" ] }, - "execution_count": 26, + "execution_count": 69, "metadata": {}, "output_type": "execute_result" } @@ -1246,7 +1391,7 @@ }, { "cell_type": "code", - "execution_count": 27, + "execution_count": 62, "id": "3720799b-192f-4b77-9ca2-a3614942d2d7", "metadata": { "id": "3720799b-192f-4b77-9ca2-a3614942d2d7" @@ -1258,7 +1403,51 @@ }, { "cell_type": "code", - "execution_count": 28, + "execution_count": 66, + "id": "7f298c61-d038-4d2e-86f2-2d5a554aa267", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 310599 entries, 0 to 310598\n", + "Data columns (total 20 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 date 310599 non-null object \n", + " 1 detections 3995 non-null float64\n", + " 2 flag 310599 non-null object \n", + " 3 gear_type 0 non-null object \n", + " 4 hours 306604 non-null float64\n", + " 5 vessel_ids 310599 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 310599 non-null object \n", + " 17 ship_name 0 non-null object \n", + " 18 lat 310599 non-null float64\n", + " 19 lon 310599 non-null float64\n", + "dtypes: float64(4), int64(1), object(15)\n", + "memory usage: 47.4+ MB\n" + ] + } + ], + "source": [ + "report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 64, "id": "8cce33de-675d-42c6-8eac-36974a9e7f48", "metadata": { "colab": { @@ -1316,7 +1505,7 @@ " \n", " 0\n", " 2022-03\n", - " None\n", + " NaN\n", " RUS\n", " None\n", " 3.416944\n", @@ -1339,7 +1528,7 @@ " \n", " 1\n", " 2022-02\n", - " None\n", + " NaN\n", " RUS\n", " None\n", " 2.144444\n", @@ -1362,7 +1551,7 @@ " \n", " 2\n", " 2022-03\n", - " None\n", + " NaN\n", " RUS\n", " None\n", " 5.436944\n", @@ -1385,7 +1574,7 @@ " \n", " 3\n", " 2022-01\n", - " None\n", + " NaN\n", " RUS\n", " None\n", " 4.435556\n", @@ -1408,7 +1597,7 @@ " \n", " 4\n", " 2022-03\n", - " None\n", + " NaN\n", " RUS\n", " None\n", " 0.362778\n", @@ -1433,12 +1622,12 @@ "" ], "text/plain": [ - " date detections flag gear_type hours vessel_ids vessel_id \\\n", - "0 2022-03 None RUS None 3.416944 2 None \n", - "1 2022-02 None RUS None 2.144444 3 None \n", - "2 2022-03 None RUS None 5.436944 2 None \n", - "3 2022-01 None RUS None 4.435556 1 None \n", - "4 2022-03 None RUS None 0.362778 1 None \n", + " date detections flag gear_type hours vessel_ids vessel_id \\\n", + "0 2022-03 NaN RUS None 3.416944 2 None \n", + "1 2022-02 NaN RUS None 2.144444 3 None \n", + "2 2022-03 NaN RUS None 5.436944 2 None \n", + "3 2022-01 NaN RUS None 4.435556 1 None \n", + "4 2022-03 NaN RUS None 0.362778 1 None \n", "\n", " vessel_type entry_timestamp exit_timestamp first_transmission_date \\\n", "0 None None None None \n", @@ -1462,7 +1651,7 @@ "4 public-global-fishing-effort:v3.0 None 46.7 141.9 " ] }, - "execution_count": 28, + "execution_count": 64, "metadata": {}, "output_type": "execute_result" } diff --git a/notebooks/usage-guides/bulk-downloads-api.ipynb b/notebooks/usage-guides/bulk-downloads-api.ipynb new file mode 100644 index 0000000..fb7b832 --- /dev/null +++ b/notebooks/usage-guides/bulk-downloads-api.ipynb @@ -0,0 +1,1409 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "7f3b7119", + "metadata": { + "colab_type": "text", + "id": "view-in-github" + }, + "source": [ + "\"Open" + ] + }, + { + "cell_type": "markdown", + "id": "493f86ff-cee9-4fb0-8e5f-b3a0903df39e", + "metadata": { + "id": "493f86ff-cee9-4fb0-8e5f-b3a0903df39e" + }, + "source": [ + "# Bulk Download API" + ] + }, + { + "cell_type": "markdown", + "id": "e9ca2eda-18f1-4f9c-9717-fb1a06423958", + "metadata": { + "id": "e9ca2eda-18f1-4f9c-9717-fb1a06423958" + }, + "source": [ + "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access the [Bulk Download API](https://globalfishingwatch.org/our-apis/documentation#bulk-download-api), which is designed to support workflows that require bulk access to data, including integration with platforms and tools used by data engineers and researchers." + ] + }, + { + "cell_type": "markdown", + "id": "3d31e934-e291-453d-aad9-6e0e61d1318e", + "metadata": {}, + "source": [ + "**Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), [SAR (Synthetic-Aperture Radar) Data Caveats](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats), 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": "cb352526-90e2-45fd-8732-e34f0342f30f", + "metadata": { + "id": "cb352526-90e2-45fd-8732-e34f0342f30f" + }, + "source": [ + "## Prerequisites" + ] + }, + { + "cell_type": "markdown", + "id": "57109889-5f3f-45b3-a594-2f82b94bcadb", + "metadata": { + "id": "57109889-5f3f-45b3-a594-2f82b94bcadb" + }, + "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": "3d1d4bf0-e6f7-4bda-9a79-4c6b6a42d1a1", + "metadata": { + "id": "3d1d4bf0-e6f7-4bda-9a79-4c6b6a42d1a1" + }, + "source": [ + "## Installation" + ] + }, + { + "cell_type": "markdown", + "id": "e8ed8d6d-214c-4888-bbb9-3798adabe12b", + "metadata": { + "id": "e8ed8d6d-214c-4888-bbb9-3798adabe12b" + }, + "source": [ + "The `gfw-api-python-client` can be easily installed using pip:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "d863fe42-f9f6-4a6e-b736-f0adc82581fe", + "metadata": { + "id": "d863fe42-f9f6-4a6e-b736-f0adc82581fe" + }, + "outputs": [], + "source": [ + "# %pip install gfw-api-python-client" + ] + }, + { + "cell_type": "markdown", + "id": "9c023a54-4d23-4cc2-bd36-659d4d78789e", + "metadata": { + "id": "9c023a54-4d23-4cc2-bd36-659d4d78789e" + }, + "source": [ + "## Usage" + ] + }, + { + "cell_type": "markdown", + "id": "fe7df9a0-cd5e-4b99-94b4-07b2ca0481f0", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "2420e772-c8c6-4eec-bbab-db0708733b50", + "metadata": { + "id": "2420e772-c8c6-4eec-bbab-db0708733b50" + }, + "outputs": [], + "source": [ + "import time\n", + "import os\n", + "\n", + "import gfwapiclient as gfw" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "c1fae7c8-2806-4468-84f0-2ca90b4f5653", + "metadata": { + "id": "c1fae7c8-2806-4468-84f0-2ca90b4f5653" + }, + "outputs": [], + "source": [ + "try:\n", + " from google.colab import userdata\n", + "\n", + " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", + "except Exception:\n", + " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", + "\n", + "access_token = access_token or \"\"" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "08c9daef-552d-4906-ac21-eaedcea7b102", + "metadata": { + "id": "08c9daef-552d-4906-ac21-eaedcea7b102" + }, + "outputs": [], + "source": [ + "gfw_client = gfw.Client(\n", + " access_token=access_token,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "1528b997-f892-46d3-976f-4b81794b1f3a", + "metadata": {}, + "source": [ + "## Create a Bulk Report (`create_bulk_report`)" + ] + }, + { + "cell_type": "markdown", + "id": "73b742ef-d9f5-4903-8ff9-743d7486b126", + "metadata": {}, + "source": [ + "The `create_bulk_report()` method allows you **create** a bulk report based on specified filters and spatial parameters. The `name` parameter is mandatory. Please [learn more about create a bulk report here](https://globalfishingwatch.org/our-apis/documentation#create-a-bulk-report) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [here](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats)." + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "a0496b62-ca37-4d36-adb8-42ab8b69690e", + "metadata": {}, + "outputs": [], + "source": [ + "timestamp = int(time.time() * 1000)\n", + "dataset = \"public-fixed-infrastructure-data:latest\"\n", + "region_dataset = \"public-eez-areas\"\n", + "region_id = \"8466\" # Argentinian Exclusive Economic Zone\n", + "name = f\"{dataset.split(':')[0]}_{region_dataset}__{region_id}_{timestamp}\"" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "aebdbd17-f0da-4f76-929d-ad26a53d5e1b", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'public-fixed-infrastructure-data_public-eez-areas__8466_1768085547174'" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "name" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "802695e0-d728-4194-967d-7a6eba3a5916", + "metadata": {}, + "outputs": [], + "source": [ + "create_bulk_report_result = await gfw_client.bulk_downloads.create_bulk_report(\n", + " name=name,\n", + " dataset=dataset,\n", + " region={\n", + " \"dataset\": region_dataset,\n", + " \"id\": region_id,\n", + " },\n", + " filters=[\"label = 'oil'\", \"label_confidence = 'high'\"],\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b1bb0495-6fd0-48e3-9583-429dd8d8b778", + "metadata": {}, + "source": [ + "### Access Create a Bulk Report Result as Pydantic models" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "fb381ffe-1441-4543-866d-f47ea4675f40", + "metadata": {}, + "outputs": [], + "source": [ + "create_bulk_report_data = create_bulk_report_result.data()" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "d2dc3e1e-c332-4d91-9209-a0680a67d31c", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "('c5e32895-4374-41d2-8b2e-ac414ed6757f',\n", + " 'public-fixed-infrastructure-data_public-eez-areas__8466_1768085547174',\n", + " 'pending',\n", + " datetime.datetime(2026, 1, 10, 22, 52, 30, 9000, tzinfo=TzInfo(0)))" + ] + }, + "execution_count": 9, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "(\n", + " create_bulk_report_data.id,\n", + " create_bulk_report_data.name,\n", + " create_bulk_report_data.status,\n", + " create_bulk_report_data.created_at,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b9d29b17-db63-4b07-9736-8fab781833d6", + "metadata": {}, + "source": [ + "### Access Create a Bulk Report Result as a DataFrame" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "f68b5906-3811-47f1-ad3d-a4a3ab14b374", + "metadata": {}, + "outputs": [], + "source": [ + "create_bulk_report_df = create_bulk_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "6744d8c2-a550-4635-8aed-4a58c0f2d64d", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 1 entries, 0 to 0\n", + "Data columns (total 12 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 1 non-null object \n", + " 1 name 1 non-null object \n", + " 2 file_path 1 non-null object \n", + " 3 format 1 non-null object \n", + " 4 filters 1 non-null object \n", + " 5 geom 1 non-null object \n", + " 6 status 1 non-null object \n", + " 7 owner_id 1 non-null int64 \n", + " 8 owner_type 1 non-null object \n", + " 9 created_at 1 non-null datetime64[ns, UTC]\n", + " 10 updated_at 1 non-null datetime64[ns, UTC]\n", + " 11 file_size 0 non-null object \n", + "dtypes: datetime64[ns, UTC](2), int64(1), object(9)\n", + "memory usage: 228.0+ bytes\n" + ] + } + ], + "source": [ + "create_bulk_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "d152ac16-99f6-4675-8f6e-a7f92302e4c2", + "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", + "
idnamefile_pathformatfiltersgeomstatusowner_idowner_typecreated_atupdated_atfile_size
0c5e32895-4374-41d2-8b2e-ac414ed6757fpublic-fixed-infrastructure-data_public-eez-ar...sar_fixed_infrastructure_202409.csvJSON[label = 'oil', label_confidence = 'high']{'type': 'dataset', 'dataset': 'public-eez-are...pending39application2026-01-10 22:52:30.009000+00:002026-01-10 22:52:30.009000+00:00None
\n", + "
" + ], + "text/plain": [ + " id \\\n", + "0 c5e32895-4374-41d2-8b2e-ac414ed6757f \n", + "\n", + " name \\\n", + "0 public-fixed-infrastructure-data_public-eez-ar... \n", + "\n", + " file_path format \\\n", + "0 sar_fixed_infrastructure_202409.csv JSON \n", + "\n", + " filters \\\n", + "0 [label = 'oil', label_confidence = 'high'] \n", + "\n", + " geom status owner_id \\\n", + "0 {'type': 'dataset', 'dataset': 'public-eez-are... pending 39 \n", + "\n", + " owner_type created_at \\\n", + "0 application 2026-01-10 22:52:30.009000+00:00 \n", + "\n", + " updated_at file_size \n", + "0 2026-01-10 22:52:30.009000+00:00 None " + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "create_bulk_report_df.head()" + ] + }, + { + "cell_type": "markdown", + "id": "ba3d1019-43d4-4d78-8b05-1b9a875aff73", + "metadata": {}, + "source": [ + "## Get Bulk Report by ID (`get_bulk_report_by_id`)" + ] + }, + { + "cell_type": "markdown", + "id": "b577a216-dd60-420f-aeef-51243eb09a32", + "metadata": {}, + "source": [ + "The `get_bulk_report_by_id()` method allows you retrieves **metadata and status** of the previously created bulk report based on the provided bulk report ID. The `id` parameter is mandatory. Please [learn more about get bulk report by id report here](https://globalfishingwatch.org/our-apis/documentation#get-bulk-report-by-id) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [here](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats)." + ] + }, + { + "cell_type": "markdown", + "id": "60e5e9ba-33a2-438f-8528-0366779e6e70", + "metadata": {}, + "source": [ + " **Important:** We recommend to use this method to poll the status of previously created bulk report, if it takes **several minutes or hours** to generate until it status is `done` or `failed`." + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "1a05b7ff-26fb-40ad-b578-74e7647eb687", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_report_result = await gfw_client.bulk_downloads.get_bulk_report_by_id(\n", + " id=create_bulk_report_data.id\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "da68ee08-c25d-40aa-b0a7-520e8408f529", + "metadata": {}, + "source": [ + "### Access Get Bulk Report by ID Result as Pydantic models" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "2f064920-a66c-48d8-9f20-2fb36b7dc4bc", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_report_data = bulk_report_result.data()" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "a966e319-3214-410e-b063-e0f51f68d04c", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "('c5e32895-4374-41d2-8b2e-ac414ed6757f',\n", + " 'public-fixed-infrastructure-data_public-eez-areas__8466_1768085547174',\n", + " 'pending',\n", + " datetime.datetime(2026, 1, 10, 22, 52, 30, 9000, tzinfo=TzInfo(0)))" + ] + }, + "execution_count": 15, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "(\n", + " create_bulk_report_data.id,\n", + " create_bulk_report_data.name,\n", + " create_bulk_report_data.status,\n", + " create_bulk_report_data.created_at,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "d33878dc-be26-47c1-9e28-68127c4c2869", + "metadata": {}, + "source": [ + "### Access Get Bulk Report by ID Result as a DataFrame" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "7cf258fa-e0d0-45c3-9f39-06f547f61529", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_report_df = bulk_report_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "57381d93-fdf1-4fd3-aec2-71bbdf877bc8", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 1 entries, 0 to 0\n", + "Data columns (total 12 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 1 non-null object \n", + " 1 name 1 non-null object \n", + " 2 file_path 1 non-null object \n", + " 3 format 1 non-null object \n", + " 4 filters 1 non-null object \n", + " 5 geom 1 non-null object \n", + " 6 status 1 non-null object \n", + " 7 owner_id 1 non-null int64 \n", + " 8 owner_type 1 non-null object \n", + " 9 created_at 1 non-null datetime64[ns, UTC]\n", + " 10 updated_at 1 non-null datetime64[ns, UTC]\n", + " 11 file_size 0 non-null object \n", + "dtypes: datetime64[ns, UTC](2), int64(1), object(9)\n", + "memory usage: 228.0+ bytes\n" + ] + } + ], + "source": [ + "bulk_report_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "89f76538-0bc2-4258-bb27-410cd9cc5b85", + "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", + "
idnamefile_pathformatfiltersgeomstatusowner_idowner_typecreated_atupdated_atfile_size
0c5e32895-4374-41d2-8b2e-ac414ed6757fpublic-fixed-infrastructure-data_public-eez-ar...sar_fixed_infrastructure_202409.csvJSON[label = 'oil', label_confidence = 'high']{'type': 'dataset', 'dataset': 'public-eez-are...pending39application2026-01-10 22:52:30.009000+00:002026-01-10 22:52:30.009000+00:00None
\n", + "
" + ], + "text/plain": [ + " id \\\n", + "0 c5e32895-4374-41d2-8b2e-ac414ed6757f \n", + "\n", + " name \\\n", + "0 public-fixed-infrastructure-data_public-eez-ar... \n", + "\n", + " file_path format \\\n", + "0 sar_fixed_infrastructure_202409.csv JSON \n", + "\n", + " filters \\\n", + "0 [label = 'oil', label_confidence = 'high'] \n", + "\n", + " geom status owner_id \\\n", + "0 {'type': 'dataset', 'dataset': 'public-eez-are... pending 39 \n", + "\n", + " owner_type created_at \\\n", + "0 application 2026-01-10 22:52:30.009000+00:00 \n", + "\n", + " updated_at file_size \n", + "0 2026-01-10 22:52:30.009000+00:00 None " + ] + }, + "execution_count": 18, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "bulk_report_df.head()" + ] + }, + { + "cell_type": "markdown", + "id": "c30c9de1-8fcc-45cc-91ad-339d1e1944ee", + "metadata": {}, + "source": [ + "## Get All Bulk Reports Created by User or Application (`get_all_bulk_reports`)" + ] + }, + { + "cell_type": "markdown", + "id": "d5f9e8ad-f137-446b-a38f-9caa4f233925", + "metadata": {}, + "source": [ + "The `get_all_bulk_reports()` method allows you retrieves a list of **metadata and status** of the previously created bulk reports based on specified pagination, sorting, and filtering criteria. Please [learn more about get all bulk reports created by user or application here](https://globalfishingwatch.org/our-apis/documentation#get-all-bulk-reports-by-user) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [here](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats)." + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "338223ff-9c23-47f6-bf33-2aaaefc35081", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_reports_result = await gfw_client.bulk_downloads.get_all_bulk_reports(\n", + " status=\"done\",\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "86738d44-fed7-4dd9-8014-d72ae3c22ae7", + "metadata": {}, + "source": [ + "### Access All Created Bulk Reports Result as Pydantic models" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "3bff3854-9b54-44c9-a7f8-3ef2bf1b7719", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_reports_data = bulk_reports_result.data()" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "21e8b553-20dd-43bb-92c3-0e7f5f6f29c3", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_report_item = bulk_reports_data[-1]" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "29bd8b84-1f22-4a11-9861-548237926012", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "('0c0cada1-72dd-4fb0-bdf6-7fe8c7fdb1e3',\n", + " 'sar-fixed-infrastructure-data-20241207-region-1',\n", + " 'done',\n", + " datetime.datetime(2025, 12, 7, 10, 3, 12, 371000, tzinfo=TzInfo(0)))" + ] + }, + "execution_count": 22, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "(\n", + " bulk_report_item.id,\n", + " bulk_report_item.name,\n", + " bulk_report_item.status,\n", + " bulk_report_item.created_at,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "f1294498-7b8c-4054-85b3-a24ecee90340", + "metadata": {}, + "source": [ + "### Access All Created Bulk Reports Result as a DataFrame" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "a778ef19-f68d-4e0b-8b37-539db79868cb", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_reports_df = bulk_reports_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "271d446a-702d-42bb-93a9-e576741a3fdd", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 7 entries, 0 to 6\n", + "Data columns (total 12 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 7 non-null object \n", + " 1 name 7 non-null object \n", + " 2 file_path 7 non-null object \n", + " 3 format 7 non-null object \n", + " 4 filters 7 non-null object \n", + " 5 geom 4 non-null object \n", + " 6 status 7 non-null object \n", + " 7 owner_id 7 non-null int64 \n", + " 8 owner_type 7 non-null object \n", + " 9 created_at 7 non-null datetime64[ns, UTC]\n", + " 10 updated_at 7 non-null datetime64[ns, UTC]\n", + " 11 file_size 7 non-null float64 \n", + "dtypes: datetime64[ns, UTC](2), float64(1), int64(1), object(8)\n", + "memory usage: 804.0+ bytes\n" + ] + } + ], + "source": [ + "bulk_reports_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "5145b645-c0fe-4780-b94f-261b534b7f04", + "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", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
idnamefile_pathformatfiltersgeomstatusowner_idowner_typecreated_atupdated_atfile_size
0705f2f9a-f695-43f1-a4bf-7746f3deb091public-fixed-infrastructure-data_public-eez-ar...sar_fixed_infrastructure_202409.csvJSON[label = 'oil', label_confidence = 'high']{'type': 'dataset', 'dataset': 'public-eez-are...done39application2026-01-10 22:47:37.506000+00:002026-01-10 22:47:37.506000+00:0022224.0
189e29012-bd90-4718-a6ba-71c0e3ea6260public-fixed-infrastructure-data_public-eez-ar...sar_fixed_infrastructure_202409.csvJSON[label = 'oil', label_confidence = 'high']{'type': 'dataset', 'dataset': 'public-eez-are...done39application2026-01-10 21:57:03.520000+00:002026-01-10 21:57:03.520000+00:0022224.0
29e8d0d20-a635-4d36-83f4-4179c3aad156sar-fixed-infrastructure-data-20241207-all-oil...sar_fixed_infrastructure_202409.csvJSON[label = 'oil', label_confidence = 'high']Nonedone39application2025-12-07 14:09:17.712000+00:002025-12-07 14:09:17.712000+00:0018223879.0
37a036b8f-21fc-4c53-a6cb-2d90caf1c2a5sar-fixed-infrastructure-data-20241207-all-lab...sar_fixed_infrastructure_202409.csvJSON[label_confidence = 'high' or label_confidence...Nonedone39application2025-12-07 12:21:33.424000+00:002025-12-07 12:21:33.424000+00:00122605450.0
4568d2d08-82f8-4243-a120-103c6417eef2sar-fixed-infrastructure-data-20241207-all-1sar_fixed_infrastructure_202409.csvJSON[label_confidence = 'high']Nonedone39application2025-12-07 10:12:40.192000+00:002025-12-07 10:12:40.192000+00:00117135274.0
\n", + "
" + ], + "text/plain": [ + " id \\\n", + "0 705f2f9a-f695-43f1-a4bf-7746f3deb091 \n", + "1 89e29012-bd90-4718-a6ba-71c0e3ea6260 \n", + "2 9e8d0d20-a635-4d36-83f4-4179c3aad156 \n", + "3 7a036b8f-21fc-4c53-a6cb-2d90caf1c2a5 \n", + "4 568d2d08-82f8-4243-a120-103c6417eef2 \n", + "\n", + " name \\\n", + "0 public-fixed-infrastructure-data_public-eez-ar... \n", + "1 public-fixed-infrastructure-data_public-eez-ar... \n", + "2 sar-fixed-infrastructure-data-20241207-all-oil... \n", + "3 sar-fixed-infrastructure-data-20241207-all-lab... \n", + "4 sar-fixed-infrastructure-data-20241207-all-1 \n", + "\n", + " file_path format \\\n", + "0 sar_fixed_infrastructure_202409.csv JSON \n", + "1 sar_fixed_infrastructure_202409.csv JSON \n", + "2 sar_fixed_infrastructure_202409.csv JSON \n", + "3 sar_fixed_infrastructure_202409.csv JSON \n", + "4 sar_fixed_infrastructure_202409.csv JSON \n", + "\n", + " filters \\\n", + "0 [label = 'oil', label_confidence = 'high'] \n", + "1 [label = 'oil', label_confidence = 'high'] \n", + "2 [label = 'oil', label_confidence = 'high'] \n", + "3 [label_confidence = 'high' or label_confidence... \n", + "4 [label_confidence = 'high'] \n", + "\n", + " geom status owner_id \\\n", + "0 {'type': 'dataset', 'dataset': 'public-eez-are... done 39 \n", + "1 {'type': 'dataset', 'dataset': 'public-eez-are... done 39 \n", + "2 None done 39 \n", + "3 None done 39 \n", + "4 None done 39 \n", + "\n", + " owner_type created_at \\\n", + "0 application 2026-01-10 22:47:37.506000+00:00 \n", + "1 application 2026-01-10 21:57:03.520000+00:00 \n", + "2 application 2025-12-07 14:09:17.712000+00:00 \n", + "3 application 2025-12-07 12:21:33.424000+00:00 \n", + "4 application 2025-12-07 10:12:40.192000+00:00 \n", + "\n", + " updated_at file_size \n", + "0 2026-01-10 22:47:37.506000+00:00 22224.0 \n", + "1 2026-01-10 21:57:03.520000+00:00 22224.0 \n", + "2 2025-12-07 14:09:17.712000+00:00 18223879.0 \n", + "3 2025-12-07 12:21:33.424000+00:00 122605450.0 \n", + "4 2025-12-07 10:12:40.192000+00:00 117135274.0 " + ] + }, + "execution_count": 25, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "bulk_reports_df.head()" + ] + }, + { + "cell_type": "markdown", + "id": "d00c4ba7-cc57-4503-8160-b42634c67777", + "metadata": {}, + "source": [ + "## Get Bulk Report File Download URL (`get_bulk_report_file_download_url`)" + ] + }, + { + "cell_type": "markdown", + "id": "65f7ae75-ae94-40d2-95b6-1b7eecc78356", + "metadata": {}, + "source": [ + "The `get_bulk_report_file_download_url()` method allows you retrieves **signed URL** that points to a **downloadable file** hosted on Global Fishing Watch's cloud infrastructure to **download file(s)** (i.e., `\"DATA\"`, `\"README\"`, or `\"GEOM\"`) of the previously created bulk report. The `id` parameter is mandatory. Please [learn more about get bulk report file download url here](https://globalfishingwatch.org/our-apis/documentation#download-bulk-report-url-file) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [here](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats)." + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "70c51654-a7b9-46a9-991b-c9c97dcfe41e", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_report_file_download_url_result = (\n", + " await gfw_client.bulk_downloads.get_bulk_report_file_download_url(\n", + " id=bulk_reports_data[0].id, file=\"DATA\"\n", + " )\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "74dbe00c-7503-473a-aac7-5f99984d41dc", + "metadata": {}, + "source": [ + "### Access Get Bulk Report File Download URL Result as Pydantic models" + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "5330ef22-3ef7-4482-ae34-f1e9f6f48ccf", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_report_file_download_url_data = bulk_report_file_download_url_result.data()" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "4e3d4575-4c59-4c8e-b15e-2206bdb995ec", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'https://storage.googleapis.com/gfw-api-bulk-pro-us-central1/705f2f9a-f695-43f1-a4bf-7746f3deb091/data.json.gz?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=api-bulk-pro%40gfw-production.iam.gserviceaccount.com%2F20260110%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20260110T225232Z&X-Goog-Expires=60&X-Goog-SignedHeaders=host&X-Goog-Signature=481a4ff7244b7286f303b37bb7941c291a26d1e3502debdb7611b8cb2d5edf37bc7aa0287b15a11c2f69f72e88791da3f76873a2fd7d08f911691c35ee8e095b825615510de8256f8cd275211997141e026837e118d86e01c026c457dc1f47d43ff2cb07131c3d21e7908c847bf1e3d87cd4773f02e8e4512a7c15e93799de186b9ea004be50cd3e53292f01e9393595a81c42cc3686f65d280f4f16076759da4722c17c2a6a698393c919cdd083402421a1bbf425b618244b3a9b30e48b770a9dc7f9eed8e63af04f8e31f0b6723fdf76fa7262ded89e7a375fbaea3b031bf29db22b1961878facd79c92d633ab6aa2309c0ce3982104d9835058ecd829bee8'" + ] + }, + "execution_count": 28, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "bulk_report_file_download_url_data.url" + ] + }, + { + "cell_type": "markdown", + "id": "a7115103-5942-429d-a247-2947f01e139f", + "metadata": {}, + "source": [ + "### Access Get Bulk Report File Download URL Result as a DataFrame" + ] + }, + { + "cell_type": "code", + "execution_count": 29, + "id": "7750da1f-e4cd-4fcd-9fe2-472e2d4e98b9", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_report_file_download_url_df = bulk_report_file_download_url_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 30, + "id": "ac6aada1-e0a2-4a31-9421-ce88c55aebb4", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 1 entries, 0 to 0\n", + "Data columns (total 1 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 url 1 non-null object\n", + "dtypes: object(1)\n", + "memory usage: 140.0+ bytes\n" + ] + } + ], + "source": [ + "bulk_report_file_download_url_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 31, + "id": "b6fe6c39-3e0a-43c2-8279-8fa1eebb18e6", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'https://storage.googleapis.com/gfw-api-bulk-pro-us-central1/705f2f9a-f695-43f1-a4bf-7746f3deb091/data.json.gz?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=api-bulk-pro%40gfw-production.iam.gserviceaccount.com%2F20260110%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20260110T225232Z&X-Goog-Expires=60&X-Goog-SignedHeaders=host&X-Goog-Signature=481a4ff7244b7286f303b37bb7941c291a26d1e3502debdb7611b8cb2d5edf37bc7aa0287b15a11c2f69f72e88791da3f76873a2fd7d08f911691c35ee8e095b825615510de8256f8cd275211997141e026837e118d86e01c026c457dc1f47d43ff2cb07131c3d21e7908c847bf1e3d87cd4773f02e8e4512a7c15e93799de186b9ea004be50cd3e53292f01e9393595a81c42cc3686f65d280f4f16076759da4722c17c2a6a698393c919cdd083402421a1bbf425b618244b3a9b30e48b770a9dc7f9eed8e63af04f8e31f0b6723fdf76fa7262ded89e7a375fbaea3b031bf29db22b1961878facd79c92d633ab6aa2309c0ce3982104d9835058ecd829bee8'" + ] + }, + "execution_count": 31, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "bulk_report_file_download_url_df.iloc[0][\"url\"]" + ] + }, + { + "cell_type": "markdown", + "id": "775f0875-6fef-45d7-ad1a-c589927a3f4b", + "metadata": {}, + "source": [ + "## Query Bulk Fixed Infrastructure Data Report (`query_bulk_fixed_infrastructure_data_report`)" + ] + }, + { + "cell_type": "markdown", + "id": "8f321b5e-3405-46fe-a92e-4d2bb698df36", + "metadata": {}, + "source": [ + "The `query_bulk_fixed_infrastructure_data_report()` method allows you retrieves **data records** of a previously created **fixed infrastructure data** (i.e., `public-fixed-infrastructure-data:latest` dataset) bulk report data in JSON format based on specified pagination, sorting, and including criteria. The `id` parameter is mandatory. Please [learn more about query bulk fixed infrastructure data report in JSON format here](https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [here](https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats)." + ] + }, + { + "cell_type": "code", + "execution_count": 32, + "id": "cd2f2b83-c2c6-4729-b229-1564ff9b4bbe", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_fixed_infrastructure_data_report_result = (\n", + " await gfw_client.bulk_downloads.query_bulk_fixed_infrastructure_data_report(\n", + " id=bulk_reports_data[0].id\n", + " )\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "79b3a72d-ec5b-4d6f-ace3-519ac1949592", + "metadata": {}, + "source": [ + "### Access Query Bulk Fixed Infrastructure Data Report Result as Pydantic models" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "id": "fc0e5713-8747-4afe-b7de-6cd5de4527af", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_fixed_infrastructure_data_report_data = (\n", + " bulk_fixed_infrastructure_data_report_result.data()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 34, + "id": "d45b9472-9051-4c15-9085-a4d904baef67", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_fixed_infrastructure_data_report_item = bulk_fixed_infrastructure_data_report_data[\n", + " -1\n", + "]" + ] + }, + { + "cell_type": "code", + "execution_count": 35, + "id": "032db92c-3a8d-4f73-a5cb-b567abe5de03", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "('1051638', -53.0895574340617, -67.32289149541135, 'oil', 'high')" + ] + }, + "execution_count": 35, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "(\n", + " bulk_fixed_infrastructure_data_report_item.structure_id,\n", + " bulk_fixed_infrastructure_data_report_item.lat,\n", + " bulk_fixed_infrastructure_data_report_item.lon,\n", + " bulk_fixed_infrastructure_data_report_item.label,\n", + " bulk_fixed_infrastructure_data_report_item.label_confidence,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "32b433f4-baed-4b0e-9989-9a02fbbc5fd9", + "metadata": {}, + "source": [ + "### Access Query Bulk Fixed Infrastructure Data Report Result as a DataFrame" + ] + }, + { + "cell_type": "code", + "execution_count": 36, + "id": "b38b2a5b-bfd7-4308-a8fa-1efb609d70c8", + "metadata": {}, + "outputs": [], + "source": [ + "bulk_fixed_infrastructure_data_report_result_df = (\n", + " bulk_fixed_infrastructure_data_report_result.df()\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "id": "a10e881e-928c-41aa-b47e-c33e9fdfb95d", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 1238 entries, 0 to 1237\n", + "Data columns (total 9 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 detection_id 1237 non-null object \n", + " 1 detection_date 1238 non-null datetime64[ns]\n", + " 2 structure_id 1238 non-null object \n", + " 3 lat 1238 non-null float64 \n", + " 4 lon 1238 non-null float64 \n", + " 5 structure_start_date 1238 non-null datetime64[ns]\n", + " 6 structure_end_date 7 non-null datetime64[ns]\n", + " 7 label 1238 non-null object \n", + " 8 label_confidence 1238 non-null object \n", + "dtypes: datetime64[ns](3), float64(2), object(4)\n", + "memory usage: 87.2+ KB\n" + ] + } + ], + "source": [ + "bulk_fixed_infrastructure_data_report_result_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 38, + "id": "2c0bb2d5-c119-4a74-800b-aef1efbc5df4", + "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", + "
detection_iddetection_datestructure_idlatlonstructure_start_datestructure_end_datelabellabel_confidence
0S1AB_AD_MEDIAN_COMP_20170902T000000_20180301T0...2017-12-01313068-52.612197-68.4492922017-01-01NaToilhigh
1S1AB_AD_MEDIAN_COMP_20231101T000000_20240501T0...2024-02-01313068-52.612197-68.4492922017-01-01NaToilhigh
2S1AB_AD_MEDIAN_COMP_20230501T000000_20231101T0...2023-08-01313068-52.612197-68.4492922017-01-01NaToilhigh
3S1AB_AD_MEDIAN_COMP_20220901T000000_20230301T0...2022-12-01313068-52.612197-68.4492922017-01-01NaToilhigh
4S1AB_AD_MEDIAN_COMP_20220701T000000_20230101T0...2022-10-01313068-52.612197-68.4492922017-01-01NaToilhigh
\n", + "
" + ], + "text/plain": [ + " detection_id detection_date \\\n", + "0 S1AB_AD_MEDIAN_COMP_20170902T000000_20180301T0... 2017-12-01 \n", + "1 S1AB_AD_MEDIAN_COMP_20231101T000000_20240501T0... 2024-02-01 \n", + "2 S1AB_AD_MEDIAN_COMP_20230501T000000_20231101T0... 2023-08-01 \n", + "3 S1AB_AD_MEDIAN_COMP_20220901T000000_20230301T0... 2022-12-01 \n", + "4 S1AB_AD_MEDIAN_COMP_20220701T000000_20230101T0... 2022-10-01 \n", + "\n", + " structure_id lat lon structure_start_date structure_end_date \\\n", + "0 313068 -52.612197 -68.449292 2017-01-01 NaT \n", + "1 313068 -52.612197 -68.449292 2017-01-01 NaT \n", + "2 313068 -52.612197 -68.449292 2017-01-01 NaT \n", + "3 313068 -52.612197 -68.449292 2017-01-01 NaT \n", + "4 313068 -52.612197 -68.449292 2017-01-01 NaT \n", + "\n", + " label label_confidence \n", + "0 oil high \n", + "1 oil high \n", + "2 oil high \n", + "3 oil high \n", + "4 oil high " + ] + }, + "execution_count": 38, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "bulk_fixed_infrastructure_data_report_result_df.head()" + ] + } + ], + "metadata": { + "colab": { + "include_colab_link": true, + "provenance": [] + }, + "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/datasets-api.ipynb b/notebooks/usage-guides/datasets-api.ipynb index 41f53ea..03fd43f 100644 --- a/notebooks/usage-guides/datasets-api.ipynb +++ b/notebooks/usage-guides/datasets-api.ipynb @@ -28,7 +28,7 @@ "id": "41006fe2-f552-4dfc-b6d0-4b6b46aadf27" }, "source": [ - "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access various datasets available through the Global Fishing Watch API. Currently, it focuses on retrieving SAR (Synthetic Aperture Radar) fixed infrastructure data." + "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access various datasets available through the Global Fishing Watch [Datasets API](https://globalfishingwatch.org/our-apis/documentation#datasets-api). Currently, it focuses on retrieving SAR (Synthetic Aperture Radar) fixed infrastructure data." ] }, { @@ -101,6 +101,14 @@ "## Usage" ] }, + { + "cell_type": "markdown", + "id": "e0ca8a5b-2028-48e0-8cb4-0c3f9601dcf6", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, { "cell_type": "code", "execution_count": 2, @@ -111,6 +119,7 @@ "outputs": [], "source": [ "import os\n", + "\n", "import gfwapiclient as gfw" ] }, @@ -127,7 +136,7 @@ " from google.colab import userdata\n", "\n", " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", - "except Exception as exc:\n", + "except Exception:\n", " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", "\n", "access_token = access_token or \"\"" @@ -234,7 +243,7 @@ { "data": { "text/plain": [ - "(646348, 'oil', -39.15082587013905, 177.96658840984458)" + "(1065796, 'oil', -71.81842050325909, -12.6523216191814)" ] }, "execution_count": 9, @@ -276,6 +285,37 @@ { "cell_type": "code", "execution_count": 11, + "id": "de8e24ee-4c15-4c38-846b-fce96ec7c41a", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 1156 entries, 0 to 1155\n", + "Data columns (total 7 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 structure_id 1156 non-null int64 \n", + " 1 lat 1156 non-null float64 \n", + " 2 lon 1156 non-null float64 \n", + " 3 label 1156 non-null object \n", + " 4 structure_start_date 1156 non-null datetime64[ns, UTC]\n", + " 5 structure_end_date 857 non-null datetime64[ns, UTC]\n", + " 6 label_confidence 1156 non-null object \n", + "dtypes: datetime64[ns, UTC](2), float64(2), int64(1), object(2)\n", + "memory usage: 63.3+ KB\n" + ] + } + ], + "source": [ + "sar_infrastructure_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 12, "id": "5350bf55-3a37-4fa9-a1d9-0642e9ece7ef", "metadata": { "colab": { @@ -319,52 +359,52 @@ " \n", " \n", " 0\n", - " 170796\n", - " 1.509645\n", - " -78.888106\n", - " unknown\n", - " 2021-11-01 00:00:00+00:00\n", - " 2021-12-01 00:00:00+00:00\n", - " high\n", - " \n", - " \n", - " 1\n", - " 254126\n", - " 1.029763\n", - " -79.745796\n", + " 128911\n", + " -14.374089\n", + " -170.707656\n", " oil\n", " 2017-01-01 00:00:00+00:00\n", " NaT\n", + " low\n", + " \n", + " \n", + " 1\n", + " 901458\n", + " -17.949867\n", + " -150.537969\n", + " unknown\n", + " 2020-01-01 00:00:00+00:00\n", + " 2020-01-01 00:00:00+00:00\n", " high\n", " \n", " \n", " 2\n", - " 360586\n", - " 1.021449\n", - " -79.733240\n", - " oil\n", - " 2017-01-01 00:00:00+00:00\n", - " NaT\n", + " 1073932\n", + " -16.838022\n", + " -148.715736\n", + " unknown\n", + " 2025-04-01 00:00:00+00:00\n", + " 2025-04-01 00:00:00+00:00\n", " high\n", " \n", " \n", " 3\n", - " 237733\n", - " 1.030971\n", - " -79.717878\n", - " oil\n", - " 2017-01-01 00:00:00+00:00\n", - " NaT\n", + " 1073227\n", + " -16.883566\n", + " -148.518017\n", + " unknown\n", + " 2025-04-01 00:00:00+00:00\n", + " 2025-04-01 00:00:00+00:00\n", " high\n", " \n", " \n", " 4\n", - " 450717\n", - " 1.033458\n", - " -79.699540\n", - " oil\n", - " 2017-01-01 00:00:00+00:00\n", - " NaT\n", + " 1073521\n", + " -16.900634\n", + " -148.443097\n", + " unknown\n", + " 2025-04-01 00:00:00+00:00\n", + " 2025-04-01 00:00:00+00:00\n", " high\n", " \n", " \n", @@ -372,22 +412,22 @@ "" ], "text/plain": [ - " structure_id lat lon label structure_start_date \\\n", - "0 170796 1.509645 -78.888106 unknown 2021-11-01 00:00:00+00:00 \n", - "1 254126 1.029763 -79.745796 oil 2017-01-01 00:00:00+00:00 \n", - "2 360586 1.021449 -79.733240 oil 2017-01-01 00:00:00+00:00 \n", - "3 237733 1.030971 -79.717878 oil 2017-01-01 00:00:00+00:00 \n", - "4 450717 1.033458 -79.699540 oil 2017-01-01 00:00:00+00:00 \n", + " structure_id lat lon label structure_start_date \\\n", + "0 128911 -14.374089 -170.707656 oil 2017-01-01 00:00:00+00:00 \n", + "1 901458 -17.949867 -150.537969 unknown 2020-01-01 00:00:00+00:00 \n", + "2 1073932 -16.838022 -148.715736 unknown 2025-04-01 00:00:00+00:00 \n", + "3 1073227 -16.883566 -148.518017 unknown 2025-04-01 00:00:00+00:00 \n", + "4 1073521 -16.900634 -148.443097 unknown 2025-04-01 00:00:00+00:00 \n", "\n", " structure_end_date label_confidence \n", - "0 2021-12-01 00:00:00+00:00 high \n", - "1 NaT high \n", - "2 NaT high \n", - "3 NaT high \n", - "4 NaT high " + "0 NaT low \n", + "1 2020-01-01 00:00:00+00:00 high \n", + "2 2025-04-01 00:00:00+00:00 high \n", + "3 2025-04-01 00:00:00+00:00 high \n", + "4 2025-04-01 00:00:00+00:00 high " ] }, - "execution_count": 11, + "execution_count": 12, "metadata": {}, "output_type": "execute_result" } @@ -408,7 +448,7 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 13, "id": "7b12622e-db12-4adb-9721-717070e026f8", "metadata": { "id": "7b12622e-db12-4adb-9721-717070e026f8" @@ -431,7 +471,7 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 14, "id": "02c19ae9-fb43-4f95-a9c2-e0e5b97a7089", "metadata": { "id": "02c19ae9-fb43-4f95-a9c2-e0e5b97a7089" @@ -445,7 +485,7 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 15, "id": "4ca75748-9258-4352-8286-ff3f2dacf2b0", "metadata": { "id": "4ca75748-9258-4352-8286-ff3f2dacf2b0" @@ -457,7 +497,7 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": 16, "id": "276c553b-df26-43cc-a1f3-6319417552e9", "metadata": { "id": "276c553b-df26-43cc-a1f3-6319417552e9" @@ -469,7 +509,7 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": 17, "id": "30f82972-50dc-4c60-a901-21c2acc17255", "metadata": { "colab": { @@ -482,10 +522,10 @@ { "data": { "text/plain": [ - "(646348, 'oil', -39.15082587013905, 177.96658840984458)" + "(1065796, 'oil', -71.81842050325909, -12.6523216191814)" ] }, - "execution_count": 16, + "execution_count": 17, "metadata": {}, "output_type": "execute_result" } @@ -511,7 +551,7 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 18, "id": "d29b4044-5ba2-44bf-a00f-f1b01cb35ab6", "metadata": { "id": "d29b4044-5ba2-44bf-a00f-f1b01cb35ab6" @@ -523,7 +563,38 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 19, + "id": "d7b179d5-4f23-49ce-b703-94f497230057", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 1156 entries, 0 to 1155\n", + "Data columns (total 7 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 structure_id 1156 non-null int64 \n", + " 1 lat 1156 non-null float64 \n", + " 2 lon 1156 non-null float64 \n", + " 3 label 1156 non-null object \n", + " 4 structure_start_date 1156 non-null datetime64[ns, UTC]\n", + " 5 structure_end_date 857 non-null datetime64[ns, UTC]\n", + " 6 label_confidence 1156 non-null object \n", + "dtypes: datetime64[ns, UTC](2), float64(2), int64(1), object(2)\n", + "memory usage: 63.3+ KB\n" + ] + } + ], + "source": [ + "sar_infrastructure_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 20, "id": "7ca536d1-dfa2-4ba7-b20a-72e739c66775", "metadata": { "colab": { @@ -567,52 +638,52 @@ " \n", " \n", " 0\n", - " 170796\n", - " 1.509645\n", - " -78.888106\n", - " unknown\n", - " 2021-11-01 00:00:00+00:00\n", - " 2021-12-01 00:00:00+00:00\n", - " high\n", - " \n", - " \n", - " 1\n", - " 254126\n", - " 1.029763\n", - " -79.745796\n", + " 128911\n", + " -14.374089\n", + " -170.707656\n", " oil\n", " 2017-01-01 00:00:00+00:00\n", " NaT\n", + " low\n", + " \n", + " \n", + " 1\n", + " 901458\n", + " -17.949867\n", + " -150.537969\n", + " unknown\n", + " 2020-01-01 00:00:00+00:00\n", + " 2020-01-01 00:00:00+00:00\n", " high\n", " \n", " \n", " 2\n", - " 360586\n", - " 1.021449\n", - " -79.733240\n", - " oil\n", - " 2017-01-01 00:00:00+00:00\n", - " NaT\n", + " 1073932\n", + " -16.838022\n", + " -148.715736\n", + " unknown\n", + " 2025-04-01 00:00:00+00:00\n", + " 2025-04-01 00:00:00+00:00\n", " high\n", " \n", " \n", " 3\n", - " 237733\n", - " 1.030971\n", - " -79.717878\n", - " oil\n", - " 2017-01-01 00:00:00+00:00\n", - " NaT\n", + " 1073227\n", + " -16.883566\n", + " -148.518017\n", + " unknown\n", + " 2025-04-01 00:00:00+00:00\n", + " 2025-04-01 00:00:00+00:00\n", " high\n", " \n", " \n", " 4\n", - " 450717\n", - " 1.033458\n", - " -79.699540\n", - " oil\n", - " 2017-01-01 00:00:00+00:00\n", - " NaT\n", + " 1073521\n", + " -16.900634\n", + " -148.443097\n", + " unknown\n", + " 2025-04-01 00:00:00+00:00\n", + " 2025-04-01 00:00:00+00:00\n", " high\n", " \n", " \n", @@ -620,22 +691,22 @@ "" ], "text/plain": [ - " structure_id lat lon label structure_start_date \\\n", - "0 170796 1.509645 -78.888106 unknown 2021-11-01 00:00:00+00:00 \n", - "1 254126 1.029763 -79.745796 oil 2017-01-01 00:00:00+00:00 \n", - "2 360586 1.021449 -79.733240 oil 2017-01-01 00:00:00+00:00 \n", - "3 237733 1.030971 -79.717878 oil 2017-01-01 00:00:00+00:00 \n", - "4 450717 1.033458 -79.699540 oil 2017-01-01 00:00:00+00:00 \n", + " structure_id lat lon label structure_start_date \\\n", + "0 128911 -14.374089 -170.707656 oil 2017-01-01 00:00:00+00:00 \n", + "1 901458 -17.949867 -150.537969 unknown 2020-01-01 00:00:00+00:00 \n", + "2 1073932 -16.838022 -148.715736 unknown 2025-04-01 00:00:00+00:00 \n", + "3 1073227 -16.883566 -148.518017 unknown 2025-04-01 00:00:00+00:00 \n", + "4 1073521 -16.900634 -148.443097 unknown 2025-04-01 00:00:00+00:00 \n", "\n", " structure_end_date label_confidence \n", - "0 2021-12-01 00:00:00+00:00 high \n", - "1 NaT high \n", - "2 NaT high \n", - "3 NaT high \n", - "4 NaT high " + "0 NaT low \n", + "1 2020-01-01 00:00:00+00:00 high \n", + "2 2025-04-01 00:00:00+00:00 high \n", + "3 2025-04-01 00:00:00+00:00 high \n", + "4 2025-04-01 00:00:00+00:00 high " ] }, - "execution_count": 18, + "execution_count": 20, "metadata": {}, "output_type": "execute_result" } diff --git a/notebooks/usage-guides/events-api.ipynb b/notebooks/usage-guides/events-api.ipynb index 0893d10..bed1978 100644 --- a/notebooks/usage-guides/events-api.ipynb +++ b/notebooks/usage-guides/events-api.ipynb @@ -28,7 +28,7 @@ "id": "e9ca2eda-18f1-4f9c-9717-fb1a06423958" }, "source": [ - "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access information about various activities of a vessel, including fishing activity, encounters, port visits, loitering, and gaps in AIS reporting." + "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access information about various activities of a vessel, including fishing activity, encounters, port visits, loitering, and gaps in AIS reporting through the Global Fishing Watch [Events API](https://globalfishingwatch.org/our-apis/documentation#events-api)." ] }, { @@ -101,6 +101,14 @@ "## Usage" ] }, + { + "cell_type": "markdown", + "id": "6d37044e-0797-4e84-991a-c13ab9997f59", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, { "cell_type": "code", "execution_count": 2, @@ -111,6 +119,7 @@ "outputs": [], "source": [ "import os\n", + "\n", "import gfwapiclient as gfw" ] }, @@ -127,7 +136,7 @@ " from google.colab import userdata\n", "\n", " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", - "except Exception as exc:\n", + "except Exception:\n", " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", "\n", "access_token = access_token or \"\"" @@ -266,6 +275,44 @@ { "cell_type": "code", "execution_count": 10, + "id": "dafd51a8-8370-471e-9a2b-f523351a5b46", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 5 entries, 0 to 4\n", + "Data columns (total 14 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 start 5 non-null datetime64[ns, UTC]\n", + " 1 end 5 non-null datetime64[ns, UTC]\n", + " 2 id 5 non-null object \n", + " 3 type 5 non-null object \n", + " 4 position 5 non-null object \n", + " 5 regions 5 non-null object \n", + " 6 bounding_box 5 non-null object \n", + " 7 distances 5 non-null object \n", + " 8 vessel 5 non-null object \n", + " 9 encounter 0 non-null object \n", + " 10 fishing 5 non-null object \n", + " 11 gap 0 non-null object \n", + " 12 loitering 0 non-null object \n", + " 13 port_visit 0 non-null object \n", + "dtypes: datetime64[ns, UTC](2), object(12)\n", + "memory usage: 692.0+ bytes\n" + ] + } + ], + "source": [ + "events_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 11, "id": "33328ed3-e2c0-456c-89d2-e13df6cb6911", "metadata": { "colab": { @@ -326,7 +373,7 @@ " {'start_distance_from_shore_km': 2.0, 'end_dis...\n", " {'id': '9e01144bf-f383-e634-3178-ca7e34477f34'...\n", " None\n", - " {'total_distance_km': 3.4650098660546638, 'ave...\n", + " {'total_distance_km': 3.4650098660546633, 'ave...\n", " None\n", " None\n", " None\n", @@ -389,12 +436,12 @@ " bbbf5d0cfa9639e5eac0130fc2b742e9\n", " fishing\n", " {'lat': 14.9647, 'lon': -17.6039}\n", - " {'mpa': [], 'eez': ['8371'], 'rfmo': ['IWC', '...\n", + " {'mpa': [], 'eez': ['8371'], 'rfmo': ['ACAP', ...\n", " [-17.480231666700007, 14.8685916667, -17.67519...\n", " {'start_distance_from_shore_km': 11.0, 'end_di...\n", " {'id': '7374d1988-87f8-6037-66b4-59854a026efb'...\n", " None\n", - " {'total_distance_km': 93.25349267584731, 'aver...\n", + " {'total_distance_km': 93.2534926758473, 'avera...\n", " None\n", " None\n", " None\n", @@ -430,7 +477,7 @@ "1 {'mpa': ['555651502'], 'eez': ['8371'], 'rfmo'... \n", "2 {'mpa': ['555705172'], 'eez': ['8371'], 'rfmo'... \n", "3 {'mpa': [], 'eez': ['8371'], 'rfmo': ['SRFC', ... \n", - "4 {'mpa': [], 'eez': ['8371'], 'rfmo': ['IWC', '... \n", + "4 {'mpa': [], 'eez': ['8371'], 'rfmo': ['ACAP', ... \n", "\n", " bounding_box \\\n", "0 [-17.4119, 14.686378333333334, -17.41116833333... \n", @@ -454,11 +501,11 @@ "4 {'id': '7374d1988-87f8-6037-66b4-59854a026efb'... None \n", "\n", " fishing gap loitering \\\n", - "0 {'total_distance_km': 3.4650098660546638, 'ave... None None \n", + "0 {'total_distance_km': 3.4650098660546633, 'ave... None None \n", "1 {'total_distance_km': 294.3073276985627, 'aver... None None \n", "2 {'total_distance_km': 130.6216027333083, 'aver... None None \n", "3 {'total_distance_km': 111.11378725724042, 'ave... None None \n", - "4 {'total_distance_km': 93.25349267584731, 'aver... None None \n", + "4 {'total_distance_km': 93.2534926758473, 'avera... None None \n", "\n", " port_visit \n", "0 None \n", @@ -468,7 +515,7 @@ "4 None " ] }, - "execution_count": 10, + "execution_count": 11, "metadata": {}, "output_type": "execute_result" } @@ -489,7 +536,7 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 12, "id": "7153066a-abe9-4b1a-9751-378f5486ed61", "metadata": { "id": "7153066a-abe9-4b1a-9751-378f5486ed61" @@ -514,7 +561,7 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 13, "id": "07f3cec3-752b-494e-be95-f96ff7cda93a", "metadata": { "id": "07f3cec3-752b-494e-be95-f96ff7cda93a" @@ -526,7 +573,7 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 14, "id": "1598ba96-1e0e-40ce-ade8-c2ccd721cad7", "metadata": { "colab": { @@ -544,7 +591,7 @@ " '8c7304226-6c71-edbe-0b63-c246734b3c01')" ] }, - "execution_count": 13, + "execution_count": 14, "metadata": {}, "output_type": "execute_result" } @@ -565,7 +612,7 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 15, "id": "5924b8c6-da8e-42a9-94ee-9b67ebdb1e7e", "metadata": { "id": "5924b8c6-da8e-42a9-94ee-9b67ebdb1e7e" @@ -577,7 +624,45 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": 16, + "id": "1754d20c-5a9c-42f1-8e02-d10fe24a43c3", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 1 entries, 0 to 0\n", + "Data columns (total 14 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 start 1 non-null datetime64[ns, UTC]\n", + " 1 end 1 non-null datetime64[ns, UTC]\n", + " 2 id 1 non-null object \n", + " 3 type 1 non-null object \n", + " 4 position 1 non-null object \n", + " 5 regions 1 non-null object \n", + " 6 bounding_box 1 non-null object \n", + " 7 distances 1 non-null object \n", + " 8 vessel 1 non-null object \n", + " 9 encounter 0 non-null object \n", + " 10 fishing 0 non-null object \n", + " 11 gap 0 non-null object \n", + " 12 loitering 0 non-null object \n", + " 13 port_visit 1 non-null object \n", + "dtypes: datetime64[ns, UTC](2), object(12)\n", + "memory usage: 244.0+ bytes\n" + ] + } + ], + "source": [ + "event_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 17, "id": "9e6befd3-f970-4a05-b2d0-63ddd4adcfe0", "metadata": { "colab": { @@ -633,7 +718,7 @@ " c2f0967e061f99a01793edac065de003\n", " port_visit\n", " {'lat': 20.7288, 'lon': -17.0148}\n", - " {'mpa': [], 'eez': ['8369'], 'rfmo': ['ICCAT',...\n", + " {'mpa': [], 'eez': ['8369'], 'rfmo': ['NAMMCO'...\n", " [-17.014774393446658, 20.72879719687954, -17.0...\n", " {'start_distance_from_shore_km': 7.0, 'end_dis...\n", " {'id': '8c7304226-6c71-edbe-0b63-c246734b3c01'...\n", @@ -658,7 +743,7 @@ "0 {'lat': 20.7288, 'lon': -17.0148} \n", "\n", " regions \\\n", - "0 {'mpa': [], 'eez': ['8369'], 'rfmo': ['ICCAT',... \n", + "0 {'mpa': [], 'eez': ['8369'], 'rfmo': ['NAMMCO'... \n", "\n", " bounding_box \\\n", "0 [-17.014774393446658, 20.72879719687954, -17.0... \n", @@ -673,7 +758,7 @@ "0 None {'visit_id': '38affb3e7bdc67e9c0c2e7e8f3b08da2... " ] }, - "execution_count": 15, + "execution_count": 17, "metadata": {}, "output_type": "execute_result" } @@ -694,7 +779,7 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": 18, "id": "aacbe1ad-9806-4f83-8d4c-e37d318e1a08", "metadata": { "id": "aacbe1ad-9806-4f83-8d4c-e37d318e1a08" @@ -725,7 +810,7 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 19, "id": "20bbb945-6c45-4ae9-98c6-029a833f0aeb", "metadata": { "id": "20bbb945-6c45-4ae9-98c6-029a833f0aeb" @@ -737,7 +822,7 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 20, "id": "24742d8a-d55f-4f1d-8d97-556fb2ec6572", "metadata": { "colab": { @@ -750,10 +835,10 @@ { "data": { "text/plain": [ - "(24750, 1, 197)" + "(24770, 1, 196)" ] }, - "execution_count": 18, + "execution_count": 20, "metadata": {}, "output_type": "execute_result" } @@ -774,7 +859,7 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": 21, "id": "bcdf7d04-695c-4bd6-8cbe-6e522339ad58", "metadata": { "id": "bcdf7d04-695c-4bd6-8cbe-6e522339ad58" @@ -786,7 +871,36 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": 22, + "id": "d97c2f90-6414-44f4-b82c-9a92731a18db", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 1 entries, 0 to 0\n", + "Data columns (total 5 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 num_events 1 non-null int64 \n", + " 1 num_flags 1 non-null int64 \n", + " 2 num_vessels 1 non-null int64 \n", + " 3 flags 1 non-null object\n", + " 4 timeseries 1 non-null object\n", + "dtypes: int64(3), object(2)\n", + "memory usage: 172.0+ bytes\n" + ] + } + ], + "source": [ + "event_stat_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 23, "id": "0496f743-190f-497c-9433-a4981446c786", "metadata": { "colab": { @@ -828,9 +942,9 @@ " \n", " \n", " 0\n", - " 24750\n", + " 24770\n", " 1\n", - " 197\n", + " 196\n", " [RUS]\n", " [{'date': 2018-01-01 00:00:00+00:00, 'value': ...\n", " \n", @@ -840,13 +954,13 @@ ], "text/plain": [ " num_events num_flags num_vessels flags \\\n", - "0 24750 1 197 [RUS] \n", + "0 24770 1 196 [RUS] \n", "\n", " timeseries \n", "0 [{'date': 2018-01-01 00:00:00+00:00, 'value': ... " ] }, - "execution_count": 20, + "execution_count": 23, "metadata": {}, "output_type": "execute_result" } diff --git a/notebooks/usage-guides/insights-api.ipynb b/notebooks/usage-guides/insights-api.ipynb index 790a793..5b7c2ad 100644 --- a/notebooks/usage-guides/insights-api.ipynb +++ b/notebooks/usage-guides/insights-api.ipynb @@ -28,7 +28,7 @@ "id": "e9ca2eda-18f1-4f9c-9717-fb1a06423958" }, "source": [ - "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access aggregated insights about vessel activities." + "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access aggregated insights about vessel activities through the Global Fishing Watch [Insights API](https://globalfishingwatch.org/our-apis/documentation#insights-api)." ] }, { @@ -101,6 +101,14 @@ "## Usage" ] }, + { + "cell_type": "markdown", + "id": "6fa3c864-ab80-4dd9-844f-68f167aaeaf2", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, { "cell_type": "code", "execution_count": 2, @@ -111,6 +119,7 @@ "outputs": [], "source": [ "import os\n", + "\n", "import gfwapiclient as gfw" ] }, @@ -127,7 +136,7 @@ " from google.colab import userdata\n", "\n", " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", - "except Exception as exc:\n", + "except Exception:\n", " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", "\n", "access_token = access_token or \"\"" @@ -265,6 +274,36 @@ { "cell_type": "code", "execution_count": 9, + "id": "df544af4-bcbf-424a-921b-a8d9b815ea6e", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 1 entries, 0 to 0\n", + "Data columns (total 6 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 period 1 non-null object\n", + " 1 vessel_ids_without_identity 0 non-null object\n", + " 2 gap 0 non-null object\n", + " 3 coverage 0 non-null object\n", + " 4 apparent_fishing 1 non-null object\n", + " 5 vessel_identity 0 non-null object\n", + "dtypes: object(6)\n", + "memory usage: 180.0+ bytes\n" + ] + } + ], + "source": [ + "insights_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 10, "id": "5dce404d-4318-44da-8811-c4bbc5fefb77", "metadata": { "colab": { @@ -329,7 +368,7 @@ "0 {'datasets': ['public-global-fishing-events:v3... None " ] }, - "execution_count": 9, + "execution_count": 10, "metadata": {}, "output_type": "execute_result" } diff --git a/notebooks/usage-guides/references-data-api.ipynb b/notebooks/usage-guides/references-data-api.ipynb index 49fa4c2..1f2d52c 100644 --- a/notebooks/usage-guides/references-data-api.ipynb +++ b/notebooks/usage-guides/references-data-api.ipynb @@ -28,7 +28,7 @@ "id": "5d8e4401-2090-47a0-b3e1-be4d3ba5cc00" }, "source": [ - "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access reference data, specifically geographic regions." + "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access reference data, specifically geographic regions through the Global Fishing Watch [Reference Data API](https://globalfishingwatch.org/our-apis/documentation#regions)." ] }, { @@ -101,6 +101,14 @@ "## Usage" ] }, + { + "cell_type": "markdown", + "id": "b201b300-884d-4ef7-895e-45c025a12962", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, { "cell_type": "code", "execution_count": 2, @@ -111,6 +119,7 @@ "outputs": [], "source": [ "import os\n", + "\n", "import gfwapiclient as gfw" ] }, @@ -127,7 +136,7 @@ " from google.colab import userdata\n", "\n", " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", - "except Exception as exc:\n", + "except Exception:\n", " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", "\n", "access_token = access_token or \"\"" @@ -255,6 +264,38 @@ { "cell_type": "code", "execution_count": 10, + "id": "547bf861-ab6f-4362-99c5-ee70041fb6e0", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 285 entries, 0 to 284\n", + "Data columns (total 8 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 285 non-null int64 \n", + " 1 label 285 non-null object\n", + " 2 iso3 234 non-null object\n", + " 3 dataset 285 non-null object\n", + " 4 isoSov1 285 non-null object\n", + " 5 isoSov2 56 non-null object\n", + " 6 isoSov3 6 non-null object\n", + " 7 territory1 285 non-null object\n", + "dtypes: int64(1), object(7)\n", + "memory usage: 17.9+ KB\n" + ] + } + ], + "source": [ + "eez_regions_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 11, "id": "3d2963b3-6ea1-489c-abdb-aad327ed4875", "metadata": { "colab": { @@ -297,21 +338,21 @@ " 0\n", " 8491\n", " Jordanian Exclusive Economic Zone\n", - " None\n", + " JOR\n", " public-eez-areas\n", " \n", " \n", " 1\n", " 8467\n", " Uruguayan Exclusive Economic Zone\n", - " None\n", + " URY\n", " public-eez-areas\n", " \n", " \n", " 2\n", " 5683\n", " Latvian Exclusive Economic Zone\n", - " None\n", + " LVA\n", " public-eez-areas\n", " \n", " \n", @@ -325,7 +366,7 @@ " 4\n", " 8327\n", " South Korean Exclusive Economic Zone\n", - " None\n", + " KOR\n", " public-eez-areas\n", " \n", " \n", @@ -334,11 +375,11 @@ ], "text/plain": [ " id label iso3 \\\n", - "0 8491 Jordanian Exclusive Economic Zone None \n", - "1 8467 Uruguayan Exclusive Economic Zone None \n", - "2 5683 Latvian Exclusive Economic Zone None \n", + "0 8491 Jordanian Exclusive Economic Zone JOR \n", + "1 8467 Uruguayan Exclusive Economic Zone URY \n", + "2 5683 Latvian Exclusive Economic Zone LVA \n", "3 48950 Overlapping claim Kuril Islands: Japan / Russia None \n", - "4 8327 South Korean Exclusive Economic Zone None \n", + "4 8327 South Korean Exclusive Economic Zone KOR \n", "\n", " dataset \n", "0 public-eez-areas \n", @@ -348,7 +389,7 @@ "4 public-eez-areas " ] }, - "execution_count": 10, + "execution_count": 11, "metadata": {}, "output_type": "execute_result" } @@ -369,7 +410,7 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 12, "id": "71915ac9-7cb4-4a11-aee6-0df2ee6f9cd5", "metadata": { "id": "71915ac9-7cb4-4a11-aee6-0df2ee6f9cd5" @@ -391,7 +432,7 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 13, "id": "eee11224-fde4-4273-bfa7-da0b2c4bb9a2", "metadata": { "id": "eee11224-fde4-4273-bfa7-da0b2c4bb9a2" @@ -403,7 +444,7 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 14, "id": "845f42d9-1abe-404c-ae2c-8fc07579a612", "metadata": { "id": "845f42d9-1abe-404c-ae2c-8fc07579a612" @@ -415,7 +456,7 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 15, "id": "c8254eff-97da-4b10-b48d-bb8eea5845d8", "metadata": { "colab": { @@ -428,10 +469,10 @@ { "data": { "text/plain": [ - "('555790807', 'public-mpa-all')" + "('555799979', 'public-mpa-all')" ] }, - "execution_count": 14, + "execution_count": 15, "metadata": {}, "output_type": "execute_result" } @@ -452,7 +493,7 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": 16, "id": "cb8f7439-5cf8-4ab9-88e1-2a84795adbb2", "metadata": { "id": "cb8f7439-5cf8-4ab9-88e1-2a84795adbb2" @@ -464,7 +505,35 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": 17, + "id": "0e111e02-aed8-49fc-bbf4-5fd293bf58d1", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 16591 entries, 0 to 16590\n", + "Data columns (total 4 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 16591 non-null object\n", + " 1 label 16591 non-null object\n", + " 2 name 0 non-null object\n", + " 3 dataset 16591 non-null object\n", + "dtypes: object(4)\n", + "memory usage: 518.6+ KB\n" + ] + } + ], + "source": [ + "mpa_regions_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 18, "id": "0dc3268f-e099-4fe2-821b-f17d579f9d68", "metadata": { "colab": { @@ -506,7 +575,7 @@ " \n", " 0\n", " 1\n", - " Diamond Reef and Salt Fish Tail Reef - Marine ...\n", + " Diamond Reef - Marine Reserve\n", " None\n", " public-mpa-all\n", " \n", @@ -544,14 +613,14 @@ ], "text/plain": [ " id label name dataset\n", - "0 1 Diamond Reef and Salt Fish Tail Reef - Marine ... None public-mpa-all\n", + "0 1 Diamond Reef - Marine Reserve None public-mpa-all\n", "1 2 Palaster Reef - Marine Reserve None public-mpa-all\n", "2 27 Folkstone - Marine Reserve None public-mpa-all\n", "3 46 Reserva Biológica Atol Das Rocas - Reserva Bio... None public-mpa-all\n", "4 57 Parque Nacional Do Cabo Orange - Parque None public-mpa-all" ] }, - "execution_count": 16, + "execution_count": 18, "metadata": {}, "output_type": "execute_result" } @@ -572,7 +641,7 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 19, "id": "ac6c6784-e839-44ed-8b47-50c9d7f0a68a", "metadata": { "id": "ac6c6784-e839-44ed-8b47-50c9d7f0a68a" @@ -594,7 +663,7 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 20, "id": "377f6c90-275f-4dbb-81d2-d1dd43e65fdd", "metadata": { "id": "377f6c90-275f-4dbb-81d2-d1dd43e65fdd" @@ -606,7 +675,7 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": 21, "id": "69605d0f-c97f-4e49-a4f5-d55121e9533a", "metadata": { "id": "69605d0f-c97f-4e49-a4f5-d55121e9533a" @@ -618,7 +687,7 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": 22, "id": "281fe6ca-f993-4158-a225-930173c52550", "metadata": { "colab": { @@ -634,7 +703,7 @@ "('BOBP-IGO', 'public-rfmo')" ] }, - "execution_count": 20, + "execution_count": 22, "metadata": {}, "output_type": "execute_result" } @@ -655,7 +724,7 @@ }, { "cell_type": "code", - "execution_count": 21, + "execution_count": 23, "id": "cf0c95fd-911d-4c0a-a663-5430a9c3d073", "metadata": { "id": "cf0c95fd-911d-4c0a-a663-5430a9c3d073" @@ -667,7 +736,36 @@ }, { "cell_type": "code", - "execution_count": 22, + "execution_count": 24, + "id": "abcf14cc-8ddb-4b01-8a58-72885e55d435", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 42 entries, 0 to 41\n", + "Data columns (total 5 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 id 42 non-null object\n", + " 1 label 42 non-null object\n", + " 2 rfb 0 non-null object\n", + " 3 dataset 42 non-null object\n", + " 4 ID 42 non-null object\n", + "dtypes: object(5)\n", + "memory usage: 1.8+ KB\n" + ] + } + ], + "source": [ + "rfmo_regions_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 25, "id": "59d334e4-6b8a-469c-b401-72613b42bd68", "metadata": { "colab": { @@ -760,7 +858,7 @@ "4 IPHC IPHC None public-rfmo IPHC" ] }, - "execution_count": 22, + "execution_count": 25, "metadata": {}, "output_type": "execute_result" } diff --git a/notebooks/usage-guides/vessels-api.ipynb b/notebooks/usage-guides/vessels-api.ipynb index 6915924..1f6bcc7 100644 --- a/notebooks/usage-guides/vessels-api.ipynb +++ b/notebooks/usage-guides/vessels-api.ipynb @@ -28,7 +28,7 @@ "id": "e9ca2eda-18f1-4f9c-9717-fb1a06423958" }, "source": [ - "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access information about vessels." + "This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access information about vessels through the Global Fishing Watch [Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api)." ] }, { @@ -101,6 +101,14 @@ "## Usage" ] }, + { + "cell_type": "markdown", + "id": "903a49ab-d6c0-4a4c-adf5-11d084edeaf1", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, { "cell_type": "code", "execution_count": 2, @@ -111,6 +119,7 @@ "outputs": [], "source": [ "import os\n", + "\n", "import gfwapiclient as gfw" ] }, @@ -127,7 +136,7 @@ " from google.colab import userdata\n", "\n", " access_token = userdata.get(\"GFW_API_ACCESS_TOKEN\")\n", - "except Exception as exc:\n", + "except Exception:\n", " access_token = os.environ.get(\"GFW_API_ACCESS_TOKEN\")\n", "\n", "access_token = access_token or \"\"" @@ -168,7 +177,6 @@ "source": [ "vessel_search_result = await gfw_client.vessels.search_vessels(\n", " where=\"ssvid='775998121' AND shipname='DON TITO'\",\n", - " datasets=[\"public-global-vessel-identity:latest\"],\n", " includes=[\"MATCH_CRITERIA\", \"OWNERSHIP\"],\n", ")" ] @@ -259,6 +267,38 @@ { "cell_type": "code", "execution_count": 10, + "id": "e7641cd3-b14d-4f6d-8702-26be4400f2e7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 2 entries, 0 to 1\n", + "Data columns (total 8 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 0 non-null object\n", + " 5 combined_sources_info 2 non-null object\n", + " 6 self_reported_info 2 non-null object\n", + " 7 matchCriteria 2 non-null object\n", + "dtypes: int64(1), object(7)\n", + "memory usage: 260.0+ bytes\n" + ] + } + ], + "source": [ + "vessel_search_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 11, "id": "9f7237f0-1de2-4a21-834b-b692cf4452b5", "metadata": { "colab": { @@ -349,7 +389,7 @@ "1 [{'reference': 'c54923e64-46f3-9338-9dcb-ff097... " ] }, - "execution_count": 10, + "execution_count": 11, "metadata": {}, "output_type": "execute_result" } @@ -370,7 +410,7 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 12, "id": "03dbbff9-1768-4e0a-bcea-130ed46f96a0", "metadata": { "id": "03dbbff9-1768-4e0a-bcea-130ed46f96a0" @@ -383,7 +423,6 @@ " \"6583c51e3-3626-5638-866a-f47c3bc7ef7c\",\n", " \"71e7da672-2451-17da-b239-857831602eca\",\n", " ],\n", - " datasets=[\"public-global-vessel-identity:latest\"],\n", ")" ] }, @@ -399,7 +438,7 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 13, "id": "a549433e-53ac-4b7c-969a-d6f20af18668", "metadata": { "id": "a549433e-53ac-4b7c-969a-d6f20af18668" @@ -411,7 +450,7 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 14, "id": "3778b513-3cfe-49b5-9107-731d2f10d82e", "metadata": { "id": "3778b513-3cfe-49b5-9107-731d2f10d82e" @@ -423,7 +462,7 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 15, "id": "8c107871-c3eb-4544-bb6c-87188fa68675", "metadata": { "colab": { @@ -436,10 +475,10 @@ { "data": { "text/plain": [ - "('public-global-vessel-identity:v3.0', '55889aefb-bef9-224c-d2db-58ecd01e1d7c')" + "('public-global-vessel-identity:v3.0', 'aca119c29-95dd-f5c4-2057-ee45268dcd6f')" ] }, - "execution_count": 14, + "execution_count": 15, "metadata": {}, "output_type": "execute_result" } @@ -460,7 +499,7 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": 16, "id": "d792efd2-c741-41e1-91df-f3822cd7ce46", "metadata": { "id": "d792efd2-c741-41e1-91df-f3822cd7ce46" @@ -472,7 +511,38 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": 17, + "id": "608434ad-151f-4fec-b62b-0c1800427362", + "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": [ + "vessels_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 18, "id": "3da7dec8-4f2b-4db9-aed0-38163d591af0", "metadata": { "colab": { @@ -521,22 +591,12 @@ " [{'id': 'a8d00ce54b37add7f85a35fcce8e7a1b', 's...\n", " [{'name': 'COLINER', 'flag': 'RUS', 'ssvid': '...\n", " [{'date_from': 2023-01-01 00:00:00+00:00, 'dat...\n", - " [{'vessel_id': '3c81a942b-bf0a-f476-ea72-75c02...\n", + " [{'vessel_id': 'da1cd7e1b-b8d0-539c-6581-2b3df...\n", " [{'id': 'da1cd7e1b-b8d0-539c-6581-2b3df8d0a6af...\n", " \n", " \n", " 1\n", " public-global-vessel-identity:v3.0\n", - " 2\n", - " [{'id': 'b82d02e5c2c11e5fe5367c91194fc3ba', 's...\n", - " [{'name': 'DONGWON INDUSTRIES', 'flag': 'KOR, ...\n", - " [{'date_from': 2015-10-08 00:00:00+00:00, 'dat...\n", - " [{'vessel_id': 'aca119c29-95dd-f5c4-2057-ee452...\n", - " [{'id': '6583c51e3-3626-5638-866a-f47c3bc7ef7c...\n", - " \n", - " \n", - " 2\n", - " public-global-vessel-identity:v3.0\n", " 1\n", " [{'id': '685862e0626f6234c844919bc738a83a', 's...\n", " [{'name': 'TRANS PACIFIC JOURNEY FISHING', 'fl...\n", @@ -544,6 +604,16 @@ " [{'vessel_id': '55889aefb-bef9-224c-d2db-58ecd...\n", " [{'id': '71e7da672-2451-17da-b239-857831602eca...\n", " \n", + " \n", + " 2\n", + " public-global-vessel-identity:v3.0\n", + " 2\n", + " [{'id': 'b82d02e5c2c11e5fe5367c91194fc3ba', 's...\n", + " [{'name': 'DONGWON INDUSTRIES', 'flag': 'KOR, ...\n", + " [{'date_from': 2015-10-08 00:00:00+00:00, 'dat...\n", + " [{'vessel_id': 'aca119c29-95dd-f5c4-2057-ee452...\n", + " [{'id': '6583c51e3-3626-5638-866a-f47c3bc7ef7c...\n", + " \n", " \n", "\n", "" @@ -551,36 +621,36 @@ "text/plain": [ " dataset registry_info_total_records \\\n", "0 public-global-vessel-identity:v3.0 5 \n", - "1 public-global-vessel-identity:v3.0 2 \n", - "2 public-global-vessel-identity:v3.0 1 \n", + "1 public-global-vessel-identity:v3.0 1 \n", + "2 public-global-vessel-identity:v3.0 2 \n", "\n", " registry_info \\\n", "0 [{'id': 'a8d00ce54b37add7f85a35fcce8e7a1b', 's... \n", - "1 [{'id': 'b82d02e5c2c11e5fe5367c91194fc3ba', 's... \n", - "2 [{'id': '685862e0626f6234c844919bc738a83a', 's... \n", + "1 [{'id': '685862e0626f6234c844919bc738a83a', 's... \n", + "2 [{'id': 'b82d02e5c2c11e5fe5367c91194fc3ba', 's... \n", "\n", " registry_owners \\\n", "0 [{'name': 'COLINER', 'flag': 'RUS', 'ssvid': '... \n", - "1 [{'name': 'DONGWON INDUSTRIES', 'flag': 'KOR, ... \n", - "2 [{'name': 'TRANS PACIFIC JOURNEY FISHING', 'fl... \n", + "1 [{'name': 'TRANS PACIFIC JOURNEY FISHING', 'fl... \n", + "2 [{'name': 'DONGWON INDUSTRIES', 'flag': 'KOR, ... \n", "\n", " registry_public_authorizations \\\n", "0 [{'date_from': 2023-01-01 00:00:00+00:00, 'dat... \n", - "1 [{'date_from': 2015-10-08 00:00:00+00:00, 'dat... \n", - "2 [{'date_from': 2012-01-01 00:00:00+00:00, 'dat... \n", + "1 [{'date_from': 2012-01-01 00:00:00+00:00, 'dat... \n", + "2 [{'date_from': 2015-10-08 00:00:00+00:00, 'dat... \n", "\n", " combined_sources_info \\\n", - "0 [{'vessel_id': '3c81a942b-bf0a-f476-ea72-75c02... \n", - "1 [{'vessel_id': 'aca119c29-95dd-f5c4-2057-ee452... \n", - "2 [{'vessel_id': '55889aefb-bef9-224c-d2db-58ecd... \n", + "0 [{'vessel_id': 'da1cd7e1b-b8d0-539c-6581-2b3df... \n", + "1 [{'vessel_id': '55889aefb-bef9-224c-d2db-58ecd... \n", + "2 [{'vessel_id': 'aca119c29-95dd-f5c4-2057-ee452... \n", "\n", " self_reported_info \n", "0 [{'id': 'da1cd7e1b-b8d0-539c-6581-2b3df8d0a6af... \n", - "1 [{'id': '6583c51e3-3626-5638-866a-f47c3bc7ef7c... \n", - "2 [{'id': '71e7da672-2451-17da-b239-857831602eca... " + "1 [{'id': '71e7da672-2451-17da-b239-857831602eca... \n", + "2 [{'id': '6583c51e3-3626-5638-866a-f47c3bc7ef7c... " ] }, - "execution_count": 16, + "execution_count": 18, "metadata": {}, "output_type": "execute_result" } @@ -601,7 +671,7 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 19, "id": "5b12f20c-9c0e-40f6-ac13-31ad7e0144ab", "metadata": { "id": "5b12f20c-9c0e-40f6-ac13-31ad7e0144ab" @@ -610,7 +680,6 @@ "source": [ "vessel_result = await gfw_client.vessels.get_vessel_by_id(\n", " id=\"c54923e64-46f3-9338-9dcb-ff09724077a3\",\n", - " dataset=\"public-global-vessel-identity:latest\",\n", ")" ] }, @@ -626,7 +695,7 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 20, "id": "ba62e001-a8e9-4dac-9674-461f9cff191f", "metadata": { "id": "ba62e001-a8e9-4dac-9674-461f9cff191f" @@ -638,7 +707,7 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": 21, "id": "4bf8c038-2aab-49d9-acfc-86949d265dfb", "metadata": { "colab": { @@ -654,7 +723,7 @@ "('public-global-vessel-identity:v3.0', 'c54923e64-46f3-9338-9dcb-ff09724077a3')" ] }, - "execution_count": 19, + "execution_count": 21, "metadata": {}, "output_type": "execute_result" } @@ -675,7 +744,7 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": 22, "id": "6f146ff6-f669-466a-b3fc-810a30f14a4d", "metadata": { "id": "6f146ff6-f669-466a-b3fc-810a30f14a4d" @@ -687,7 +756,38 @@ }, { "cell_type": "code", - "execution_count": 21, + "execution_count": 23, + "id": "591d90b1-58ca-4da6-8455-c506953824bf", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 1 entries, 0 to 0\n", + "Data columns (total 7 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 dataset 1 non-null object\n", + " 1 registry_info_total_records 1 non-null int64 \n", + " 2 registry_info 1 non-null object\n", + " 3 registry_owners 1 non-null object\n", + " 4 registry_public_authorizations 1 non-null object\n", + " 5 combined_sources_info 1 non-null object\n", + " 6 self_reported_info 1 non-null object\n", + "dtypes: int64(1), object(6)\n", + "memory usage: 188.0+ bytes\n" + ] + } + ], + "source": [ + "vessel_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 24, "id": "f2b2b97d-bc5b-4dba-a17a-40eb9ada75ab", "metadata": { "colab": { @@ -757,7 +857,7 @@ "0 [{'id': 'c54923e64-46f3-9338-9dcb-ff09724077a3... " ] }, - "execution_count": 21, + "execution_count": 24, "metadata": {}, "output_type": "execute_result" } 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..765071b --- /dev/null +++ b/notebooks/workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez.ipynb @@ -0,0 +1,1269 @@ +{ + "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": "markdown", + "id": "2532e150-f450-4ae6-b7a1-3433b5f25dac", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "cc98323c-c9e4-401c-8f26-f551968c003a", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "import pandas as pd\n", + "\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:\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
0CHNTRAWLERS0.368056412209175MENGXIN24
1ESPTRAWLERS1.306389225987981CIUDAD DE HUELVA
2CHNTRAWLERS216.545000412549331YUAN YU 886
3SENTRAWLERS612.825556663123000ILE AUX OISEAUX
4CHNTRAWLERS31.888889412444322MIN LONG YU61146
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours mmsi ship_name\n", + "0 CHN TRAWLERS 0.368056 412209175 MENGXIN24\n", + "1 ESP TRAWLERS 1.306389 225987981 CIUDAD DE HUELVA\n", + "2 CHN TRAWLERS 216.545000 412549331 YUAN YU 886\n", + "3 SEN TRAWLERS 612.825556 663123000 ILE AUX OISEAUX\n", + "4 CHN TRAWLERS 31.888889 412444322 MIN LONG YU61146" + ] + }, + "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': '29fef17154387858d8d4c777311c57f7', 's...[{'name': 'SENEVISA', 'flag': 'ESP', 'ssvid': ...[{'id': 'bf28c5a58-8c83-8690-8689-7f2d520f926e...
1[{'id': '199483471cd2da3717552fddb1a3172a', 's...[{'name': 'ARMEMENT SOPASEN', 'flag': 'SEN', '...[{'id': '894bc3ec6-6ade-f09c-e792-ff2e947508d8...
\n", + "
" + ], + "text/plain": [ + " registry_info \\\n", + "0 [{'id': '29fef17154387858d8d4c777311c57f7', 's... \n", + "1 [{'id': '199483471cd2da3717552fddb1a3172a', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'SENEVISA', 'flag': 'ESP', 'ssvid': ... \n", + "1 [{'name': 'ARMEMENT SOPASEN', 'flag': 'SEN', '... \n", + "\n", + " self_reported_info \n", + "0 [{'id': 'bf28c5a58-8c83-8690-8689-7f2d520f926e... \n", + "1 [{'id': '894bc3ec6-6ade-f09c-e792-ff2e947508d8... " + ] + }, + "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
0663178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
1762178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
2552178000SENNUEVO NOSO LARNUEVONOSOLAR[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
3663115000SENBETTYBETTY[TRAWLERS][IMO, TMT_NATIONAL, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name gear_types \\\n", + "0 663178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "1 762178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "2 552178000 SEN NUEVO NOSO LAR NUEVONOSOLAR [TRAWLERS] \n", + "3 663115000 SEN BETTY BETTY [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
0663178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
1663176000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
2762178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
3552178000ESPSENEVISA[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
4663115000SENARMEMENT SOPASEN[TMT_NATIONAL, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag name source_code\n", + "0 663178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "1 663176000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "2 762178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "3 552178000 ESP SENEVISA [TMT_NATIONAL, TMT_OTHER_OFFICIAL]\n", + "4 663115000 SEN ARMEMENT SOPASEN [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
0663178000SENNUEVONOSOLARNUEVONOSOLAR[AIS]
1663178000SENNUEVO=NOSOLAR+3&!U.?NUEVONOSOLAR3U[AIS]
2762178000NoneNUEVO NOSOLARNUEVONOSOLAR[AIS]
3552178000NoneNUEVO NOSOLARNUEVONOSOLAR[AIS]
4663178000SENNUEVO NOSOLARNUEVONOSOLAR[AIS]
5663115000SENBETTYBETTY[AIS]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name source_code\n", + "0 663178000 SEN NUEVONOSOLAR NUEVONOSOLAR [AIS]\n", + "1 663178000 SEN NUEVO=NOSOLAR+3&!U.? NUEVONOSOLAR3U [AIS]\n", + "2 762178000 None NUEVO NOSOLAR NUEVONOSOLAR [AIS]\n", + "3 552178000 None NUEVO NOSOLAR NUEVONOSOLAR [AIS]\n", + "4 663178000 SEN NUEVO NOSOLAR NUEVONOSOLAR [AIS]\n", + "5 663115000 SEN BETTY BETTY [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..a146cfc --- /dev/null +++ b/notebooks/workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez.ipynb @@ -0,0 +1,2182 @@ +{ + "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": "markdown", + "id": "420afe1c-ff77-40e2-9a07-7372dc95170c", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "cc98323c-c9e4-401c-8f26-f551968c003a", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "import pandas as pd\n", + "\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:\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
0pots_and_traps92.0297223
1inconclusive215.6238892
2inconclusive98.1558332
3set_longlines17.9258331
4other_purse_seines57.3775001
\n", + "
" + ], + "text/plain": [ + " gear_type hours vessel_ids\n", + "0 pots_and_traps 92.029722 3\n", + "1 inconclusive 215.623889 2\n", + "2 inconclusive 98.155833 2\n", + "3 set_longlines 17.925833 1\n", + "4 other_purse_seines 57.377500 1" + ] + }, + "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
0ARGTRAWLERS714.842500701000882FELIX AUGUSTO
1ARGTRAWLERS641.522222701000932ANTONIO ALVAREZ
2URYTRAWLERS10.023056770576463KALATXORI
3ARGTRAWLERS326.160833701079000ENTRENA UNO
4ARGTRAWLERS295.007500701000820CORAJE
\n", + "
" + ], + "text/plain": [ + " flag gear_type hours mmsi ship_name\n", + "0 ARG TRAWLERS 714.842500 701000882 FELIX AUGUSTO\n", + "1 ARG TRAWLERS 641.522222 701000932 ANTONIO ALVAREZ\n", + "2 URY TRAWLERS 10.023056 770576463 KALATXORI\n", + "3 ARG TRAWLERS 326.160833 701079000 ENTRENA UNO\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': '2d939efefd3f45788ed103ff0723f564', 's...[{'name': 'CLEARWATER SEAFOODS', 'flag': 'CAN'...[{'id': 'de8a03acd-dc6c-8e08-2867-24e55ffc0017...
1[{'id': '45502524c9a150e77869ee647423dba1', 's...[{'name': 'GLACIAR PESQUERA', 'flag': 'ARG', '...[{'id': '8e930bac5-594b-aa3f-081d-d12668819e1f...
\n", + "
" + ], + "text/plain": [ + " registry_info \\\n", + "0 [{'id': '2d939efefd3f45788ed103ff0723f564', 's... \n", + "1 [{'id': '45502524c9a150e77869ee647423dba1', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'CLEARWATER SEAFOODS', 'flag': 'CAN'... \n", + "1 [{'name': 'GLACIAR PESQUERA', 'flag': 'ARG', '... \n", + "\n", + " self_reported_info \n", + "0 [{'id': 'de8a03acd-dc6c-8e08-2867-24e55ffc0017... \n", + "1 [{'id': '8e930bac5-594b-aa3f-081d-d12668819e1f... " + ] + }, + "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
0701006605ARGCAPESANTECAPESANTE[TRAWLERS][GFW-REVIEW, IMO, RESEARCH-PAPER, TMT_OTHER_OF...
1316003980CANATLANTICLEADERATLANTICLEADER[TRAWLERS][IMO, TMT_OTHER_OFFICIAL]
2701024000ARGATLANTIC SURF IIIATLANTICSURF3[TRAWLERS][IMO, TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name gear_types \\\n", + "0 701006605 ARG CAPESANTE CAPESANTE [TRAWLERS] \n", + "1 316003980 CAN ATLANTICLEADER ATLANTICLEADER [TRAWLERS] \n", + "2 701024000 ARG ATLANTIC SURF III ATLANTICSURF3 [TRAWLERS] \n", + "\n", + " source_code \n", + "0 [GFW-REVIEW, IMO, RESEARCH-PAPER, TMT_OTHER_OF... \n", + "1 [IMO, TMT_OTHER_OFFICIAL] \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
0701006605CANCLEARWATER SEAFOODS[RESEARCH-PAPER]
1316003980CANCS MANPAR[TMT_OTHER_OFFICIAL]
2701024000ARGGLACIAR PESQUERA[TMT_OTHER_OFFICIAL]
\n", + "
" + ], + "text/plain": [ + " ssvid flag name source_code\n", + "0 701006605 CAN CLEARWATER SEAFOODS [RESEARCH-PAPER]\n", + "1 316003980 CAN CS MANPAR [TMT_OTHER_OFFICIAL]\n", + "2 701024000 ARG GLACIAR PESQUERA [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
0701006605ARGCAPESANTECAPESANTE[AIS]
1316003980CANATLANTIC LEADERATLANTICLEADER[AIS]
2701024000ARGATLANTIC SURF IIIATLANTICSURF3[AIS]
\n", + "
" + ], + "text/plain": [ + " ssvid flag ship_name n_ship_name source_code\n", + "0 701006605 ARG CAPESANTE CAPESANTE [AIS]\n", + "1 316003980 CAN ATLANTIC LEADER ATLANTICLEADER [AIS]\n", + "2 701024000 ARG ATLANTIC SURF III ATLANTICSURF3 [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 III701024000222.7216104.098386
1ATLANTIC SURF III7010240007.9053354.590909
2ATLANTIC SURF III7010240002.7946814.655555
3ATLANTIC SURF III7010240002.0123922.953846
4ATLANTIC SURF III7010240003.2600403.705556
...............
346CAPESANTE70100660525.5687964.074561
347CAPESANTE70100660545.8309803.771852
348CAPESANTE70100660574.6118304.087912
349CAPESANTE70100660582.6075253.788187
350CAPESANTE701006605205.8262824.136848
\n", + "

351 rows × 4 columns

\n", + "
" + ], + "text/plain": [ + " name ssvid total_distance_km average_speed_knots\n", + "0 ATLANTIC SURF III 701024000 222.721610 4.098386\n", + "1 ATLANTIC SURF III 701024000 7.905335 4.590909\n", + "2 ATLANTIC SURF III 701024000 2.794681 4.655555\n", + "3 ATLANTIC SURF III 701024000 2.012392 2.953846\n", + "4 ATLANTIC SURF III 701024000 3.260040 3.705556\n", + ".. ... ... ... ...\n", + "346 CAPESANTE 701006605 25.568796 4.074561\n", + "347 CAPESANTE 701006605 45.830980 3.771852\n", + "348 CAPESANTE 701006605 74.611830 4.087912\n", + "349 CAPESANTE 701006605 82.607525 3.788187\n", + "350 CAPESANTE 701006605 205.826282 4.136848\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
2ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
3CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
4ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
5CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
6ATLANTIC SURF III7010240004MAR DEL PLATAMAR DEL PLATAMAR DEL PLATA
7CAPESANTE7010066054USHUAIAUSHUAIAUSHUAIA
\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 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "3 CAPESANTE 701006605 4 USHUAIA \n", + "4 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "5 CAPESANTE 701006605 4 USHUAIA \n", + "6 ATLANTIC SURF III 701024000 4 MAR DEL PLATA \n", + "7 CAPESANTE 701006605 4 USHUAIA \n", + "\n", + " intermediate_anchorage_name end_anchorage_name \n", + "0 MAR DEL PLATA MAR DEL PLATA \n", + "1 USHUAIA USHUAIA \n", + "2 MAR DEL PLATA MAR DEL PLATA \n", + "3 USHUAIA USHUAIA \n", + "4 MAR DEL PLATA MAR DEL PLATA \n", + "5 USHUAIA USHUAIA \n", + "6 MAR DEL PLATA MAR DEL PLATA \n", + "7 USHUAIA USHUAIA " + ] + }, + "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..76f7033 --- /dev/null +++ b/notebooks/workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez.ipynb @@ -0,0 +1,2005 @@ +{ + "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": "markdown", + "id": "53f445b9-02bb-425a-817a-2768941c7d5a", + "metadata": {}, + "source": [ + "Import and use `gfw-api-python-client` in your Python codes" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "d93d57ae-0ec7-4d97-8fea-f679e89fc3b1", + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "\n", + "import pandas as pd\n", + "\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:\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
2Nonepole_and_line3481.5091675
3Noneother_purse_seines26.5811111
4Nonefishing20929.56333321
\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 pole_and_line 3481.509167 5\n", + "3 None other_purse_seines 26.581111 1\n", + "4 None fishing 20929.563333 21" + ] + }, + "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 SHUN41600749644.0268823.808824
1HUNG CHUAN SHUN4160074969.3535008.200000
2HUNG CHUAN SHUN4160074969.8680505.494444
3HUNG CHUAN SHUN41600749610.9553108.555556
4HUNG CHUAN SHUN4160074969.6306878.942857
...............
409HUNG CHUAN SHUN416007496101.4022634.041791
410HUNG CHUAN SHUN416007496115.6421594.743357
411HUNG CHUAN SHUN416007496100.0194564.402564
412HUNG CHUAN SHUN416007496155.9231384.975000
413HUNG CHUAN SHUN416007496173.2531374.869231
\n", + "

414 rows × 4 columns

\n", + "
" + ], + "text/plain": [ + " name ssvid total_distance_km average_speed_knots\n", + "0 HUNG CHUAN SHUN 416007496 44.026882 3.808824\n", + "1 HUNG CHUAN SHUN 416007496 9.353500 8.200000\n", + "2 HUNG CHUAN SHUN 416007496 9.868050 5.494444\n", + "3 HUNG CHUAN SHUN 416007496 10.955310 8.555556\n", + "4 HUNG CHUAN SHUN 416007496 9.630687 8.942857\n", + ".. ... ... ... ...\n", + "409 HUNG CHUAN SHUN 416007496 101.402263 4.041791\n", + "410 HUNG CHUAN SHUN 416007496 115.642159 4.743357\n", + "411 HUNG CHUAN SHUN 416007496 100.019456 4.402564\n", + "412 HUNG CHUAN SHUN 416007496 155.923138 4.975000\n", + "413 HUNG CHUAN SHUN 416007496 173.253137 4.869231\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
0SENSHU MARU NO.34311006904TEMATEMATEMA
1HUNG CHUAN SHUN4160074964TEMATEMATEMA
2SENSHU MARU NO.34311006904TEMATEMATEMA
3None4123310324DAKARDAKARDAKAR
\n", + "
" + ], + "text/plain": [ + " name ssvid confidence start_anchorage_name \\\n", + "0 SENSHU MARU NO.3 431100690 4 TEMA \n", + "1 HUNG CHUAN SHUN 416007496 4 TEMA \n", + "2 SENSHU MARU NO.3 431100690 4 TEMA \n", + "3 None 412331032 4 DAKAR \n", + "\n", + " intermediate_anchorage_name end_anchorage_name \n", + "0 TEMA TEMA \n", + "1 TEMA TEMA \n", + "2 TEMA TEMA \n", + "3 DAKAR DAKAR " + ] + }, + "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/pyproject.toml b/pyproject.toml index f33e3b3..ffaaa5b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -75,7 +75,7 @@ dependencies = [ [project.optional-dependencies] # Linting and code quality tools lint = [ - "black>=25.9.0", # Code formatting tool + "black[jupyter]>=25.9.0", # Code formatting tool "isort>=7.0.0", # Python imports sorting tool "mypy>=1.18.2", # Static type checker "pydocstyle>=6.3.0", # Python docstring style checker