Merge pull request #44 from GlobalFishingWatch/feature/bulk-downloads-resource

implement Bulk Download API resource and client integration

Author: lykmapipo

README.md

@@ -39,6 +39,8 @@ 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.

src/gfwapiclient/__init__.py

@@ -1,25 +1,52 @@
 """Global Fishing Watch (GFW) API Python Client.
 
-This package provides a Python client for interacting with the Global Fishing Watch (GFW) API,
-specifically `version 3 <https://globalfishingwatch.org/our-apis/documentation#version-3-api>`_.
-It enables access to publicly available API resources, and facilitating the retrieval of the data.
+This package provides a Python client for interacting with the Global Fishing Watch
+(GFW) API version 3.
 
-Features:
+See: https://globalfishingwatch.org/our-apis/documentation#version-3-api
 
-- **4Wings**: Access AIS apparent fishing effort, AIS vessel presence, and SAR vessel detections between 2017 to ~5 days ago.
+See: https://globalfishingwatch.org/our-apis/documentation#in-api-version-3
 
-- **Vessels**: Search and retrieve vessel identity based on AIS self-reported data, combined with authorization and registry data from regional and national registries.
+It enables access to publicly available API resources, and facilitating the retrieval
+of the following APIs data:
 
-- **Events**: Retrieve vessel activity events such as encounters, loitering, port visits, fishing events, and AIS off (aka GAPs).
+- **Map Visualization (4Wings API)**: Access AIS apparent fishing effort,
+AIS vessel presence, and SAR vessel detections between 2017 to ~5 days ago.
 
-- **Insights**: Access vessel insights that combine AIS activity, vessel identity, and public authorizations. Designed to support risk-based decision-making, operational planning, and due diligence—particularly for assessing risks of IUU (Illegal, Unreported, or Unregulated) fishing.
+- **Vessels API**: Search and retrieve vessel identity based on AIS self-reported data,
+combined with authorization and registry data from regional and national registries.
 
-- **Datasets**: 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.
+- **Events API**: Retrieve vessel activity events such as encounters, loitering, port
+visits, fishing events, and AIS off (aka GAPs).
 
-- **References**: 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.
+- **Insights API**: Access vessel insights that combine AIS activity, vessel identity,
+and public authorizations. Designed to support risk-based decision-making, operational
+planning, and due diligence—particularly for assessing risks of
+IUU (Illegal, Unreported, or Unregulated) fishing.
 
-For comprehensive details, please refer to the official
-`Global Fishing Watch API Documentation <https://globalfishingwatch.org/our-apis/documentation#version-3-api>`_.
+- **Datasets API**: Retrieve fixed offshore infrastructure detections (e.g.,
+oil platforms, wind farms etc.) from Sentinel-1 and Sentinel-2 satellite imagery,
+from 2017 up to 3 months ago, classified using deep learning.
+
+- **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 (4Wings API, Datasets API, etc.), these datasets may include
+some **noisy** that are not filtered out.
+
+- **References**: Access metadata for EEZs, MPAs, and RFMOs to use in Events API and
+4Wings API requests and analyses.
+
+For more details on the data, API licenses, and rate limits, please refer to
+the official Global Fishing Watch API documentation:
+
+See: https://globalfishingwatch.org/our-apis/documentation#introduction
+
+For more details on the data caveats and terms of use, please refer to the
+official Global Fishing Watch API documentation:
+
+See: https://globalfishingwatch.org/our-apis/documentation#data-caveat
+
+See: https://globalfishingwatch.org/our-apis/documentation#terms-of-use
 """
 
 from gfwapiclient.__version__ import __version__

src/gfwapiclient/client/client.py

@@ -8,6 +8,7 @@
 
 from gfwapiclient.http import HTTPClient
 from gfwapiclient.resources import (
+    BulkDownloadResource,
     DatasetResource,
     EventResource,
     FourWingsResource,
@@ -55,6 +56,9 @@ class Client:
         datasets (DatasetResource):
             Access to the datasets data resources.
 
+        bulk_downloads (BulkDownloadResource):
+            Access to the Bulk download API resources.
+
         references (ReferenceResource):
             Access to the reference data resources.
     """
@@ -64,6 +68,7 @@ class Client:
     _events: EventResource
     _insights: InsightResource
     _datasets: DatasetResource
+    _bulk_downloads: BulkDownloadResource
     _references: ReferenceResource
 
     def __init__(
@@ -245,6 +250,26 @@ def datasets(self) -> DatasetResource:
             self._datasets = DatasetResource(http_client=self._http_client)
         return self._datasets
 
+    @property
+    def bulk_downloads(self) -> BulkDownloadResource:
+        """Bulk download API resource.
+
+        Provides access to the Bulk Download API resources, which allow to
+        efficiently create, retrieve, and download bulk reports data and files.
+
+        For more details on the Bulk Download API, please refer to the official
+        Global Fishing Watch API documentation:
+
+        See: https://globalfishingwatch.org/our-apis/documentation#bulk-download-api
+
+        Returns:
+            BulkDownloadResource:
+                The bulk download resource instance.
+        """
+        if not hasattr(self, "_bulk_downloads"):
+            self._bulk_downloads = BulkDownloadResource(http_client=self._http_client)
+        return self._bulk_downloads
+
     @property
     def references(self) -> ReferenceResource:
         """References data API resource.

src/gfwapiclient/resources/__init__.py

@@ -1,5 +1,6 @@
 """Global Fishing Watch (GFW) API Python Client - Resources."""
 
+from gfwapiclient.resources.bulk_downloads import BulkDownloadResource
 from gfwapiclient.resources.datasets import DatasetResource
 from gfwapiclient.resources.events import EventResource
 from gfwapiclient.resources.fourwings import FourWingsResource
@@ -9,6 +10,7 @@
 
 
 __all__ = [
+    "BulkDownloadResource",
     "DatasetResource",
     "EventResource",
     "FourWingsResource",

src/gfwapiclient/resources/bulk_downloads/__init__.py

@@ -19,3 +19,8 @@
 
 See: https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats
 """
+
+from gfwapiclient.resources.bulk_downloads.resources import BulkDownloadResource
+
+
+__all__ = ["BulkDownloadResource"]