Global Fishing Watch API Python Client

Python package for accessing data from Global Fishing Watch (GFW) APIs.

Important: The gfw-api-python-client version 1 directly corresponds to Global Fishing Watch API version 3. As of April 30th, 2024, API version 3 is the standard. For the most recent API updates, refer to our API release notes.

Introduction

The gfw-api-python-client simplifies access to Global Fishing Watch (GFW) data through our APIs. It offers straightforward functions for retrieving GFW data. For R users, we also provide the gfwr package; learn more here

The Global Fishing Watch Python package currently works with the following APIs:

• Map Visualization (4Wings API): Access AIS apparent fishing effort, AIS vessel presence, and SAR vessel detections between 2017 to ~5 days ago.

• Vessels API: Search and retrieve vessel identity based on AIS self-reported data, combined with authorization and registry data from regional and national registries.

• Events API: Retrieve vessel activity events such as encounters, loitering, port visits, fishing events, and AIS off (aka GAPs).

• 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.

• 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: 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), Datasets API etc.), these datasets may include some noisy that are not filtered out.

• References API: Access metadata for EEZs, MPAs, and RFMOs to use in Events API and Map Visualization (4Wings API) requests and analyses.

Note: See the Datasets, Data Caveats, and Terms of Use pages in the GFW API documentation for details on GFW data, API licenses, and rate limits.

Requirements

• Python >= 3.11
• pip >= 25
• venv - Python's built-in virtual environment tool
• API access token from the Global Fishing Watch API portal

Installation

You can install gfw-api-python-client using pip:

pip install gfw-api-python-client

For detailed instructions—including how to set up a virtual environment—refer to the Installation Guide in the documentation.

Usage

After installation, you can start using gfw-api-python-client by importing it into your Python code:

import gfwapiclient as gfw

gfw_client = gfw.Client(
    access_token="<PASTE_YOUR_GFW_API_ACCESS_TOKEN_HERE>",
)

For step-by-step instructions and examples, see the Getting Started, Usage Guides, and Workflow Guides in the documentation.

Documentation

The full project documentation is available at globalfishingwatch.github.io/gfw-api-python-client.

To get started with the basics, head over to the Getting Started guide.

For detailed instructions and examples on interacting with the various APIs offered by Global Fishing Watch, explore the Usage Guides, and Workflow Guides sections.

For a complete reference of all available classes, methods, and modules, see the API Reference section.

Contributing

We welcome and appreciate contributions of all kinds to help improve this package!

Before getting started, please take a moment to review the following guides:

• Contribution Guide – Learn how to propose changes, submit pull requests, and understand our development process.

• Setup Guide – Get your development environment up and running.

• Git Workflow – Understand our branching strategy and commit conventions.

If you have questions, ideas, or run into issues, feel free to open an issue or reach out — we’d love to hear from you!