improve documentation, notebooks, and async usage guidance

Makefile

@@ -1,5 +1,6 @@
 .DEFAULT_GOAL := help
 sources = src tests
+notebooks-sources = notebooks
 
 .PHONY: install  ## Install the package, dependencies, and pre-commit for local development
 install:
@@ -14,12 +15,24 @@ format:
 	python -m ruff check --fix $(sources)
 	python -m ruff format $(sources)
 
+.PHONY: format-notebooks  ## Auto-format Jupyter Notebooks
+format-notebooks:
+	python -m black $(notebooks-sources)
+	python -m ruff check --fix $(notebooks-sources)
+	python -m ruff format $(notebooks-sources)
+
 .PHONY: lint  ## Lint python source files
 lint:
 	python -m ruff check $(sources)
 	python -m ruff format --check $(sources)
 	python -m black $(sources) --check --diff
 
+.PHONY: lint-notebooks  ## Lint Jupyter Notebooks
+lint-notebooks:
+	python -m ruff check $(notebooks-sources)
+	python -m ruff format --check $(notebooks-sources)
+	python -m black $(notebooks-sources) --check --diff
+
 .PHONY: codespell  ## Use Codespell to do spellchecking
 codespell:
 	python -m codespell_lib

README.md

@@ -74,15 +74,15 @@ gfw_client = gfw.Client(
 )
 ```
 
-For step-by-step instructions and examples, see the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html) and [Usage Guides](https://globalfishingwatch.github.io/gfw-api-python-client/usage-guides/index.html) in the documentation.
+For step-by-step instructions and examples, see the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html), [Usage Guides](https://globalfishingwatch.github.io/gfw-api-python-client/usage-guides/index.html), and [Workflow Guides](https://globalfishingwatch.github.io/gfw-api-python-client/workflow-guides/index.html) in the documentation.
 
 ## Documentation
 
 The full project documentation is available at [globalfishingwatch.github.io/gfw-api-python-client](https://globalfishingwatch.github.io/gfw-api-python-client/index.html).
 
 To get started with the basics, head over to the [Getting Started](https://globalfishingwatch.github.io/gfw-api-python-client/getting-started.html) guide.
 
-For detailed instructions and examples on interacting with the various APIs offered by Global Fishing Watch, explore the [Usage Guides](https://globalfishingwatch.github.io/gfw-api-python-client/usage-guides/index.html) section.
+For detailed instructions and examples on interacting with the various APIs offered by Global Fishing Watch, explore the [Usage Guides](https://globalfishingwatch.github.io/gfw-api-python-client/usage-guides/index.html), and [Workflow Guides](https://globalfishingwatch.github.io/gfw-api-python-client/workflow-guides/index.html) sections.
 
 For a complete reference of all available classes, methods, and modules, see the [API Reference](https://globalfishingwatch.github.io/gfw-api-python-client/apidocs/index.html) section.
 

docs/source/conf.py

@@ -34,8 +34,8 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     # third-party extensions
-    "myst_parser",
-    # "myst_nb",
+    # "myst_parser", # imported by myst_nb automatically
+    "myst_nb",
     "autodoc2",
     "sphinx_copybutton",
     "sphinx_inline_tabs",
@@ -47,7 +47,8 @@
 # The suffix of source filenames.
 source_suffix = {
     ".rst": "restructuredtext",
-    ".md": "markdown",
+    ".md": "myst-nb",
+    ".ipynb": "myst-nb",
 }
 
 # The master toctree document.
@@ -95,6 +96,16 @@
 ]
 myst_heading_anchors = 3
 
+# -- MyST-NB execution configuration ------------------------------------------
+# https://myst-nb.readthedocs.io/en/latest/configuration.html#config-intro
+
+nb_execution_mode = "force"
+nb_execution_timeout = 300
+nb_execution_raise_on_error = True
+
+nb_output_stderr = "show"
+nb_merge_streams = True
+
 
 # -- Options for autodoc2 -------------------------------------------------
 # https://sphinx-autodoc2.readthedocs.io/en/latest/config.html

docs/source/getting-started.md

@@ -47,8 +47,8 @@ For more detailed installation instructions, including setting up a virtual envi
 Once installed, you can import and use `gfw-api-python-client` in your Python codes:
 
 ```python
-import os
 import datetime
+import os
 
 import gfwapiclient as gfw
 
@@ -63,6 +63,10 @@ gfw_client = gfw.Client(
 )
 ```
 
+> **Important:** The `gfw-api-python-client` is **async-first**: all API methods are asynchronous and must be executed using Python's `async` / `await` syntax. **Environments with built-in async support** (e.g., _Jupyter Notebook_, _Google Colab_, and async web frameworks such as _FastAPI_) can call client methods directly using `await`, with no additional setup. **Environments without built-in async support** (e.g., _plain Python scripts_, _Python modules_, or synchronous web frameworks such as _Flask_ and _Django_) must explicitly run asynchronous code using an event loop. This can be done with tools such as [`asyncio.run`](https://docs.python.org/3/library/asyncio.html), [`trio.run`](https://trio.readthedocs.io/en/stable/), [`anyio.run`](https://anyio.readthedocs.io/en/stable/), or framework-specific async integration.
+
+> **Tip:** Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.11+ with `python -m asyncio` to run `gfw-api-python-client` code interactively, as these environments support executing `async` / `await` expressions directly in the console.
+
 ## Making API Requests
 
 ### Searching for a Vessel by MMSI
@@ -103,6 +107,10 @@ vessel_self_reported_infos = [
     for self_reported_info in vessel_item.self_reported_info
 ]
 
+vessel_ids = [
+    self_reported_info.id for self_reported_info in vessel_self_reported_infos
+]
+
 print(vessel_ids)
 ```
 
@@ -124,6 +132,7 @@ start_datetime = min(
     ]
 )
 start_date = start_datetime.date()
+start_date = max(start_date, datetime.date.fromisoformat("2020-01-01"))
 
 
 end_datetime = max(
@@ -226,6 +235,6 @@ memory usage: 43.7+ KB
 
 This guide has provided you with the fundamental steps to install and use the `gfw-api-python-client` for making basic API requests.
 
-To further explore the capabilities of our APIs (`4Wings`, `Vessels`, `Events`, `Insights`, `Datasets`, `References`, etc.), please refer to the detailed [Usage Guides](usage-guides/index). These guides delve into specific use cases and demonstrate how to effectively leverage the `gfw-api-python-client` for your data exploration needs.
+To further explore the capabilities of our APIs (`4Wings`, `Vessels`, `Events`, `Insights`, `Datasets`, `Bulk Download`, `References`, etc.), please refer to the detailed [Usage Guides](usage-guides/index) and [Workflow Guides](workflow-guides/index). These guides delve into specific use cases and demonstrate how to effectively leverage the `gfw-api-python-client` for your data exploration needs.
 
 Happy coding and data exploring!

docs/source/index.md

@@ -14,6 +14,7 @@ The `gfw-api-python-client` simplifies access to Global Fishing Watch (GFW) data
 getting-started
 installation
 usage-guides/index
+workflow-guides/index
 ```
 
 ```{toctree}
@@ -48,7 +49,12 @@ To learn about how to use `gfw-api-python-client`, check out the following resou
     - [Events API](usage-guides/events-api)
     - [Insights API](usage-guides/insights-api)
     - [Datasets API](usage-guides/datasets-api)
+    - [Bulk Download API](usage-guides/bulk-downloads-api)
     - [References Data API](usage-guides/references-data-api)
+- [Workflow Guides](workflow-guides/index)
+    - [Analyze apparent fishing effort in Senegalese EEZ](workflow-guides/workflow-01-analyze-apparent-fishing-effort-senegalese-eez)
+    - [Analyze apparent fishing effort in Argentinian EEZ](workflow-guides/workflow-02-analyze-apparent-fishing-effort-argentinian-eez)
+    - [Analyze a fleet in Ghanaian EEZ](workflow-guides/workflow-03-analyze-fleet-in-ghanaian-eez)
 
 If you find bugs, need help, or want to contribute, check out the following resources:
 

docs/source/usage-guides/4wings-api.md

@@ -2,9 +2,9 @@
 
 <a href="https://colab.research.google.com/github/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/4wings-api.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>
 
-This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access the 4Wings API, which is designed for generating reports and statistics on activities within specified regions. This API is particularly useful for creating data visualizations related to fishing effort and other vessel activities. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/4wings-api.ipynb) version of this guide with more usage examples.
+This guide provides detailed instructions on how to use the [gfw-api-python-client](https://github.com/GlobalFishingWatch/gfw-api-python-client) to access the [4Wings API](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api), which is designed for generating reports and statistics on activities within specified regions. This API is particularly useful for creating data visualizations related to fishing effort and other vessel activities. Here is a [Jupyter Notebook](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/notebooks/usage-guides/4wings-api.ipynb) version of this guide with more usage examples.
 
-> **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [Data Caveats](https://globalfishingwatch.org/our-apis/documentation#data-caveat), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits.
+> **Note:** See the [Datasets](https://globalfishingwatch.org/our-apis/documentation#api-dataset), [AIS Apparent Fishing Effort Data Caveats](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort), [AIS Vessel Presence Data Caveats](https://globalfishingwatch.org/our-apis/documentation#ais-vessel-presence-caveats), [SAR Vessel Detections Data Caveats](https://globalfishingwatch.org/our-apis/documentation#sar-vessel-detections-data-caveats), and [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#terms-of-use) pages in the [GFW API documentation](https://globalfishingwatch.org/our-apis/documentation#introduction) for details on GFW data, API licenses, and rate limits.
 
 ## Prerequisites
 
@@ -32,6 +32,8 @@ gfw_client = gfw.Client(
 
 The `gfw_client.fourwings` object provides methods to generate reports, retrieve the last generated report, and get global fishing effort statistics. These methods return a `result` object, which offers convenient ways to access the data as Pydantic models using `.data()` or as pandas DataFrames using `.df()`.
 
+> **Tip:** Use [IPython](https://ipython.readthedocs.io/en/stable/) or Python 3.11+ with `python -m asyncio` to run `gfw-api-python-client` code interactively, as these environments support executing `async` / `await` expressions directly in the console.
+
 ## Creating a Fishing Effort Report (`create_fishing_effort_report`)
 
 Generates **AIS (Automatic Identification System) apparent fishing effort** reports to visualize fishing activity. Please [learn more about apparent fishing effort here](https://globalfishingwatch.org/our-apis/documentation#ais-apparent-fishing-effort) and [check its data caveats here](https://globalfishingwatch.org/our-apis/documentation#apparent-fishing-effort).
@@ -293,7 +295,11 @@ report_result = await gfw_client.fourwings.create_report(
     spatial_resolution="LOW",
     temporal_resolution="MONTHLY",
     group_by="FLAG",
-    datasets=["public-global-fishing-effort:latest"],
+    datasets=[
+        "public-global-fishing-effort:latest",
+        "public-global-sar-presence:latest",
+        "public-global-presence:latest",
+    ],
     start_date="2022-01-01",
     end_date="2022-05-01",
     region={
@@ -324,7 +330,7 @@ print(report_item.model_dump())
 **Output:**
 
 ```
-('2022-03', 'RUS', 7.109166666666667, 3, 75.8, 44.0)
+('2022-03', 'RUS', 1.0, 1, 52.1, 153.2)
 ```
 
 ### Access the report data as a DataFrame
@@ -340,32 +346,32 @@ print(report_df[["date", "flag", "hours", "lat", "lon"]].head())
 
 ```
 <class 'pandas.core.frame.DataFrame'>
-RangeIndex: 32271 entries, 0 to 32270
+RangeIndex: 310599 entries, 0 to 310598
 Data columns (total 20 columns):
- #   Column                   Non-Null Count  Dtype
----  ------                   --------------  -----
- 0   date                     32271 non-null  object
- 1   detections               0 non-null      object
- 2   flag                     32271 non-null  object
- 3   gear_type                0 non-null      object
- 4   hours                    32271 non-null  float64
- 5   vessel_ids               32271 non-null  int64
- 6   vessel_id                0 non-null      object
- 7   vessel_type              0 non-null      object
- 8   entry_timestamp          0 non-null      object
- 9   exit_timestamp           0 non-null      object
- 10  first_transmission_date  0 non-null      object
- 11  last_transmission_date   0 non-null      object
- 12  imo                      0 non-null      object
- 13  mmsi                     0 non-null      object
- 14  call_sign                0 non-null      object
- 15  dataset                  0 non-null      object
- 16  report_dataset           32271 non-null  object
- 17  ship_name                0 non-null      object
- 18  lat                      32271 non-null  float64
- 19  lon                      32271 non-null  float64
-dtypes: float64(3), int64(1), object(16)
-memory usage: 4.9+ MB
+ #   Column                   Non-Null Count   Dtype
+---  ------                   --------------   -----
+ 0   date                     310599 non-null  object
+ 1   detections               3995 non-null    float64
+ 2   flag                     310599 non-null  object
+ 3   gear_type                0 non-null       object
+ 4   hours                    306604 non-null  float64
+ 5   vessel_ids               310599 non-null  int64
+ 6   vessel_id                0 non-null       object
+ 7   vessel_type              0 non-null       object
+ 8   entry_timestamp          0 non-null       object
+ 9   exit_timestamp           0 non-null       object
+ 10  first_transmission_date  0 non-null       object
+ 11  last_transmission_date   0 non-null       object
+ 12  imo                      0 non-null       object
+ 13  mmsi                     0 non-null       object
+ 14  call_sign                0 non-null       object
+ 15  dataset                  0 non-null       object
+ 16  report_dataset           310599 non-null  object
+ 17  ship_name                0 non-null       object
+ 18  lat                      310599 non-null  float64
+ 19  lon                      310599 non-null  float64
+dtypes: float64(4), int64(1), object(15)
+memory usage: 47.4+ MB
 ```
 
 ## Reference Data
@@ -374,10 +380,11 @@ The 4Wings API often requires specifying geographic regions. You can use the [Re
 
 ## Next Steps
 
-Explore the [Usage Guides](index) for other API resources to understand how you can combine the reporting and statistical capabilities of the 4Wings API with vessel information, event data, and more. Check out the following resources:
+Explore the [Usage Guides](index) and [Workflow Guides](../workflow-guides/index) for other API resources to understand how you can combine the reporting and statistical capabilities of the 4Wings API with vessel information, event data, and more. Check out the following resources:
 
 - [Vessels API](vessels-api)
 - [Events API](events-api)
 - [Insights API](insights-api)
 - [Datasets API](datasets-api)
+- [Bulk Download API](bulk-downloads-api)
 - [Reference Data API](references-data-api)