diff --git a/README.md b/README.md index 342a448..ebc8848 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ The Global Fishing Watch Python package currently works with the following APIs: - [References API](https://globalfishingwatch.org/our-apis/documentation#regions): Access metadata for EEZs, MPAs, and RFMOs to use in [Events API](https://globalfishingwatch.org/our-apis/documentation#events-api) and [Map Visualization (4Wings API)](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api) requests and analyses. -> **Note:** See the [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits. +> **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits. ## Requirements diff --git a/docs/source/development-guides/changelog.md b/docs/source/development-guides/changelog.md index dd74d15..4f3f75f 100644 --- a/docs/source/development-guides/changelog.md +++ b/docs/source/development-guides/changelog.md @@ -3,4 +3,5 @@ All notable changes to this project will be documented in this file. ```{include} ../../../CHANGELOG.md + ``` diff --git a/docs/source/development-guides/code-of-conduct.md b/docs/source/development-guides/code-of-conduct.md index 03ce547..7d7f11c 100644 --- a/docs/source/development-guides/code-of-conduct.md +++ b/docs/source/development-guides/code-of-conduct.md @@ -1,2 +1,3 @@ ```{include} ../../../CODE_OF_CONDUCT.md + ``` diff --git a/docs/source/development-guides/contributing.md b/docs/source/development-guides/contributing.md index 004f419..7f619f5 100644 --- a/docs/source/development-guides/contributing.md +++ b/docs/source/development-guides/contributing.md @@ -1,2 +1,3 @@ ```{include} ../../../CONTRIBUTING.md + ``` diff --git a/docs/source/development-guides/git-workflow.md b/docs/source/development-guides/git-workflow.md index 157422a..47caf96 100644 --- a/docs/source/development-guides/git-workflow.md +++ b/docs/source/development-guides/git-workflow.md @@ -1,2 +1,3 @@ ```{include} ../../../GIT_WORKFLOW.md + ``` diff --git a/docs/source/development-guides/index.md b/docs/source/development-guides/index.md index e1159ac..54a59f9 100644 --- a/docs/source/development-guides/index.md +++ b/docs/source/development-guides/index.md @@ -2,7 +2,6 @@ The sections below will help you get started with development, testing, and documentation. - ```{toctree} :maxdepth: 1 diff --git a/docs/source/development-guides/license.md b/docs/source/development-guides/license.md index 57b86a0..3bdb79c 100644 --- a/docs/source/development-guides/license.md +++ b/docs/source/development-guides/license.md @@ -1,4 +1,5 @@ # License ```{include} ../../../LICENSE + ``` diff --git a/docs/source/development-guides/security.md b/docs/source/development-guides/security.md index cef7352..c559719 100644 --- a/docs/source/development-guides/security.md +++ b/docs/source/development-guides/security.md @@ -1,2 +1,3 @@ ```{include} ../../../SECURITY.md + ``` diff --git a/docs/source/development-guides/setup.md b/docs/source/development-guides/setup.md index c856d25..e68a53b 100644 --- a/docs/source/development-guides/setup.md +++ b/docs/source/development-guides/setup.md @@ -1,2 +1,3 @@ ```{include} ../../../SETUP.md + ``` diff --git a/docs/source/getting-started.md b/docs/source/getting-started.md index c6b887a..9bccd24 100644 --- a/docs/source/getting-started.md +++ b/docs/source/getting-started.md @@ -4,7 +4,7 @@ This guide introduces you to the basics of using the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client). For detailed and alternative installation instructions, please refer to the [Installation](installation) section. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/getting-started.ipynb) version for this guide. -> **Note:** See the [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits. +> **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits. ## Authorization @@ -42,10 +42,13 @@ For more detailed installation instructions, including setting up a virtual envi ## Basic Usage +Open In Colab + Once installed, you can import and use `gfw-api-python-client` in your Python codes: ```python import os +import datetime import gfwapiclient as gfw @@ -66,15 +69,38 @@ gfw_client = gfw.Client( ```python vessel_search_result = await gfw_client.vessels.search_vessels( - query="368045130", - datasets=["public-global-vessel-identity:latest"], - includes=["MATCH_CRITERIA", "OWNERSHIP", "AUTHORIZATIONS"], + query="412331038", ) -vessel_ids = [ +vessel_search_ids = [ self_reported_info.id - for vessel in vessel_search_result.data() - for self_reported_info in vessel.self_reported_info + for vessel_search_item in vessel_search_result.data() + if vessel_search_item.registry_info_total_records >= 1 + for self_reported_info in vessel_search_item.self_reported_info +] + +print(vessel_search_ids) +``` + +**Output:** + +``` +['755a48dd4-4bee-4bcf-7b5f-9baea058fc7b', '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'] +``` + +**Note:** It is recommended to prioritize vessels that include both `registry_info` and `self_reported_info` (AIS), as this indicates a successful match between registry data and AIS information. + +### Getting Details of Vessels Filtered by Vessel Searched IDs + +```python +vessels_result = await gfw_client.vessels.get_vessels_by_ids( + ids=vessel_search_ids, +) + +vessel_self_reported_infos = [ + self_reported_info + for vessel_item in vessels_result.data() + for self_reported_info in vessel_item.self_reported_info ] print(vessel_ids) @@ -83,16 +109,85 @@ print(vessel_ids) **Output:** ``` -["3312b30d6-65b6-1bdb-6a78-3f5eb3977e58", "126221ace-e3b5-f4ed-6150-394809737c55"] +['755a48dd4-4bee-4bcf-7b5f-9baea058fc7b', '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'] ``` -### Getting Fishing Events for the Searched Vessels +### Getting Insights Related to Fishing Events for the Vessel Searched + +**Important:** `start_date` must be on or after `January 1, 2020` + +```python +start_datetime = min( + [ + self_reported_info.transmission_date_from + for self_reported_info in vessel_self_reported_infos + ] +) +start_date = start_datetime.date() + + +end_datetime = max( + [ + self_reported_info.transmission_date_to + for self_reported_info in vessel_self_reported_infos + ] +) +end_date = end_datetime.date() + +dataset_id = "public-global-vessel-identity:latest" +dataset_ids_vessel_ids = [ + {"dataset_id": dataset_id, "vessel_id": vessel_id} for vessel_id in vessel_ids +] + +insights_result = await gfw_client.insights.get_vessel_insights( + includes=["FISHING"], + start_date=start_date, + end_date=end_date, + vessels=dataset_ids_vessel_ids, +) + +insights_df = insights_result.df() + +print(insights_df.info()) +``` + +**Output:** + +``` + +RangeIndex: 1 entries, 0 to 0 +Data columns (total 6 columns): + # Column Non-Null Count Dtype +--- ------ -------------- ----- + 0 period 1 non-null object + 1 vessel_ids_without_identity 0 non-null object + 2 gap 0 non-null object + 3 coverage 0 non-null object + 4 apparent_fishing 1 non-null object + 5 vessel_identity 0 non-null object +dtypes: object(6) +memory usage: 180.0+ bytes +``` + +```python +insights_data = insights_result.data() + +print(dict(insights_data.apparent_fishing.period_selected_counters)) +``` + +**Output:** + +``` +{'events': 398, 'events_gap_off': None, 'events_in_rfmo_without_known_authorization': 144, 'events_in_no_take_mpas': 0} +``` + +### Getting Fishing Events for the Vessels Searched ```python events_result = await gfw_client.events.get_all_events( datasets=["public-global-fishing-events:latest"], - start_date="2024-03-01", - end_date="2025-03-31", + start_date=start_date, + end_date=end_date, vessels=vessel_ids, ) @@ -101,30 +196,30 @@ events_df = events_result.df() print(events_df.info()) ``` -Output: +**Output:** ``` -RangeIndex: 3 entries, 0 to 2 +RangeIndex: 398 entries, 0 to 397 Data columns (total 14 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- - 0 start 3 non-null datetime64[ns, UTC] - 1 end 3 non-null datetime64[ns, UTC] - 2 id 3 non-null object - 3 type 3 non-null object - 4 position 3 non-null object - 5 regions 3 non-null object - 6 bounding_box 3 non-null object - 7 distances 3 non-null object - 8 vessel 3 non-null object + 0 start 398 non-null datetime64[ns, UTC] + 1 end 398 non-null datetime64[ns, UTC] + 2 id 398 non-null object + 3 type 398 non-null object + 4 position 398 non-null object + 5 regions 398 non-null object + 6 bounding_box 398 non-null object + 7 distances 398 non-null object + 8 vessel 398 non-null object 9 encounter 0 non-null object - 10 fishing 3 non-null object + 10 fishing 398 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: 468.0+ bytes +memory usage: 43.7+ KB ``` ## Next Steps diff --git a/docs/source/index.md b/docs/source/index.md index 15707df..bb58aed 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -4,7 +4,9 @@ hide-toc: true # gfw-api-python-client -The `gfw-api-python-client` simplifies access to Global Fishing Watch (GFW) data through [our APIs](https://globalfishingwatch.org/our-apis/documentation). It offers straightforward functions for retrieving GFW data. For R users, we also provide the gfwr package; learn more [here](https://globalfishingwatch.github.io/gfwr/) +The `gfw-api-python-client` simplifies access to Global Fishing Watch (GFW) data through [our APIs](https://globalfishingwatch.org/our-apis/documentation). It offers straightforward functions for retrieving GFW data. For **R users**, we also provide the [gfwr](https://github.com/GlobalFishingWatch/gfwr) package; learn more [here](https://globalfishingwatch.github.io/gfwr/) + +> **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} :hidden: @@ -29,6 +31,7 @@ GitHub Website Our APIs +Datasets Data Caveats Terms of Use FAQs @@ -40,12 +43,12 @@ To learn about how to use `gfw-api-python-client`, check out the following resou - [Getting Started](getting-started) - [Installation Guide](installation) - [Usage Guides](usage-guides/index) - - [4Wings API](usage-guides/4wings-api) - - [Vessels API](usage-guides/vessels-api) - - [Events API](usage-guides/events-api) - - [Insights API](usage-guides/insights-api) - - [Datasets API](usage-guides/datasets-api) - - [References Data API](usage-guides/references-data-api) + - [4Wings API](usage-guides/4wings-api) + - [Vessels API](usage-guides/vessels-api) + - [Events API](usage-guides/events-api) + - [Insights API](usage-guides/insights-api) + - [Datasets API](usage-guides/datasets-api) + - [References Data API](usage-guides/references-data-api) If you find bugs, need help, or want to contribute, check out the following resources: diff --git a/docs/source/installation.md b/docs/source/installation.md index f703928..d63111c 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -1,2 +1,3 @@ ```{include} ../../INSTALLATION.md + ``` diff --git a/docs/source/usage-guides/4wings-api.md b/docs/source/usage-guides/4wings-api.md index 068bcee..748f00b 100644 --- a/docs/source/usage-guides/4wings-api.md +++ b/docs/source/usage-guides/4wings-api.md @@ -4,11 +4,11 @@ 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. -> **Note:** See the [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits. +> **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits. ## Prerequisites -- You have installed the `gfw-api-python-client`. Refer to the [Getting Started](../getting-started) guide for installation instructions. +- 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 @@ -40,7 +40,7 @@ Generates **AIS (Automatic Identification System) apparent fishing effort** repo fishing_effort_report_result = await gfw_client.fourwings.create_fishing_effort_report( spatial_resolution="LOW", temporal_resolution="MONTHLY", - group_by="GEARTYPE", + group_by="FLAG", start_date="2022-01-01", end_date="2022-05-01", region={ @@ -59,7 +59,7 @@ fishing_effort_report_item = fishing_effort_report_data[-1] print(( fishing_effort_report_item.date, - fishing_effort_report_item.gear_type, + fishing_effort_report_item.flag, fishing_effort_report_item.hours, fishing_effort_report_item.vessel_ids, fishing_effort_report_item.lat, @@ -70,7 +70,7 @@ print(( **Output:** ``` -('2022-04', 'fishing', 2.705, 1, 52.0, 155.2) +('2022-03', 'RUS', 7.109166666666667, 3, 75.8, 44.0) ``` ### Access the report data as a DataFrame @@ -79,23 +79,23 @@ print(( fishing_effort_report_df = fishing_effort_report_result.df() print(fishing_effort_report_df.info()) -print(fishing_effort_report_df[["date", "gear_type", "hours", "vessel_ids", "lat", "lon"]].head()) +print(fishing_effort_report_df[["date", "flag", "hours", "vessel_ids", "lat", "lon"]].head()) ``` **Output:** ``` -RangeIndex: 41916 entries, 0 to 41915 +RangeIndex: 32271 entries, 0 to 32270 Data columns (total 20 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- - 0 date 41916 non-null object + 0 date 32271 non-null object 1 detections 0 non-null object - 2 flag 0 non-null object - 3 gear_type 41916 non-null object - 4 hours 41916 non-null float64 - 5 vessel_ids 41916 non-null int64 + 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 @@ -106,12 +106,12 @@ Data columns (total 20 columns): 13 mmsi 0 non-null object 14 call_sign 0 non-null object 15 dataset 0 non-null object - 16 report_dataset 41916 non-null object + 16 report_dataset 32271 non-null object 17 ship_name 0 non-null object - 18 lat 41916 non-null float64 - 19 lon 41916 non-null float64 + 18 lat 32271 non-null float64 + 19 lon 32271 non-null float64 dtypes: float64(3), int64(1), object(16) -memory usage: 6.4+ MB +memory usage: 4.9+ MB ``` ## Creating an AIS Presence Report (`create_ais_presence_report`) @@ -124,7 +124,7 @@ Generates **AIS (Automatic Identification System) vessel presence** reports to v ais_presence_report_result = await gfw_client.fourwings.create_ais_presence_report( spatial_resolution="LOW", temporal_resolution="MONTHLY", - group_by="GEARTYPE", + group_by="FLAG", start_date="2022-01-01", end_date="2022-05-01", region={ @@ -143,6 +143,7 @@ ais_presence_report_item = ais_presence_report_data[-1] print(( ais_presence_report_item.date, + ais_presence_report_item.flag, ais_presence_report_item.hours, ais_presence_report_item.vessel_ids, ais_presence_report_item.lat, @@ -153,7 +154,7 @@ print(( **Output:** ``` -('2022-04', 9.0, 8, 50.4, 160.7) +('2022-03', 'RUS', 1.0, 1, 52.1, 153.2) ``` ### Access the report data as a DataFrame @@ -162,23 +163,23 @@ print(( ais_presence_report_df = ais_presence_report_result.df() print(ais_presence_report_df.info()) -print(ais_presence_report_df[["date", "hours", "vessel_ids", "lat", "lon"]].head()) +print(ais_presence_report_df[["date", "flag", "hours", "vessel_ids", "lat", "lon"]].head()) ``` **Output:** ``` -RangeIndex: 144227 entries, 0 to 144226 +RangeIndex: 274333 entries, 0 to 274332 Data columns (total 20 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- - 0 date 144227 non-null object + 0 date 274333 non-null object 1 detections 0 non-null object - 2 flag 0 non-null object - 3 gear_type 144227 non-null object - 4 hours 144227 non-null float64 - 5 vessel_ids 144227 non-null int64 + 2 flag 274333 non-null object + 3 gear_type 0 non-null object + 4 hours 274333 non-null float64 + 5 vessel_ids 274333 non-null int64 6 vessel_id 0 non-null object 7 vessel_type 0 non-null object 8 entry_timestamp 0 non-null object @@ -189,12 +190,12 @@ Data columns (total 20 columns): 13 mmsi 0 non-null object 14 call_sign 0 non-null object 15 dataset 0 non-null object - 16 report_dataset 144227 non-null object + 16 report_dataset 274333 non-null object 17 ship_name 0 non-null object - 18 lat 144227 non-null float64 - 19 lon 144227 non-null float64 + 18 lat 274333 non-null float64 + 19 lon 274333 non-null float64 dtypes: float64(3), int64(1), object(16) -memory usage: 22.0+ MB +memory usage: 41.9+ MB ``` ## Creating a SAR Vessel Detections Report (`create_sar_presence_report`) @@ -226,6 +227,7 @@ sar_presence_report_item = sar_presence_report_data[-1] print(( sar_presence_report_item.date, + sar_presence_report_item.flag, sar_presence_report_item.detections, sar_presence_report_item.vessel_ids, sar_presence_report_item.lat, @@ -236,7 +238,7 @@ print(( **Output:** ``` -('2022-04', 1, 1, 46.6, 142.6) +('2022-04', '', 1, 1, 46.6, 142.6) ``` ### Access the report data as a DataFrame @@ -245,23 +247,23 @@ print(( sar_presence_report_df = sar_presence_report_result.df() print(sar_presence_report_df.info()) -print(sar_presence_report_df[["date", "detections", "vessel_ids", "lat", "lon"]].head()) +print(sar_presence_report_df[["date", "flag", "detections", "vessel_ids", "lat", "lon"]].head()) ``` **Output:** ``` -RangeIndex: 3300 entries, 0 to 3299 +RangeIndex: 3995 entries, 0 to 3994 Data columns (total 20 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- - 0 date 3300 non-null object - 1 detections 3300 non-null int64 - 2 flag 0 non-null object - 3 gear_type 3300 non-null object + 0 date 3995 non-null object + 1 detections 3995 non-null int64 + 2 flag 3995 non-null object + 3 gear_type 0 non-null object 4 hours 0 non-null object - 5 vessel_ids 3300 non-null int64 + 5 vessel_ids 3995 non-null int64 6 vessel_id 0 non-null object 7 vessel_type 0 non-null object 8 entry_timestamp 0 non-null object @@ -272,23 +274,25 @@ Data columns (total 20 columns): 13 mmsi 0 non-null object 14 call_sign 0 non-null object 15 dataset 0 non-null object - 16 report_dataset 3300 non-null object + 16 report_dataset 3995 non-null object 17 ship_name 0 non-null object - 18 lat 3300 non-null float64 - 19 lon 3300 non-null float64 + 18 lat 3995 non-null float64 + 19 lon 3995 non-null float64 dtypes: float64(2), int64(2), object(16) -memory usage: 515.8+ KB +memory usage: 624.3+ KB ``` ## Creating a Report (`create_report`) Generates a report for any [supported datasets](https://globalfishingwatch.org/our-apis/documentation#supported-datasets), using fully customizable parameters. [Please check the data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat). +> **Note:** AIS vessel presence (i.e., `"public-global-sar-presence:latest"` dataset) does **not** support `"GEARTYPE"` or `"FLAGANDGEARTYPE"` as `group_by` criteria. + ```python report_result = await gfw_client.fourwings.create_report( spatial_resolution="LOW", temporal_resolution="MONTHLY", - group_by="GEARTYPE", + group_by="FLAG", datasets=["public-global-fishing-effort:latest"], start_date="2022-01-01", end_date="2022-05-01", @@ -308,7 +312,7 @@ report_item = report_data[-1] print(( report_item.date, - report_item.gear_type, + report_item.flag, report_item.hours, report_item.vessel_ids, report_item.lat, @@ -320,7 +324,7 @@ print(report_item.model_dump()) **Output:** ``` -('2022-04', 'fishing', 2.705, 1, 52.0, 155.2) +('2022-03', 'RUS', 7.109166666666667, 3, 75.8, 44.0) ``` ### Access the report data as a DataFrame @@ -329,23 +333,23 @@ print(report_item.model_dump()) report_df = report_result.df() print(report_df.info()) -print(report_df[["date", "hours", "lat", "lon"]].head()) +print(report_df[["date", "flag", "hours", "lat", "lon"]].head()) ``` **Output:** ``` -RangeIndex: 41916 entries, 0 to 41915 +RangeIndex: 32271 entries, 0 to 32270 Data columns (total 20 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- - 0 date 41916 non-null object + 0 date 32271 non-null object 1 detections 0 non-null object - 2 flag 0 non-null object - 3 gear_type 41916 non-null object - 4 hours 41916 non-null float64 - 5 vessel_ids 41916 non-null int64 + 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 @@ -356,12 +360,12 @@ Data columns (total 20 columns): 13 mmsi 0 non-null object 14 call_sign 0 non-null object 15 dataset 0 non-null object - 16 report_dataset 41916 non-null object + 16 report_dataset 32271 non-null object 17 ship_name 0 non-null object - 18 lat 41916 non-null float64 - 19 lon 41916 non-null float64 + 18 lat 32271 non-null float64 + 19 lon 32271 non-null float64 dtypes: float64(3), int64(1), object(16) -memory usage: 6.4+ MB +memory usage: 4.9+ MB ``` ## Reference Data diff --git a/docs/source/usage-guides/datasets-api.md b/docs/source/usage-guides/datasets-api.md index 61649ce..0c1e96f 100644 --- a/docs/source/usage-guides/datasets-api.md +++ b/docs/source/usage-guides/datasets-api.md @@ -4,11 +4,11 @@ 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. -> **Note:** See the [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. +> **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. ## Prerequisites -- You have installed the `gfw-api-python-client`. Refer to the [Getting Started](../getting-started) guide for installation instructions. +- 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 diff --git a/docs/source/usage-guides/events-api.md b/docs/source/usage-guides/events-api.md index a5079a8..c570a91 100644 --- a/docs/source/usage-guides/events-api.md +++ b/docs/source/usage-guides/events-api.md @@ -4,11 +4,11 @@ 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. -> **Note:** See the [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. +> **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. ## Prerequisites -- You have installed the `gfw-api-python-client`. Refer to the [Getting Started](../getting-started) guide for installation instructions. +- 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 diff --git a/docs/source/usage-guides/index.md b/docs/source/usage-guides/index.md index f3aacd0..00ec833 100644 --- a/docs/source/usage-guides/index.md +++ b/docs/source/usage-guides/index.md @@ -2,6 +2,8 @@ The sections below provide detailed instructions and examples for interacting with the various APIs offered by Global Fishing Watch using the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client). +> **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 diff --git a/docs/source/usage-guides/insights-api.md b/docs/source/usage-guides/insights-api.md index 2270b9f..5208c2b 100644 --- a/docs/source/usage-guides/insights-api.md +++ b/docs/source/usage-guides/insights-api.md @@ -4,11 +4,11 @@ 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. -> **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 [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) page 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 [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. ## Prerequisites -- You have installed the `gfw-api-python-client`. Refer to the [Getting Started](../getting-started) guide for installation instructions. +- 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). - You will need a valid `Vessel ID` to retrieve insights for a specific vessel. You can obtain these IDs using the [Vessels API](vessels-api). diff --git a/docs/source/usage-guides/references-data-api.md b/docs/source/usage-guides/references-data-api.md index 19b24c5..1290a74 100644 --- a/docs/source/usage-guides/references-data-api.md +++ b/docs/source/usage-guides/references-data-api.md @@ -4,11 +4,11 @@ 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. -> **Note:** See the [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. +> **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. ## Prerequisites -- You have installed the `gfw-api-python-client`. Refer to the [Getting Started](../getting-started) guide for installation instructions. +- 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 diff --git a/docs/source/usage-guides/vessels-api.md b/docs/source/usage-guides/vessels-api.md index e980e05..ec9ef6c 100644 --- a/docs/source/usage-guides/vessels-api.md +++ b/docs/source/usage-guides/vessels-api.md @@ -4,11 +4,11 @@ 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. -> **Note:** See the [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. +> **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. ## Prerequisites -- You have installed the `gfw-api-python-client`. Refer to the [Getting Started](../getting-started) guide for installation instructions. +- 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 diff --git a/notebooks/getting-started.ipynb b/notebooks/getting-started.ipynb index 1705966..4be4609 100644 --- a/notebooks/getting-started.ipynb +++ b/notebooks/getting-started.ipynb @@ -36,7 +36,7 @@ "id": "54769843-ce28-4fcb-84ca-d57636e1f5b1", "metadata": {}, "source": [ - "**Note:** See the [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat) and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits." + "**Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits." ] }, { @@ -56,7 +56,7 @@ "id": "7523e57e-6439-43cb-ae85-2bf789462453" }, "source": [ - "Before using the `gfw-api-python-client`, you need to obtain an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)" + "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)." ] }, { @@ -121,6 +121,8 @@ "outputs": [], "source": [ "import os\n", + "import datetime\n", + "import pandas as pd\n", "import gfwapiclient as gfw" ] }, @@ -187,31 +189,398 @@ "outputs": [], "source": [ "vessel_search_result = await gfw_client.vessels.search_vessels(\n", - " query=\"368045130\",\n", - " datasets=[\"public-global-vessel-identity:latest\"],\n", - " includes=[\"MATCH_CRITERIA\", \"OWNERSHIP\", \"AUTHORIZATIONS\"],\n", + " query=\"412331038\",\n", ")" ] }, { "cell_type": "code", "execution_count": 6, - "id": "44a0cd8d-4ec6-4163-8ecc-90d9a1300641", - "metadata": { - "id": "44a0cd8d-4ec6-4163-8ecc-90d9a1300641" - }, + "id": "9e2d4dae-455b-43ca-81ed-dea8917b1b23", + "metadata": {}, "outputs": [], "source": [ - "vessel_ids = [\n", + "vessel_search_df = vessel_search_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "5a970cc1-2f4e-424b-a7bb-b92f935cfbe7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "\n", + "RangeIndex: 5 entries, 0 to 4\n", + "Data columns (total 8 columns):\n", + " # Column Non-Null Count Dtype \n", + "--- ------ -------------- ----- \n", + " 0 dataset 5 non-null object\n", + " 1 registry_info_total_records 5 non-null int64 \n", + " 2 registry_info 5 non-null object\n", + " 3 registry_owners 5 non-null object\n", + " 4 registry_public_authorizations 5 non-null object\n", + " 5 combined_sources_info 5 non-null object\n", + " 6 self_reported_info 5 non-null object\n", + " 7 matchCriteria 5 non-null object\n", + "dtypes: int64(1), object(7)\n", + "memory usage: 452.0+ bytes\n" + ] + } + ], + "source": [ + "vessel_search_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "17b0c17c-92e0-49e1-9aaa-0831d4de567c", + "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", + "
datasetregistry_info_total_recordsregistry_inforegistry_ownersregistry_public_authorizationscombined_sources_infoself_reported_infomatchCriteria
0public-global-vessel-identity:v3.00[][][][{'vessel_id': '91df2f8c7-74fd-5b5a-60f5-3d86f...[{'id': '91df2f8c7-74fd-5b5a-60f5-3d86f9c51ff2...[{'reference': '91df2f8c7-74fd-5b5a-60f5-3d86f...
1public-global-vessel-identity:v3.01[{'id': '4ef90bea19300c6a23f6ce627a80238b', 's...[{'name': 'ZHOUSHAN SHUNHANG OCEAN FISHERIES',...[{'date_from': 2017-01-04 00:00:00+00:00, 'dat...[{'vessel_id': '755a48dd4-4bee-4bcf-7b5f-9baea...[{'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b...[{'reference': '755a48dd4-4bee-4bcf-7b5f-9baea...
2public-global-vessel-identity:v3.00[][][][{'vessel_id': 'a5ef97d59-9f40-3bdc-e247-daf9c...[{'id': 'a5ef97d59-9f40-3bdc-e247-daf9c892ceff...[{'reference': 'a5ef97d59-9f40-3bdc-e247-daf9c...
3public-global-vessel-identity:v3.00[][][][{'vessel_id': '108c5510b-b6aa-9cf2-8b86-0598d...[{'id': '108c5510b-b6aa-9cf2-8b86-0598de546741...[{'reference': '108c5510b-b6aa-9cf2-8b86-0598d...
4public-global-vessel-identity:v3.00[][][][{'vessel_id': 'd2fbd05f5-57dd-1faa-c384-67a75...[{'id': 'd2fbd05f5-57dd-1faa-c384-67a75f27fc80...[{'reference': 'd2fbd05f5-57dd-1faa-c384-67a75...
\n", + "
" + ], + "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", + "2 public-global-vessel-identity:v3.0 0 \n", + "3 public-global-vessel-identity:v3.0 0 \n", + "4 public-global-vessel-identity:v3.0 0 \n", + "\n", + " registry_info \\\n", + "0 [] \n", + "1 [{'id': '4ef90bea19300c6a23f6ce627a80238b', 's... \n", + "2 [] \n", + "3 [] \n", + "4 [] \n", + "\n", + " registry_owners \\\n", + "0 [] \n", + "1 [{'name': 'ZHOUSHAN SHUNHANG OCEAN FISHERIES',... \n", + "2 [] \n", + "3 [] \n", + "4 [] \n", + "\n", + " registry_public_authorizations \\\n", + "0 [] \n", + "1 [{'date_from': 2017-01-04 00:00:00+00:00, 'dat... \n", + "2 [] \n", + "3 [] \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", + "\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", + "\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... " + ] + }, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "vessel_search_df.head()" + ] + }, + { + "cell_type": "markdown", + "id": "3b34b0b1-c631-42c0-8950-d87234e68e87", + "metadata": {}, + "source": [ + "**Note:** It is recommended to prioritize vessels that include both `registry_info` and `self_reported_info` (AIS), as this indicates a successful match between registry data and AIS information." + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "49b4c9fd-0d95-4259-a124-4e1f0193cd92", + "metadata": {}, + "outputs": [], + "source": [ + "vessel_search_ids = [\n", " self_reported_info.id\n", - " for vessel in vessel_search_result.data()\n", - " for self_reported_info in vessel.self_reported_info\n", + " for vessel_search_item in vessel_search_result.data()\n", + " if vessel_search_item.registry_info_total_records >= 1\n", + " for self_reported_info in vessel_search_item.self_reported_info\n", "]" ] }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 10, + "id": "9ecd48fb-11e3-45b6-ac50-f16b81f7f1b7", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['755a48dd4-4bee-4bcf-7b5f-9baea058fc7b',\n", + " '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f']" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "vessel_search_ids" + ] + }, + { + "cell_type": "markdown", + "id": "f72bc72f-8a94-425d-9a38-8dabc7947b05", + "metadata": {}, + "source": [ + "### Getting Details of Vessels Filtered by Vessel Searched IDs" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "19e6add8-e0a8-42e5-a2b9-8291026cf48d", + "metadata": {}, + "outputs": [], + "source": [ + "vessels_result = await gfw_client.vessels.get_vessels_by_ids(\n", + " ids=vessel_search_ids,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "6aded3f4-69c3-47ec-8a6a-4d672fc56356", + "metadata": {}, + "outputs": [], + "source": [ + "vessels_df = vessels_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "c131c32f-1cc1-4bf8-83d3-4d559153d150", + "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": [ + "vessels_df.info()" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "40c56dc8-09a0-48d5-9a93-fdca34815a27", + "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", + "
datasetregistry_info_total_recordsregistry_inforegistry_ownersregistry_public_authorizationscombined_sources_infoself_reported_info
0public-global-vessel-identity:v3.01[{'id': '4ef90bea19300c6a23f6ce627a80238b', 's...[{'name': 'ZHOUSHAN SHUNHANG OCEAN FISHERIES',...[{'date_from': 2017-01-04 00:00:00+00:00, 'dat...[{'vessel_id': '755a48dd4-4bee-4bcf-7b5f-9baea...[{'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b...
\n", + "
" + ], + "text/plain": [ + " dataset registry_info_total_records \\\n", + "0 public-global-vessel-identity:v3.0 1 \n", + "\n", + " registry_info \\\n", + "0 [{'id': '4ef90bea19300c6a23f6ce627a80238b', 's... \n", + "\n", + " registry_owners \\\n", + "0 [{'name': 'ZHOUSHAN SHUNHANG OCEAN FISHERIES',... \n", + "\n", + " registry_public_authorizations \\\n", + "0 [{'date_from': 2017-01-04 00:00:00+00:00, 'dat... \n", + "\n", + " combined_sources_info \\\n", + "0 [{'vessel_id': '755a48dd4-4bee-4bcf-7b5f-9baea... \n", + "\n", + " self_reported_info \n", + "0 [{'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b... " + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "vessels_df.head()" + ] + }, + { + "cell_type": "code", + "execution_count": 15, "id": "522a618d-140e-4d36-9e18-b71e81d1c40e", "metadata": { "colab": { @@ -220,15 +589,41 @@ "id": "522a618d-140e-4d36-9e18-b71e81d1c40e", "outputId": "ee9a5ca8-f994-4357-f748-d1140bb29f9a" }, + "outputs": [], + "source": [ + "vessel_self_reported_infos = [\n", + " self_reported_info\n", + " for vessel_item in vessels_result.data()\n", + " for self_reported_info in vessel_item.self_reported_info\n", + "]" + ] + }, + { + "cell_type": "code", + "execution_count": 16, + "id": "e35272d9-7758-4abc-bb24-a112647c8fc9", + "metadata": {}, + "outputs": [], + "source": [ + "vessel_ids = [\n", + " self_reported_info.id for self_reported_info in vessel_self_reported_infos\n", + "]" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "05a96294-7009-477f-9175-f2653d10b989", + "metadata": {}, "outputs": [ { "data": { "text/plain": [ - "['3312b30d6-65b6-1bdb-6a78-3f5eb3977e58',\n", - " '126221ace-e3b5-f4ed-6150-394809737c55']" + "['755a48dd4-4bee-4bcf-7b5f-9baea058fc7b',\n", + " '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f']" ] }, - "execution_count": 7, + "execution_count": 17, "metadata": {}, "output_type": "execute_result" } @@ -237,6 +632,256 @@ "vessel_ids" ] }, + { + "cell_type": "markdown", + "id": "ef5c4cd5-c8b0-440b-8177-67741714b574", + "metadata": {}, + "source": [ + "### Getting Insights Related to Fishing Events for the Vessel Searched" + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "89f02bda-8318-43e3-8b28-fa85d42772e9", + "metadata": {}, + "outputs": [], + "source": [ + "start_datetime = min(\n", + " [\n", + " self_reported_info.transmission_date_from\n", + " for self_reported_info in vessel_self_reported_infos\n", + " ]\n", + ")\n", + "start_date = start_datetime.date()" + ] + }, + { + "cell_type": "markdown", + "id": "4fee4e40-4ec0-406d-aa4e-3de9e6224c55", + "metadata": {}, + "source": [ + "**Important:** `start_date` must be on or after `January 1, 2020`" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "ba29290c-d0c2-4150-8650-7851cb4fe097", + "metadata": {}, + "outputs": [], + "source": [ + "start_date = max(start_date, datetime.date.fromisoformat(\"2020-01-01\"))" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "e2b49d3e-4317-4866-adcd-78e51662c89d", + "metadata": {}, + "outputs": [], + "source": [ + "end_datetime = max(\n", + " [\n", + " self_reported_info.transmission_date_to\n", + " for self_reported_info in vessel_self_reported_infos\n", + " ]\n", + ")\n", + "end_date = end_datetime.date()" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "629f5ca9-ff9f-4d09-bfe8-e01b7af6f6c3", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "(datetime.date(2020, 1, 1), datetime.date(2026, 1, 4))" + ] + }, + "execution_count": 21, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "start_date, end_date" + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "2d331aeb-370e-4039-aa46-75a10e2d0a18", + "metadata": {}, + "outputs": [], + "source": [ + "dataset_id = \"public-global-vessel-identity:latest\"\n", + "dataset_ids_vessel_ids = [\n", + " {\"dataset_id\": dataset_id, \"vessel_id\": vessel_id} for vessel_id in vessel_ids\n", + "]" + ] + }, + { + "cell_type": "code", + "execution_count": 23, + "id": "cd5725f5-57ca-4620-9946-d3cf4ea153b1", + "metadata": {}, + "outputs": [], + "source": [ + "insights_result = await gfw_client.insights.get_vessel_insights(\n", + " includes=[\"FISHING\"],\n", + " start_date=start_date,\n", + " end_date=end_date,\n", + " vessels=dataset_ids_vessel_ids,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 24, + "id": "15f1a28c-215d-4cef-b62e-84f029fecfd1", + "metadata": {}, + "outputs": [], + "source": [ + "insights_df = insights_result.df()" + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "cca3b40f-8f19-4715-a91e-0e86c2d2588e", + "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": 26, + "id": "be8dd7ac-b8d7-4c3d-9fe6-157831a8a7b9", + "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", + "
periodvessel_ids_without_identitygapcoverageapparent_fishingvessel_identity
0{'start_date': 2020-01-01, 'end_date': 2026-01...NoneNoneNone{'datasets': ['public-global-fishing-events:v3...None
\n", + "
" + ], + "text/plain": [ + " period \\\n", + "0 {'start_date': 2020-01-01, 'end_date': 2026-01... \n", + "\n", + " vessel_ids_without_identity gap coverage \\\n", + "0 None None None \n", + "\n", + " apparent_fishing vessel_identity \n", + "0 {'datasets': ['public-global-fishing-events:v3... None " + ] + }, + "execution_count": 26, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "insights_df.head()" + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "7eb5f9e3-57b8-44b7-bf5e-3091cb9c0033", + "metadata": {}, + "outputs": [], + "source": [ + "insights_data = insights_result.data()" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "53704e62-9e21-4182-bab6-058e4e297fe6", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'events': 398,\n", + " 'events_gap_off': None,\n", + " 'events_in_rfmo_without_known_authorization': 144,\n", + " 'events_in_no_take_mpas': 0}" + ] + }, + "execution_count": 28, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "dict(insights_data.apparent_fishing.period_selected_counters)" + ] + }, { "cell_type": "markdown", "id": "38d7148a-23dc-4a7b-8aa2-27a79f49bea9", @@ -244,12 +889,12 @@ "id": "38d7148a-23dc-4a7b-8aa2-27a79f49bea9" }, "source": [ - "### Getting Fishing Events for the Searched Vessels" + "### Getting Fishing Events for the Vessels Searched" ] }, { "cell_type": "code", - "execution_count": 8, + "execution_count": 29, "id": "b078ce74-f2d1-4ec3-a163-b3961407e497", "metadata": { "id": "b078ce74-f2d1-4ec3-a163-b3961407e497" @@ -258,15 +903,15 @@ "source": [ "events_result = await gfw_client.events.get_all_events(\n", " datasets=[\"public-global-fishing-events:latest\"],\n", - " start_date=\"2024-03-01\",\n", - " end_date=\"2025-03-31\",\n", + " start_date=start_date,\n", + " end_date=end_date,\n", " vessels=vessel_ids,\n", ")" ] }, { "cell_type": "code", - "execution_count": 9, + "execution_count": 30, "id": "8b1c4289-5896-4590-8d6e-7405bb0037f8", "metadata": { "id": "8b1c4289-5896-4590-8d6e-7405bb0037f8" @@ -278,7 +923,7 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": 31, "id": "8a1f2985-e849-4e7c-8a7e-77afcba17764", "metadata": { "colab": { @@ -293,26 +938,26 @@ "output_type": "stream", "text": [ "\n", - "RangeIndex: 3 entries, 0 to 2\n", + "RangeIndex: 398 entries, 0 to 397\n", "Data columns (total 14 columns):\n", " # Column Non-Null Count Dtype \n", "--- ------ -------------- ----- \n", - " 0 start 3 non-null datetime64[ns, UTC]\n", - " 1 end 3 non-null datetime64[ns, UTC]\n", - " 2 id 3 non-null object \n", - " 3 type 3 non-null object \n", - " 4 position 3 non-null object \n", - " 5 regions 3 non-null object \n", - " 6 bounding_box 3 non-null object \n", - " 7 distances 3 non-null object \n", - " 8 vessel 3 non-null object \n", + " 0 start 398 non-null datetime64[ns, UTC]\n", + " 1 end 398 non-null datetime64[ns, UTC]\n", + " 2 id 398 non-null object \n", + " 3 type 398 non-null object \n", + " 4 position 398 non-null object \n", + " 5 regions 398 non-null object \n", + " 6 bounding_box 398 non-null object \n", + " 7 distances 398 non-null object \n", + " 8 vessel 398 non-null object \n", " 9 encounter 0 non-null object \n", - " 10 fishing 3 non-null object \n", + " 10 fishing 398 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: 468.0+ bytes\n" + "memory usage: 43.7+ KB\n" ] } ], @@ -322,7 +967,7 @@ }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 32, "id": "ff424bc9-bb00-4bc6-a8e3-ee01346786c8", "metadata": { "colab": { @@ -373,51 +1018,85 @@ " \n", " \n", " 0\n", - " 2024-03-02 07:20:58+00:00\n", - " 2024-03-02 16:31:16+00:00\n", - " b45f90c9d26b298d740d981ff3989e9f\n", + " 2025-12-21 22:54:19+00:00\n", + " 2025-12-22 01:59:26+00:00\n", + " 20722d55b7a106978e2b55e65f7affa6\n", " fishing\n", - " {'lat': 41.4282, 'lon': -69.0376}\n", - " {'mpa': [], 'eez': ['8456'], 'rfmo': ['NAMMCO'...\n", - " [-69.09002, 41.356445, -69.013173, 41.455082]\n", - " {'start_distance_from_shore_km': 74.0, 'end_di...\n", - " {'id': '3312b30d6-65b6-1bdb-6a78-3f5eb3977e58'...\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", " None\n", - " {'total_distance_km': 20.67347342859376, 'aver...\n", + " {'total_distance_km': 1.553408717842079, 'aver...\n", " None\n", " None\n", " None\n", " \n", " \n", " 1\n", - " 2024-04-08 22:29:41+00:00\n", - " 2024-04-09 01:56:10+00:00\n", - " f126f405f67d32f6488dbff9c828ca86\n", + " 2020-05-29 15:38:07+00:00\n", + " 2020-05-29 19:22:03+00:00\n", + " aa6f570aee327010bd4714aa6e459d08\n", " fishing\n", - " {'lat': 40.9922, 'lon': -68.2989}\n", - " {'mpa': [], 'eez': ['8456'], 'rfmo': ['NAMMCO'...\n", - " [-68.444835, 40.96636, -68.237482, 41.062727]\n", - " {'start_distance_from_shore_km': 133.0, 'end_d...\n", - " {'id': '3312b30d6-65b6-1bdb-6a78-3f5eb3977e58'...\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", + " {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'...\n", " None\n", - " {'total_distance_km': 22.543354447253645, 'ave...\n", + " {'total_distance_km': 3.2539329459390007, 'ave...\n", " None\n", " None\n", " None\n", " \n", " \n", " 2\n", - " 2024-04-06 06:24:38+00:00\n", - " 2024-04-06 10:44:37+00:00\n", - " 5a78695b7c9e56e511c40d058dd07e20\n", + " 2025-12-31 23:00:02+00:00\n", + " 2026-01-01 07:57:31+00:00\n", + " 82ab07bcb2f0881dbdc2bea176f4d0eb\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", + " None\n", + " {'total_distance_km': 5.18218418253593, 'avera...\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", + " 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", + " {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'...\n", + " None\n", + " {'total_distance_km': 13.20298689870354, '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", " fishing\n", - " {'lat': 41.2956, 'lon': -69.0377}\n", - " {'mpa': [], 'eez': ['8456'], 'rfmo': ['ACAP', ...\n", - " [-69.116493, 41.278087, -69.014402, 41.368413]\n", - " {'start_distance_from_shore_km': 71.0, 'end_di...\n", - " {'id': '3312b30d6-65b6-1bdb-6a78-3f5eb3977e58'...\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", + " {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'...\n", " None\n", - " {'total_distance_km': 16.614674434708487, 'ave...\n", + " {'total_distance_km': 4.430991184550807, 'aver...\n", " None\n", " None\n", " None\n", @@ -428,52 +1107,70 @@ ], "text/plain": [ " start end \\\n", - "0 2024-03-02 07:20:58+00:00 2024-03-02 16:31:16+00:00 \n", - "1 2024-04-08 22:29:41+00:00 2024-04-09 01:56:10+00:00 \n", - "2 2024-04-06 06:24:38+00:00 2024-04-06 10:44:37+00:00 \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", "\n", " id type \\\n", - "0 b45f90c9d26b298d740d981ff3989e9f fishing \n", - "1 f126f405f67d32f6488dbff9c828ca86 fishing \n", - "2 5a78695b7c9e56e511c40d058dd07e20 fishing \n", + "0 20722d55b7a106978e2b55e65f7affa6 fishing \n", + "1 aa6f570aee327010bd4714aa6e459d08 fishing \n", + "2 82ab07bcb2f0881dbdc2bea176f4d0eb fishing \n", + "3 634e0f958283315e9850e1523e6f7a88 fishing \n", + "4 1c4ef3bc92b7a763c5f3b04d3a1a0779 fishing \n", "\n", - " position \\\n", - "0 {'lat': 41.4282, 'lon': -69.0376} \n", - "1 {'lat': 40.9922, 'lon': -68.2989} \n", - "2 {'lat': 41.2956, 'lon': -69.0377} \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", "\n", " regions \\\n", - "0 {'mpa': [], 'eez': ['8456'], 'rfmo': ['NAMMCO'... \n", - "1 {'mpa': [], 'eez': ['8456'], 'rfmo': ['NAMMCO'... \n", - "2 {'mpa': [], 'eez': ['8456'], 'rfmo': ['ACAP', ... \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", "\n", - " bounding_box \\\n", - "0 [-69.09002, 41.356445, -69.013173, 41.455082] \n", - "1 [-68.444835, 40.96636, -68.237482, 41.062727] \n", - "2 [-69.116493, 41.278087, -69.014402, 41.368413] \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", "\n", " distances \\\n", - "0 {'start_distance_from_shore_km': 74.0, 'end_di... \n", - "1 {'start_distance_from_shore_km': 133.0, 'end_d... \n", - "2 {'start_distance_from_shore_km': 71.0, 'end_di... \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", "\n", " vessel encounter \\\n", - "0 {'id': '3312b30d6-65b6-1bdb-6a78-3f5eb3977e58'... None \n", - "1 {'id': '3312b30d6-65b6-1bdb-6a78-3f5eb3977e58'... None \n", - "2 {'id': '3312b30d6-65b6-1bdb-6a78-3f5eb3977e58'... None \n", + "0 {'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b'... None \n", + "1 {'id': '3dad49b0b-b2e0-9347-0c4c-e39fea560f9f'... None \n", + "2 {'id': '755a48dd4-4bee-4bcf-7b5f-9baea058fc7b'... 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': 20.67347342859376, 'aver... None None \n", - "1 {'total_distance_km': 22.543354447253645, 'ave... None None \n", - "2 {'total_distance_km': 16.614674434708487, 'ave... None None \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", "\n", " port_visit \n", "0 None \n", "1 None \n", - "2 None " + "2 None \n", + "3 None \n", + "4 None " ] }, - "execution_count": 11, + "execution_count": 32, "metadata": {}, "output_type": "execute_result" } diff --git a/notebooks/usage-guides/4wings-api.ipynb b/notebooks/usage-guides/4wings-api.ipynb index db1850b..d825bef 100644 --- a/notebooks/usage-guides/4wings-api.ipynb +++ b/notebooks/usage-guides/4wings-api.ipynb @@ -56,7 +56,7 @@ "id": "57109889-5f3f-45b3-a594-2f82b94bcadb" }, "source": [ - "Before using the `gfw-api-python-client`, you need to obtain an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)" + "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)." ] }, { @@ -173,7 +173,7 @@ "fishing_effort_report_result = await gfw_client.fourwings.create_fishing_effort_report(\n", " spatial_resolution=\"LOW\",\n", " temporal_resolution=\"MONTHLY\",\n", - " group_by=\"GEARTYPE\",\n", + " group_by=\"FLAG\",\n", " start_date=\"2022-01-01\",\n", " end_date=\"2022-05-01\",\n", " region={\n", @@ -220,7 +220,7 @@ { "data": { "text/plain": [ - "('2022-04', 'fishing', 2.705, 1, 52.0, 155.2)" + "('2022-03', 'RUS', 7.109166666666667, 3, 75.8, 44.0)" ] }, "execution_count": 8, @@ -231,7 +231,7 @@ "source": [ "(\n", " fishing_effort_report_item.date,\n", - " fishing_effort_report_item.gear_type,\n", + " fishing_effort_report_item.flag,\n", " fishing_effort_report_item.hours,\n", " fishing_effort_report_item.vessel_ids,\n", " fishing_effort_report_item.lat,\n", @@ -309,12 +309,12 @@ " \n", " \n", " 0\n", - " 2022-01\n", + " 2022-03\n", " None\n", + " RUS\n", " None\n", - " trawlers\n", - " 2.848333\n", - " 1\n", + " 3.416944\n", + " 2\n", " None\n", " None\n", " None\n", @@ -327,17 +327,17 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 58.5\n", - " 149.2\n", + " 75.6\n", + " 50.3\n", " \n", " \n", " 1\n", - " 2022-03\n", + " 2022-02\n", " None\n", + " RUS\n", " None\n", - " fishing\n", - " 1.305710\n", - " 1\n", + " 2.144444\n", + " 3\n", " None\n", " None\n", " None\n", @@ -350,17 +350,17 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 55.6\n", - " 153.8\n", + " 51.4\n", + " 155.4\n", " \n", " \n", " 2\n", - " 2022-02\n", + " 2022-03\n", " None\n", + " RUS\n", " None\n", - " trawlers\n", - " 20.537500\n", - " 13\n", + " 5.436944\n", + " 2\n", " None\n", " None\n", " None\n", @@ -373,17 +373,17 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 54.9\n", - " 152.7\n", + " 58.6\n", + " 155.8\n", " \n", " \n", " 3\n", - " 2022-02\n", + " 2022-01\n", " None\n", + " RUS\n", " None\n", - " trawlers\n", - " 5.952222\n", - " 3\n", + " 4.435556\n", + " 1\n", " None\n", " None\n", " None\n", @@ -396,16 +396,16 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 56.1\n", - " 144.4\n", + " 45.7\n", + " 149.8\n", " \n", " \n", " 4\n", - " 2022-01\n", + " 2022-03\n", " None\n", + " RUS\n", " None\n", - " trawlers\n", - " 1.951944\n", + " 0.362778\n", " 1\n", " None\n", " None\n", @@ -419,20 +419,20 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 51.7\n", - " 154.1\n", + " 46.7\n", + " 141.9\n", " \n", " \n", "\n", "" ], "text/plain": [ - " date detections flag gear_type hours vessel_ids vessel_id \\\n", - "0 2022-01 None None trawlers 2.848333 1 None \n", - "1 2022-03 None None fishing 1.305710 1 None \n", - "2 2022-02 None None trawlers 20.537500 13 None \n", - "3 2022-02 None None trawlers 5.952222 3 None \n", - "4 2022-01 None None trawlers 1.951944 1 None \n", + " 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", "\n", " vessel_type entry_timestamp exit_timestamp first_transmission_date \\\n", "0 None None None None \n", @@ -449,11 +449,11 @@ "4 None None None None None \n", "\n", " report_dataset ship_name lat lon \n", - "0 public-global-fishing-effort:v3.0 None 58.5 149.2 \n", - "1 public-global-fishing-effort:v3.0 None 55.6 153.8 \n", - "2 public-global-fishing-effort:v3.0 None 54.9 152.7 \n", - "3 public-global-fishing-effort:v3.0 None 56.1 144.4 \n", - "4 public-global-fishing-effort:v3.0 None 51.7 154.1 " + "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 " ] }, "execution_count": 10, @@ -499,7 +499,7 @@ "ais_presence_report_result = await gfw_client.fourwings.create_ais_presence_report(\n", " spatial_resolution=\"LOW\",\n", " temporal_resolution=\"MONTHLY\",\n", - " group_by=\"GEARTYPE\",\n", + " group_by=\"FLAG\",\n", " start_date=\"2022-01-01\",\n", " end_date=\"2022-05-01\",\n", " region={\n", @@ -546,7 +546,7 @@ { "data": { "text/plain": [ - "('2022-04', 9.0, 8, 50.4, 160.7)" + "('2022-03', 'RUS', 1.0, 1, 52.1, 153.2)" ] }, "execution_count": 14, @@ -557,6 +557,7 @@ "source": [ "(\n", " ais_presence_report_item.date,\n", + " ais_presence_report_item.flag,\n", " ais_presence_report_item.hours,\n", " ais_presence_report_item.vessel_ids,\n", " ais_presence_report_item.lat,\n", @@ -634,12 +635,12 @@ " \n", " \n", " 0\n", - " 2022-02\n", + " 2022-04\n", " None\n", + " PAN\n", " None\n", - " \n", - " 4.0\n", - " 4\n", + " 3.0\n", + " 2\n", " None\n", " None\n", " None\n", @@ -652,16 +653,16 @@ " None\n", " public-global-presence:v3.0\n", " None\n", - " 45.0\n", - " 154.3\n", + " 47.8\n", + " 154.1\n", " \n", " \n", " 1\n", - " 2022-03\n", + " 2022-02\n", " None\n", + " RUS\n", " None\n", - " \n", - " 1.0\n", + " 4.0\n", " 1\n", " None\n", " None\n", @@ -675,17 +676,17 @@ " None\n", " public-global-presence:v3.0\n", " None\n", - " 49.8\n", - " 147.8\n", + " 77.6\n", + " 70.6\n", " \n", " \n", " 2\n", - " 2022-03\n", + " 2022-02\n", " None\n", + " RUS\n", " None\n", - " \n", - " 2.0\n", - " 2\n", + " 1.0\n", + " 1\n", " None\n", " None\n", " None\n", @@ -698,17 +699,17 @@ " None\n", " public-global-presence:v3.0\n", " None\n", - " 69.4\n", - " 45.4\n", + " 75.0\n", + " 159.2\n", " \n", " \n", " 3\n", - " 2022-02\n", + " 2022-03\n", " None\n", + " RUS\n", " None\n", - " \n", - " 1.0\n", - " 1\n", + " 2.0\n", + " 2\n", " None\n", " None\n", " None\n", @@ -721,17 +722,17 @@ " None\n", " public-global-presence:v3.0\n", " None\n", - " 54.3\n", - " 145.3\n", + " 68.4\n", + " 49.0\n", " \n", " \n", " 4\n", - " 2022-03\n", + " 2022-02\n", " None\n", + " PAN\n", " None\n", - " \n", - " 13.0\n", - " 10\n", + " 1.0\n", + " 1\n", " None\n", " None\n", " None\n", @@ -744,27 +745,27 @@ " None\n", " public-global-presence:v3.0\n", " None\n", - " 66.3\n", - " 40.8\n", + " 50.0\n", + " 157.0\n", " \n", " \n", "\n", "" ], "text/plain": [ - " date detections flag gear_type hours vessel_ids vessel_id \\\n", - "0 2022-02 None None 4.0 4 None \n", - "1 2022-03 None None 1.0 1 None \n", - "2 2022-03 None None 2.0 2 None \n", - "3 2022-02 None None 1.0 1 None \n", - "4 2022-03 None None 13.0 10 None \n", + " date detections flag gear_type hours vessel_ids vessel_id vessel_type \\\n", + "0 2022-04 None PAN None 3.0 2 None None \n", + "1 2022-02 None RUS None 4.0 1 None None \n", + "2 2022-02 None RUS None 1.0 1 None None \n", + "3 2022-03 None RUS None 2.0 2 None None \n", + "4 2022-02 None PAN None 1.0 1 None None \n", "\n", - " vessel_type entry_timestamp exit_timestamp first_transmission_date \\\n", - "0 None None None None \n", - "1 None None None None \n", - "2 None None None None \n", - "3 None None None None \n", - "4 None None None None \n", + " entry_timestamp exit_timestamp first_transmission_date \\\n", + "0 None None None \n", + "1 None None None \n", + "2 None None None \n", + "3 None None None \n", + "4 None None None \n", "\n", " last_transmission_date imo mmsi call_sign dataset \\\n", "0 None None None None None \n", @@ -774,11 +775,11 @@ "4 None None None None None \n", "\n", " report_dataset ship_name lat lon \n", - "0 public-global-presence:v3.0 None 45.0 154.3 \n", - "1 public-global-presence:v3.0 None 49.8 147.8 \n", - "2 public-global-presence:v3.0 None 69.4 45.4 \n", - "3 public-global-presence:v3.0 None 54.3 145.3 \n", - "4 public-global-presence:v3.0 None 66.3 40.8 " + "0 public-global-presence:v3.0 None 47.8 154.1 \n", + "1 public-global-presence:v3.0 None 77.6 70.6 \n", + "2 public-global-presence:v3.0 None 75.0 159.2 \n", + "3 public-global-presence:v3.0 None 68.4 49.0 \n", + "4 public-global-presence:v3.0 None 50.0 157.0 " ] }, "execution_count": 16, @@ -824,7 +825,7 @@ "sar_presence_report_result = await gfw_client.fourwings.create_sar_presence_report(\n", " spatial_resolution=\"LOW\",\n", " temporal_resolution=\"MONTHLY\",\n", - " group_by=\"GEARTYPE\",\n", + " group_by=\"FLAG\",\n", " start_date=\"2022-01-01\",\n", " end_date=\"2022-05-01\",\n", " region={\n", @@ -871,7 +872,7 @@ { "data": { "text/plain": [ - "('2022-04', 1, 1, 46.6, 142.6)" + "('2022-04', '', 1, 1, 46.6, 142.6)" ] }, "execution_count": 20, @@ -882,6 +883,7 @@ "source": [ "(\n", " sar_presence_report_item.date,\n", + " sar_presence_report_item.flag,\n", " sar_presence_report_item.detections,\n", " sar_presence_report_item.vessel_ids,\n", " sar_presence_report_item.lat,\n", @@ -959,11 +961,11 @@ " \n", " \n", " 0\n", - " 2022-02\n", + " 2022-01\n", " 1\n", - " None\n", " \n", " None\n", + " None\n", " 1\n", " None\n", " None\n", @@ -977,17 +979,17 @@ " None\n", " public-global-sar-presence:v3.0\n", " None\n", - " 46.3\n", - " 142.4\n", + " 44.6\n", + " 38.0\n", " \n", " \n", " 1\n", - " 2022-04\n", - " 1\n", + " 2022-03\n", + " 3\n", + " RUS\n", " None\n", - " other\n", " None\n", - " 1\n", + " 3\n", " None\n", " None\n", " None\n", @@ -1000,15 +1002,15 @@ " None\n", " public-global-sar-presence:v3.0\n", " None\n", - " 46.0\n", - " 143.7\n", + " 46.7\n", + " 141.8\n", " \n", " \n", " 2\n", - " 2022-03\n", + " 2022-04\n", " 1\n", + " RUS\n", " None\n", - " fishing\n", " None\n", " 1\n", " None\n", @@ -1023,17 +1025,17 @@ " None\n", " public-global-sar-presence:v3.0\n", " None\n", - " 46.7\n", - " 141.7\n", + " 46.8\n", + " 141.4\n", " \n", " \n", " 3\n", - " 2022-03\n", - " 1\n", + " 2022-02\n", + " 2\n", + " GRC\n", " None\n", - " \n", " None\n", - " 1\n", + " 2\n", " None\n", " None\n", " None\n", @@ -1046,15 +1048,15 @@ " None\n", " public-global-sar-presence:v3.0\n", " None\n", - " 49.1\n", - " 144.4\n", + " 44.2\n", + " 37.4\n", " \n", " \n", " 4\n", - " 2022-03\n", + " 2022-01\n", " 1\n", + " MLT\n", " None\n", - " other\n", " None\n", " 1\n", " None\n", @@ -1069,27 +1071,27 @@ " None\n", " public-global-sar-presence:v3.0\n", " None\n", - " 49.3\n", - " 141.8\n", + " 43.8\n", + " 38.7\n", " \n", " \n", "\n", "" ], "text/plain": [ - " date detections flag gear_type hours vessel_ids vessel_id \\\n", - "0 2022-02 1 None None 1 None \n", - "1 2022-04 1 None other None 1 None \n", - "2 2022-03 1 None fishing None 1 None \n", - "3 2022-03 1 None None 1 None \n", - "4 2022-03 1 None other None 1 None \n", + " 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", "\n", - " vessel_type entry_timestamp exit_timestamp first_transmission_date \\\n", - "0 None None None None \n", - "1 None None None None \n", - "2 None None None None \n", - "3 None None None None \n", - "4 None None None None \n", + " entry_timestamp exit_timestamp first_transmission_date \\\n", + "0 None None None \n", + "1 None None None \n", + "2 None None None \n", + "3 None None None \n", + "4 None None None \n", "\n", " last_transmission_date imo mmsi call_sign dataset \\\n", "0 None None None None None \n", @@ -1099,11 +1101,11 @@ "4 None None None None None \n", "\n", " report_dataset ship_name lat lon \n", - "0 public-global-sar-presence:v3.0 None 46.3 142.4 \n", - "1 public-global-sar-presence:v3.0 None 46.0 143.7 \n", - "2 public-global-sar-presence:v3.0 None 46.7 141.7 \n", - "3 public-global-sar-presence:v3.0 None 49.1 144.4 \n", - "4 public-global-sar-presence:v3.0 None 49.3 141.8 " + "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 " ] }, "execution_count": 22, @@ -1133,6 +1135,14 @@ "Generates a report for any [supported datasets](https://globalfishingwatch.org/our-apis/documentation#supported-datasets), using fully customizable parameters. [Please check the data caveats here](https://globalfishingwatch.org/our-apis/documentation#data-caveat)." ] }, + { + "cell_type": "markdown", + "id": "ef93b16e-2374-44b3-84f1-afe681df336b", + "metadata": {}, + "source": [ + "**Note:** AIS vessel presence (i.e., `\"public-global-sar-presence:latest\"` dataset) does **not** support `\"GEARTYPE\"` or `\"FLAGANDGEARTYPE\"` as `group_by` criteria." + ] + }, { "cell_type": "code", "execution_count": 23, @@ -1145,7 +1155,7 @@ "report_result = await gfw_client.fourwings.create_report(\n", " spatial_resolution=\"LOW\",\n", " temporal_resolution=\"MONTHLY\",\n", - " group_by=\"GEARTYPE\",\n", + " group_by=\"FLAG\",\n", " datasets=[\"public-global-fishing-effort:latest\"],\n", " start_date=\"2022-01-01\",\n", " end_date=\"2022-05-01\",\n", @@ -1205,7 +1215,7 @@ { "data": { "text/plain": [ - "('2022-04', 'fishing', 2.705, 1, 52.0, 155.2)" + "('2022-03', 'RUS', 7.109166666666667, 3, 75.8, 44.0)" ] }, "execution_count": 26, @@ -1216,7 +1226,7 @@ "source": [ "(\n", " report_item.date,\n", - " report_item.gear_type,\n", + " report_item.flag,\n", " report_item.hours,\n", " report_item.vessel_ids,\n", " report_item.lat,\n", @@ -1305,12 +1315,12 @@ " \n", " \n", " 0\n", - " 2022-01\n", + " 2022-03\n", " None\n", + " RUS\n", " None\n", - " trawlers\n", - " 2.848333\n", - " 1\n", + " 3.416944\n", + " 2\n", " None\n", " None\n", " None\n", @@ -1323,17 +1333,17 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 58.5\n", - " 149.2\n", + " 75.6\n", + " 50.3\n", " \n", " \n", " 1\n", - " 2022-03\n", + " 2022-02\n", " None\n", + " RUS\n", " None\n", - " fishing\n", - " 1.305710\n", - " 1\n", + " 2.144444\n", + " 3\n", " None\n", " None\n", " None\n", @@ -1346,17 +1356,17 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 55.6\n", - " 153.8\n", + " 51.4\n", + " 155.4\n", " \n", " \n", " 2\n", - " 2022-02\n", + " 2022-03\n", " None\n", + " RUS\n", " None\n", - " trawlers\n", - " 20.537500\n", - " 13\n", + " 5.436944\n", + " 2\n", " None\n", " None\n", " None\n", @@ -1369,17 +1379,17 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 54.9\n", - " 152.7\n", + " 58.6\n", + " 155.8\n", " \n", " \n", " 3\n", - " 2022-02\n", + " 2022-01\n", " None\n", + " RUS\n", " None\n", - " trawlers\n", - " 5.952222\n", - " 3\n", + " 4.435556\n", + " 1\n", " None\n", " None\n", " None\n", @@ -1392,16 +1402,16 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 56.1\n", - " 144.4\n", + " 45.7\n", + " 149.8\n", " \n", " \n", " 4\n", - " 2022-01\n", + " 2022-03\n", " None\n", + " RUS\n", " None\n", - " trawlers\n", - " 1.951944\n", + " 0.362778\n", " 1\n", " None\n", " None\n", @@ -1415,20 +1425,20 @@ " None\n", " public-global-fishing-effort:v3.0\n", " None\n", - " 51.7\n", - " 154.1\n", + " 46.7\n", + " 141.9\n", " \n", " \n", "\n", "" ], "text/plain": [ - " date detections flag gear_type hours vessel_ids vessel_id \\\n", - "0 2022-01 None None trawlers 2.848333 1 None \n", - "1 2022-03 None None fishing 1.305710 1 None \n", - "2 2022-02 None None trawlers 20.537500 13 None \n", - "3 2022-02 None None trawlers 5.952222 3 None \n", - "4 2022-01 None None trawlers 1.951944 1 None \n", + " 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", "\n", " vessel_type entry_timestamp exit_timestamp first_transmission_date \\\n", "0 None None None None \n", @@ -1445,11 +1455,11 @@ "4 None None None None None \n", "\n", " report_dataset ship_name lat lon \n", - "0 public-global-fishing-effort:v3.0 None 58.5 149.2 \n", - "1 public-global-fishing-effort:v3.0 None 55.6 153.8 \n", - "2 public-global-fishing-effort:v3.0 None 54.9 152.7 \n", - "3 public-global-fishing-effort:v3.0 None 56.1 144.4 \n", - "4 public-global-fishing-effort:v3.0 None 51.7 154.1 " + "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 " ] }, "execution_count": 28, diff --git a/notebooks/usage-guides/datasets-api.ipynb b/notebooks/usage-guides/datasets-api.ipynb index 73d0fa9..41f53ea 100644 --- a/notebooks/usage-guides/datasets-api.ipynb +++ b/notebooks/usage-guides/datasets-api.ipynb @@ -36,7 +36,7 @@ "id": "0805b620-fb90-4f78-b4eb-79fb3bf5d878", "metadata": {}, "source": [ - "See the [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." + "**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." ] }, { @@ -56,7 +56,7 @@ "id": "a5b0d532-a373-4082-b860-3ad9ebc90a45" }, "source": [ - "Before using the `gfw-api-python-client`, you need to obtain an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)" + "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)." ] }, { diff --git a/notebooks/usage-guides/events-api.ipynb b/notebooks/usage-guides/events-api.ipynb index f8ade5a..0893d10 100644 --- a/notebooks/usage-guides/events-api.ipynb +++ b/notebooks/usage-guides/events-api.ipynb @@ -36,7 +36,7 @@ "id": "ac3ebead-45de-4287-bbd0-7c62d5e71b3a", "metadata": {}, "source": [ - "See the [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." + "**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." ] }, { @@ -56,7 +56,7 @@ "id": "57109889-5f3f-45b3-a594-2f82b94bcadb" }, "source": [ - "Before using the `gfw-api-python-client`, you need to obtain an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)" + "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)." ] }, { diff --git a/notebooks/usage-guides/insights-api.ipynb b/notebooks/usage-guides/insights-api.ipynb index 84a4629..790a793 100644 --- a/notebooks/usage-guides/insights-api.ipynb +++ b/notebooks/usage-guides/insights-api.ipynb @@ -36,7 +36,7 @@ "id": "d1d62e3b-fc42-422a-bb7d-2ccc927ba494", "metadata": {}, "source": [ - "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 [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) page 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 [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." ] }, { @@ -56,7 +56,7 @@ "id": "57109889-5f3f-45b3-a594-2f82b94bcadb" }, "source": [ - "Before using the `gfw-api-python-client`, you need to obtain an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)" + "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)." ] }, { @@ -157,6 +157,14 @@ "## Getting Insights by Vessel (`get_vessel_insights`)" ] }, + { + "cell_type": "markdown", + "id": "ec5549cf-873a-4f34-9dd5-fd651ff85ef5", + "metadata": {}, + "source": [ + "**Important:** `start_date` must be on or after `January 1, 2020`" + ] + }, { "cell_type": "code", "execution_count": 5, diff --git a/notebooks/usage-guides/references-data-api.ipynb b/notebooks/usage-guides/references-data-api.ipynb index 1827ea3..49fa4c2 100644 --- a/notebooks/usage-guides/references-data-api.ipynb +++ b/notebooks/usage-guides/references-data-api.ipynb @@ -36,7 +36,7 @@ "id": "c777748f-4bf0-4529-8361-46841cf4ea26", "metadata": {}, "source": [ - "See the [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." + "**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." ] }, { @@ -56,7 +56,7 @@ "id": "cda8a081-5851-4926-adc4-fe09a82b6221" }, "source": [ - "Before using the `gfw-api-python-client`, you need to obtain an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)" + "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)." ] }, { diff --git a/notebooks/usage-guides/vessels-api.ipynb b/notebooks/usage-guides/vessels-api.ipynb index d1302cd..6915924 100644 --- a/notebooks/usage-guides/vessels-api.ipynb +++ b/notebooks/usage-guides/vessels-api.ipynb @@ -36,7 +36,7 @@ "id": "fa8109d3-42f9-4ad2-a734-5c62ff41eb72", "metadata": {}, "source": [ - "See the [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." + "**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." ] }, { @@ -56,7 +56,7 @@ "id": "57109889-5f3f-45b3-a594-2f82b94bcadb" }, "source": [ - "Before using the `gfw-api-python-client`, you need to obtain an API access token from the [Global Fishing Watch API portal](https://globalfishingwatch.org/our-apis/tokens)" + "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)." ] }, { @@ -222,7 +222,7 @@ { "data": { "text/plain": [ - "('public-global-vessel-identity:v3.0', 'bae8f325c-cf0a-01fe-6d1a-9a275588d4ff')" + "('public-global-vessel-identity:v3.0', 'c54923e64-46f3-9338-9dcb-ff09724077a3')" ] }, "execution_count": 8, @@ -308,9 +308,9 @@ " []\n", " []\n", " None\n", - " [{'vessel_id': 'c54923e64-46f3-9338-9dcb-ff097...\n", - " [{'id': 'c54923e64-46f3-9338-9dcb-ff09724077a3...\n", - " [{'reference': 'c54923e64-46f3-9338-9dcb-ff097...\n", + " [{'vessel_id': 'bae8f325c-cf0a-01fe-6d1a-9a275...\n", + " [{'id': 'bae8f325c-cf0a-01fe-6d1a-9a275588d4ff...\n", + " [{'reference': 'bae8f325c-cf0a-01fe-6d1a-9a275...\n", " \n", " \n", " 1\n", @@ -319,9 +319,9 @@ " []\n", " []\n", " None\n", - " [{'vessel_id': 'bae8f325c-cf0a-01fe-6d1a-9a275...\n", - " [{'id': 'bae8f325c-cf0a-01fe-6d1a-9a275588d4ff...\n", - " [{'reference': 'bae8f325c-cf0a-01fe-6d1a-9a275...\n", + " [{'vessel_id': 'c54923e64-46f3-9338-9dcb-ff097...\n", + " [{'id': 'c54923e64-46f3-9338-9dcb-ff09724077a3...\n", + " [{'reference': 'c54923e64-46f3-9338-9dcb-ff097...\n", " \n", " \n", "\n", @@ -337,16 +337,16 @@ "1 [] [] None \n", "\n", " combined_sources_info \\\n", - "0 [{'vessel_id': 'c54923e64-46f3-9338-9dcb-ff097... \n", - "1 [{'vessel_id': 'bae8f325c-cf0a-01fe-6d1a-9a275... \n", + "0 [{'vessel_id': 'bae8f325c-cf0a-01fe-6d1a-9a275... \n", + "1 [{'vessel_id': 'c54923e64-46f3-9338-9dcb-ff097... \n", "\n", " self_reported_info \\\n", - "0 [{'id': 'c54923e64-46f3-9338-9dcb-ff09724077a3... \n", - "1 [{'id': 'bae8f325c-cf0a-01fe-6d1a-9a275588d4ff... \n", + "0 [{'id': 'bae8f325c-cf0a-01fe-6d1a-9a275588d4ff... \n", + "1 [{'id': 'c54923e64-46f3-9338-9dcb-ff09724077a3... \n", "\n", " matchCriteria \n", - "0 [{'reference': 'c54923e64-46f3-9338-9dcb-ff097... \n", - "1 [{'reference': 'bae8f325c-cf0a-01fe-6d1a-9a275... " + "0 [{'reference': 'bae8f325c-cf0a-01fe-6d1a-9a275... \n", + "1 [{'reference': 'c54923e64-46f3-9338-9dcb-ff097... " ] }, "execution_count": 10, @@ -436,7 +436,7 @@ { "data": { "text/plain": [ - "('public-global-vessel-identity:v3.0', 'aca119c29-95dd-f5c4-2057-ee45268dcd6f')" + "('public-global-vessel-identity:v3.0', '55889aefb-bef9-224c-d2db-58ecd01e1d7c')" ] }, "execution_count": 14, @@ -467,7 +467,7 @@ }, "outputs": [], "source": [ - "vessel_search_df = vessels_result.df()" + "vessels_df = vessels_result.df()" ] }, { @@ -517,62 +517,67 @@ " \n", " 0\n", " public-global-vessel-identity:v3.0\n", - " 1\n", - " [{'id': '685862e0626f6234c844919bc738a83a', 's...\n", - " []\n", - " [{'date_from': 2012-01-01 00:00:00+00:00, 'dat...\n", - " [{'vessel_id': '55889aefb-bef9-224c-d2db-58ecd...\n", - " [{'id': '71e7da672-2451-17da-b239-857831602eca...\n", - " \n", - " \n", - " 1\n", - " public-global-vessel-identity:v3.0\n", - " 2\n", + " 5\n", " [{'id': 'a8d00ce54b37add7f85a35fcce8e7a1b', 's...\n", - " []\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", " [{'id': 'da1cd7e1b-b8d0-539c-6581-2b3df8d0a6af...\n", " \n", " \n", - " 2\n", + " 1\n", " public-global-vessel-identity:v3.0\n", " 2\n", " [{'id': 'b82d02e5c2c11e5fe5367c91194fc3ba', 's...\n", - " []\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", + " [{'date_from': 2012-01-01 00:00:00+00:00, 'dat...\n", + " [{'vessel_id': '55889aefb-bef9-224c-d2db-58ecd...\n", + " [{'id': '71e7da672-2451-17da-b239-857831602eca...\n", + " \n", " \n", "\n", "" ], "text/plain": [ " dataset registry_info_total_records \\\n", - "0 public-global-vessel-identity:v3.0 1 \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 2 \n", + "2 public-global-vessel-identity:v3.0 1 \n", "\n", - " registry_info registry_owners \\\n", - "0 [{'id': '685862e0626f6234c844919bc738a83a', 's... [] \n", - "1 [{'id': 'a8d00ce54b37add7f85a35fcce8e7a1b', 's... [] \n", - "2 [{'id': 'b82d02e5c2c11e5fe5367c91194fc3ba', 's... [] \n", + " registry_info \\\n", + "0 [{'id': 'a8d00ce54b37add7f85a35fcce8e7a1b', 's... \n", + "1 [{'id': 'b82d02e5c2c11e5fe5367c91194fc3ba', 's... \n", + "2 [{'id': '685862e0626f6234c844919bc738a83a', '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", "\n", " registry_public_authorizations \\\n", - "0 [{'date_from': 2012-01-01 00:00:00+00:00, 'dat... \n", - "1 [{'date_from': 2023-01-01 00:00:00+00:00, 'dat... \n", - "2 [{'date_from': 2015-10-08 00:00:00+00:00, 'dat... \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", "\n", " combined_sources_info \\\n", - "0 [{'vessel_id': '55889aefb-bef9-224c-d2db-58ecd... \n", - "1 [{'vessel_id': '3c81a942b-bf0a-f476-ea72-75c02... \n", - "2 [{'vessel_id': 'aca119c29-95dd-f5c4-2057-ee452... \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", "\n", " self_reported_info \n", - "0 [{'id': '71e7da672-2451-17da-b239-857831602eca... \n", - "1 [{'id': 'da1cd7e1b-b8d0-539c-6581-2b3df8d0a6af... \n", - "2 [{'id': '6583c51e3-3626-5638-866a-f47c3bc7ef7c... " + "0 [{'id': 'da1cd7e1b-b8d0-539c-6581-2b3df8d0a6af... \n", + "1 [{'id': '6583c51e3-3626-5638-866a-f47c3bc7ef7c... \n", + "2 [{'id': '71e7da672-2451-17da-b239-857831602eca... " ] }, "execution_count": 16, @@ -581,7 +586,7 @@ } ], "source": [ - "vessel_search_df.head()" + "vessels_df.head()" ] }, { diff --git a/src/gfwapiclient/__init__.py b/src/gfwapiclient/__init__.py index 31e66e3..f46c81d 100644 --- a/src/gfwapiclient/__init__.py +++ b/src/gfwapiclient/__init__.py @@ -41,9 +41,11 @@ See: https://globalfishingwatch.org/our-apis/documentation#introduction -For more details on the data caveats and terms of use, please refer to the +For more details on the datasets, data caveats and terms of use, please refer to the official Global Fishing Watch API documentation: +See: https://globalfishingwatch.org/our-apis/documentation#api-dataset + See: https://globalfishingwatch.org/our-apis/documentation#data-caveat See: https://globalfishingwatch.org/our-apis/documentation#terms-of-use diff --git a/src/gfwapiclient/client/__init__.py b/src/gfwapiclient/client/__init__.py index 790c30f..e9d2293 100644 --- a/src/gfwapiclient/client/__init__.py +++ b/src/gfwapiclient/client/__init__.py @@ -1,17 +1,19 @@ """Global Fishing Watch (GFW) API Python Client. -This module provides the main entry point for interacting with the Global Fishing Watch (GFW) API, specifically Version 3. -It encapsulates the HTTP client and resources, providing a unified interface -for accessing GFW's data. +This module provides the main entry point for interacting with the +Global Fishing Watch (GFW) API, specifically Version 3. It encapsulates the HTTP client +and resources, providing a unified interface for accessing GFW's data. -For more details on the GFW API and available data, please refer to the -official documentation: +For more details on the GFW API and available data, please refer to the official +Global Fishing Watch API documentation: See: https://globalfishingwatch.org/our-apis/documentation#introduction See: https://globalfishingwatch.org/our-apis/documentation#data-available -See: https://globalfishingwatch.org/our-apis/documentation#version-3-api +See: https://globalfishingwatch.org/our-apis/documentation#api-dataset + +See: https://globalfishingwatch.org/our-apis/documentation#data-caveat """ from gfwapiclient.client.client import Client diff --git a/src/gfwapiclient/client/client.py b/src/gfwapiclient/client/client.py index 270de6e..1474534 100644 --- a/src/gfwapiclient/client/client.py +++ b/src/gfwapiclient/client/client.py @@ -38,6 +38,8 @@ class Client: See: https://globalfishingwatch.org/our-apis/documentation#data-available + See: https://globalfishingwatch.org/our-apis/documentation#api-dataset + See: https://globalfishingwatch.org/our-apis/documentation#data-caveat Attributes: diff --git a/src/gfwapiclient/resources/fourwings/resources.py b/src/gfwapiclient/resources/fourwings/resources.py index 6551647..a632c88 100644 --- a/src/gfwapiclient/resources/fourwings/resources.py +++ b/src/gfwapiclient/resources/fourwings/resources.py @@ -227,7 +227,7 @@ async def create_ais_presence_report( group_by (Optional[Union[FourWingsReportGroupBy, str]], default=None): Grouping criteria for the report. Defaults to `None`. - Allowed values: `"VESSEL_ID"`, `"FLAG"`, `"GEARTYPE"`, `"FLAGANDGEARTYPE"`, `"MMSI"`. + Allowed values: `"VESSEL_ID"`, `"FLAG"`, `"MMSI"`. Example: `"FLAG"`. temporal_resolution (Optional[Union[FourWingsReportTemporalResolution, str]], default="HOURLY"): @@ -463,6 +463,11 @@ async def create_report( and ensure optimal performance, keep requests manageable: prefer simple, small regions and shorter time ranges (e.g., a few days). + **Note:** + + AIS vessel presence (i.e., `"public-global-sar-presence:latest"` dataset) does **not** + support `"GEARTYPE"` or `"FLAGANDGEARTYPE"` as `group_by` criteria. + Args: spatial_resolution (Optional[Union[FourWingsReportSpatialResolution, str]], default="HIGH"): Spatial resolution of the report. Defaults to `"HIGH"`. diff --git a/src/gfwapiclient/resources/insights/resources.py b/src/gfwapiclient/resources/insights/resources.py index cb3dde1..5008741 100644 --- a/src/gfwapiclient/resources/insights/resources.py +++ b/src/gfwapiclient/resources/insights/resources.py @@ -44,7 +44,7 @@ async def get_vessel_insights( Args: includes (Union[List[VesselInsightInclude], List[str]]): List of insight types to include in the response. - Allowed values are `"FISHING"`, `"GAP"`, `"COVERAGE"`, `"IDENTITY"`. + Allowed values are `"FISHING"`, `"GAP"`, `"COVERAGE"`, `"VESSEL-IDENTITY-IUU-VESSEL-LIST"`. Example: `["FISHING", "GAP"]`. start_date (Union[datetime.date, str]):