Metadata-Version: 2.4
Name: gfw-api-python-client
Version: 1.0.1
Summary: Python package for accessing data from Global Fishing Watch APIs.
Author-email: Global Fishing Watch <apis@globalfishingwatch.org>
Maintainer-email: Global Fishing Watch <apis@globalfishingwatch.org>
License: Apache License 2.0
Project-URL: Homepage, https://github.com/GlobalFishingWatch/gfw-api-python-client
Project-URL: Documentation, https://globalfishingwatch.github.io/gfw-api-python-client/
Project-URL: Changelog, https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/main/CHANGELOG.md
Project-URL: Repository, https://github.com/GlobalFishingWatch/gfw-api-python-client
Project-URL: Issues, https://github.com/GlobalFishingWatch/gfw-api-python-client/issues
Keywords: global fishing watch,gfw,apis,api client,fishing data,satellite data,vessel data,marine data,geospatial data,ocean monitoring,marine research,marine conservation,environmental research,ocean sustainability,ais,vms
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Pydantic
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx~=0.28
Requires-Dist: pydantic~=2.10
Requires-Dist: pydantic-settings~=2.8
Requires-Dist: mapbox-vector-tile~=2.1
Requires-Dist: pandas~=2.2
Requires-Dist: geopandas~=1.0
Provides-Extra: lint
Requires-Dist: black>=25.1.0; extra == "lint"
Requires-Dist: isort>=6.0.1; extra == "lint"
Requires-Dist: mypy>=1.15.0; extra == "lint"
Requires-Dist: pydocstyle>=6.3.0; extra == "lint"
Requires-Dist: ruff>=0.11.2; extra == "lint"
Requires-Dist: codespell[toml]>=2.4.1; extra == "lint"
Provides-Extra: test
Requires-Dist: pytest>=8.3.5; extra == "test"
Requires-Dist: pytest-asyncio>=0.26.0; extra == "test"
Requires-Dist: pytest-cov>=6.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.14.0; extra == "test"
Requires-Dist: pytest-xdist>=3.6.1; extra == "test"
Requires-Dist: pytest-timeout>=2.3.1; extra == "test"
Requires-Dist: coverage[toml]>=7.7.1; extra == "test"
Requires-Dist: respx>=0.22.0; extra == "test"
Provides-Extra: dev
Requires-Dist: commitizen>=4.4.1; extra == "dev"
Requires-Dist: pre-commit>=4.2.0; extra == "dev"
Requires-Dist: pip-audit>=2.8.0; extra == "dev"
Provides-Extra: build
Requires-Dist: build>=1.2.2; extra == "build"
Requires-Dist: setuptools>=78.1.0; extra == "build"
Requires-Dist: twine>=6.1.0; extra == "build"
Provides-Extra: docs
Requires-Dist: sphinx>=8.2.3; extra == "docs"
Requires-Dist: furo>=2024.8.6; extra == "docs"
Requires-Dist: myst-parser>=4.0.1; extra == "docs"
Requires-Dist: myst-nb>=1.2.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
Requires-Dist: sphinx-autobuild>=2024.10.3; extra == "docs"
Requires-Dist: sphinx-inline-tabs>=2023.4.21; extra == "docs"
Requires-Dist: sphinx-autodoc2>=0.5.0; extra == "docs"
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6.29.5; extra == "notebooks"
Requires-Dist: ipython>=9.0.2; extra == "notebooks"
Requires-Dist: jupyterlab>=4.3.6; extra == "notebooks"
Requires-Dist: watermark>=2.5.0; extra == "notebooks"
Dynamic: license-file

# Global Fishing Watch API Python Client

<!-- start: badges -->
[![ci](https://github.com/GlobalFishingWatch/gfw-api-python-client/actions/workflows/ci.yaml/badge.svg)](https://github.com/GlobalFishingWatch/gfw-api-python-client/actions/workflows/ci.yaml)
[![codecov](https://codecov.io/gh/GlobalFishingWatch/gfw-api-python-client/branch/develop/graph/badge.svg?token=w4R4VZB5RY)](https://codecov.io/gh/GlobalFishingWatch/gfw-api-python-client)
[![license](https://img.shields.io/badge/license-Apache%202-blue)](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/main/LICENSE)

[![pre-commit action](https://github.com/GlobalFishingWatch/gfw-api-python-client/actions/workflows/pre-commit.yaml/badge.svg)](https://github.com/GlobalFishingWatch/gfw-api-python-client/actions/workflows/pre-commit.yaml)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![conventional commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
<!-- end: badges -->

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](https://globalfishingwatch.org/our-apis/documentation#version-3-api). As of April 30th, 2024, API version 3 is the standard. For the most recent API updates, refer to our [API release notes](https://globalfishingwatch.org/our-apis/documentation#api-release-notes).


The `gfw-api-python-client` simplifies access to Global Fishing Watch (GFW) data through [our APIs](https://globalfishingwatch.org/our-apis/documentation#introduction]). 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 Global Fishing Watch Python package currently works with the following APIs:

- [Vessels API](https://globalfishingwatch.org/our-apis/documentation#vessels-api): vessel search and identity based on AIS self reported data and public registry information

- [Events API](https://globalfishingwatch.org/our-apis/documentation#events-api): encounters, loitering, port visits, AIS-disabling events and fishing events based on AIS data

- [Gridded fishing effort (4Wings API)](https://globalfishingwatch.org/our-apis/documentation#map-visualization-4wings-api): apparent fishing effort based on AIS data and SAR vessel detections.

- [Insights API](https://globalfishingwatch.org/our-apis/documentation#insights-api): The Insights API is a set of indicators or 'vessel insights' that bring together important information on a vessel's known activity (based on AIS), vessel identity information and public authorizations. The objective of the insights is to support risk-based decision-making, operational planning, and other due diligence activities by making it easier for a user to identify vessel characteristics that can indicate an increased potential or opportunity for a vessel to engage in IUU (Illegal, Unreported, or Unregulated) fishing.

> **Note**: See the [Terms of Use](https://globalfishingwatch.org/our-apis/documentation#reference-data) page for GFW APIs for information on our API licenses and rate limits.

## Installation

To start using `gfw-api-python-client`, ensure you have [Python 3.12+](https://realpython.com/installing-python/) installed on your system. It's recommended to install the package in a [virtual environment](https://docs.python.org/3/library/venv.html) using [pip](https://pip.pypa.io/en/stable/).

### Linux/macOS

```bash
python3.12 -m venv .venv
source venv/bin/activate
pip install gfw-api-python-client
```

### Windows

```batch
python3.12 -m venv .venv
venv\Scripts\activate
pip install gfw-api-python-client
```

## Usage

Once installed, you can import and use `gfw-api-python-client` in your code:

```python
import gfwapiclient as gfw

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

## Authorization

To use the `gfw-api-python-client`, you need a GFW API access token. You can request this access token from the [GFW API Portal](https://globalfishingwatch.org/our-apis/tokens). Once you have your access token, export it as an environment variable.


### Linux/macOS

```bash
export GFW_API_ACCESS_TOKEN="<PASTE_YOUR_GFW_API_ACCESS_TOKEN_HERE>"
```

### Windows

```powershell
$env:GFW_API_ACCESS_TOKEN = "<PASTE_YOUR_GFW_API_ACCESS_TOKEN_HERE>"
```

## Contributing

We welcome all contributions to improve the package!. Please read our [Contribution Guide](https://github.com/GlobalFishingWatch/gfw-api-python-client/blob/develop/CONTRIBUTING.md) and reach out!.
