GlobalFishingWatch · lykmapipo · Jan 13, 2026 · Sep 17, 2025 · Sep 17, 2025 · Oct 28, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,19 @@
+## v1.4.0 (2026-01-13)
+
+### Feat
+
+- **bulk-downloads**: implement bulk report query API endpoints and models
+- **bulk-downloads**: implement bulk report API endpoints
+- **bulk-downloads**: implement bulk report file API endpoints and models
+- **bulk-downloads**: implement bulk report list API endpoints and models
+- **bulk-downloads**: implement bulk report detail API endpoints and models
+- **bulk-downloads**: implement bulk report create API endpoints and models
+- **bulk-downloads**: add base request and response models for Bulk Download API
+
+### Fix
+
+- **bulk-downloads**: correct typehints in docstrings
+
 ## v1.3.0 (2025-09-17)
 
 ### Feat

diff --git a/CITATION.cff b/CITATION.cff
@@ -1,18 +1,18 @@
-cff-version: 1.3.0
+cff-version: 1.2.0
 title: "GlobalFishingWatch/gfw-api-python-client: Global Fishing Watch APIs Python Client"
 message: "If you use this software, please cite it using the metadata below."
 authors:
   - name: "The Global Fishing Watch Team"
     website: "https://globalfishingwatch.org/"
     email: "apis@globalfishingwatch.org"
 abstract: "Python package for accessing data from Global Fishing Watch APIs."
-version: "1.3.0"
+version: "1.4.0"
 doi: 10.5281/zenodo.15617432
 license: "Apache-2.0"
 license-url: "https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/LICENSE"
 repository-code: "https://github.com/GlobalFishingWatch/gfw-api-python-client"
 url: "https://github.com/GlobalFishingWatch/gfw-api-python-client"
-date-released: "2025-09-17"
+date-released: "2026-01-13"
 keywords:
   - "global fishing watch"
   - "gfw"

diff --git a/INSTALLATION.md b/INSTALLATION.md
@@ -127,7 +127,7 @@ print(gfw.__version__)
 If the installation was successful, you should see the installed version number, for example:
 
 ```
-3.0.0
+1.4.0
 ```
 
 You can also try a basic import to ensure the package is accessible:

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

diff --git a/README.md b/README.md
@@ -39,9 +39,11 @@ The Global Fishing Watch Python package currently works with the following APIs:
 
 - [Datasets API](https://globalfishingwatch.org/our-apis/documentation#datasets-api): Retrieve fixed offshore infrastructure detections (e.g., oil platforms, wind farms) from Sentinel-1 and Sentinel-2 satellite imagery, from 2017 up to 3 months ago, classified using deep learning.
 
+- [Bulk Download API](https://globalfishingwatch.org/our-apis/documentation#bulk-download-api): Efficiently access and download large-scale datasets to integrate with big data platforms and tools used by data engineers and researchers. Unlike our other APIs ([Map Visualization (4Wings API)](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api), [Datasets API](https://globalfishingwatch.org/our-apis/documentation#datasets-api) etc.), these datasets may include some **noisy** that are not filtered out.
+
 - [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
 
@@ -72,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.
 

diff --git a/docs/source/apidocs/gfwapiclient/gfwapiclient.__version__.rst b/docs/source/apidocs/gfwapiclient/gfwapiclient.__version__.rst
@@ -25,6 +25,6 @@ API
 
 .. py:data:: __version__
    :canonical: gfwapiclient.__version__.__version__
-   :value: '1.3.0'
+   :value: '1.4.0'
 
    .. autodoc2-docstring:: gfwapiclient.__version__.__version__
diff --git a/docs/source/apidocs/gfwapiclient/gfwapiclient.client.client.rst b/docs/source/apidocs/gfwapiclient/gfwapiclient.client.client.rst
@@ -94,6 +94,13 @@ API
 
       .. autodoc2-docstring:: gfwapiclient.client.client.Client._datasets
 
+   .. py:attribute:: _bulk_downloads
+      :canonical: gfwapiclient.client.client.Client._bulk_downloads
+      :type: gfwapiclient.resources.BulkDownloadResource
+      :value: None
+
+      .. autodoc2-docstring:: gfwapiclient.client.client.Client._bulk_downloads
+
    .. py:attribute:: _references
       :canonical: gfwapiclient.client.client.Client._references
       :type: gfwapiclient.resources.ReferenceResource
@@ -131,6 +138,12 @@ API
 
       .. autodoc2-docstring:: gfwapiclient.client.client.Client.datasets
 
+   .. py:property:: bulk_downloads
+      :canonical: gfwapiclient.client.client.Client.bulk_downloads
+      :type: gfwapiclient.resources.BulkDownloadResource
+
+      .. autodoc2-docstring:: gfwapiclient.client.client.Client.bulk_downloads
+
    .. py:property:: references
       :canonical: gfwapiclient.client.client.Client.references
       :type: gfwapiclient.resources.ReferenceResource

diff --git a/...docs/gfwapiclient/gfwapiclient.resources.bulk_downloads.base.models.request.rst b/...docs/gfwapiclient/gfwapiclient.resources.bulk_downloads.base.models.request.rst
@@ -0,0 +1,172 @@
+:py:mod:`gfwapiclient.resources.bulk_downloads.base.models.request`
+===================================================================
+
+.. py:module:: gfwapiclient.resources.bulk_downloads.base.models.request
+
+.. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request
+   :allowtitles:
+
+Module Contents
+---------------
+
+Classes
+~~~~~~~
+
+.. list-table::
+   :class: autosummary longtable
+   :align: left
+
+   * - :py:obj:`BulkReportDataset <gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportDataset>`
+     - .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportDataset
+          :summary:
+   * - :py:obj:`BulkReportFormat <gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFormat>`
+     - .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFormat
+          :summary:
+   * - :py:obj:`BulkReportGeometry <gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportGeometry>`
+     - .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportGeometry
+          :summary:
+   * - :py:obj:`BulkReportRegion <gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportRegion>`
+     - .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportRegion
+          :summary:
+   * - :py:obj:`BulkReportFileType <gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType>`
+     - .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType
+          :summary:
+
+Data
+~~~~
+
+.. list-table::
+   :class: autosummary longtable
+   :align: left
+
+   * - :py:obj:`__all__ <gfwapiclient.resources.bulk_downloads.base.models.request.__all__>`
+     - .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.__all__
+          :summary:
+
+API
+~~~
+
+.. py:data:: __all__
+   :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.__all__
+   :value: ['BulkReportDataset', 'BulkReportFileType', 'BulkReportFormat', 'BulkReportGeometry', 'BulkReportReg...
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.__all__
+
+.. py:class:: BulkReportDataset()
+   :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportDataset
+
+   Bases: :py:obj:`str`, :py:obj:`enum.Enum`
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportDataset
+
+   .. rubric:: Initialization
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportDataset.__init__
+
+   .. py:attribute:: FIXED_INFRASTRUCTURE_DATA_LATEST
+      :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportDataset.FIXED_INFRASTRUCTURE_DATA_LATEST
+      :value: 'public-fixed-infrastructure-data:latest'
+
+      .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportDataset.FIXED_INFRASTRUCTURE_DATA_LATEST
+
+.. py:class:: BulkReportFormat()
+   :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFormat
+
+   Bases: :py:obj:`str`, :py:obj:`enum.Enum`
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFormat
+
+   .. rubric:: Initialization
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFormat.__init__
+
+   .. py:attribute:: CSV
+      :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFormat.CSV
+      :value: 'CSV'
+
+      .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFormat.CSV
+
+   .. py:attribute:: JSON
+      :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFormat.JSON
+      :value: 'JSON'
+
+      .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFormat.JSON
+
+.. py:class:: BulkReportGeometry(/, **data: typing.Any)
+   :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportGeometry
+
+   Bases: :py:obj:`gfwapiclient.base.models.BaseModel`
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportGeometry
+
+   .. rubric:: Initialization
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportGeometry.__init__
+
+   .. py:attribute:: type
+      :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportGeometry.type
+      :type: str
+      :value: 'Field(...)'
+
+      .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportGeometry.type
+
+   .. py:attribute:: coordinates
+      :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportGeometry.coordinates
+      :type: typing.Any
+      :value: 'Field(...)'
+
+      .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportGeometry.coordinates
+
+.. py:class:: BulkReportRegion(/, **data: typing.Any)
+   :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportRegion
+
+   Bases: :py:obj:`gfwapiclient.base.models.BaseModel`
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportRegion
+
+   .. rubric:: Initialization
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportRegion.__init__
+
+   .. py:attribute:: dataset
+      :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportRegion.dataset
+      :type: typing.Optional[str]
+      :value: 'Field(...)'
+
+      .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportRegion.dataset
+
+   .. py:attribute:: id
+      :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportRegion.id
+      :type: typing.Optional[typing.Union[str, int]]
+      :value: 'Field(...)'
+
+      .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportRegion.id
+
+.. py:class:: BulkReportFileType()
+   :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType
+
+   Bases: :py:obj:`str`, :py:obj:`enum.Enum`
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType
+
+   .. rubric:: Initialization
+
+   .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType.__init__
+
+   .. py:attribute:: DATA
+      :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType.DATA
+      :value: 'DATA'
+
+      .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType.DATA
+
+   .. py:attribute:: README
+      :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType.README
+      :value: 'README'
+
+      .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType.README
+
+   .. py:attribute:: GEOM
+      :canonical: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType.GEOM
+      :value: 'GEOM'
+
+      .. autodoc2-docstring:: gfwapiclient.resources.bulk_downloads.base.models.request.BulkReportFileType.GEOM
-Original file line number
+Diff line change
@@ Expand Up / @@ -127,7 +127,7 @@ print(gfw.__version__) @@
     If the installation was successful, you should see the installed version number, for example:
     ```
-.0.0
+.4.0
     ```
     You can also try a basic import to ensure the package is accessible:
@@ Expand Down @@