py-seaaroundus

Python wrapper for the Sea Around Us API, inspired by the R rseaaroundus package. Install as py-seaaroundus; import as seaaroundus.

Install from PyPI:

pip install py-seaaroundus

Optional extras:

pip install "py-seaaroundus[plot]"     # matplotlib stacked-area charts
pip install "py-seaaroundus[maps]"     # geopandas region maps
pip install "py-seaaroundus[notebook]" # ipykernel for notebooks
pip install "py-seaaroundus[all]"      # plot, maps, and dev tools

The Sea Around Us data are licensed to the public under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License. Please read the data use policy in DATA_USE.

Quick start

import seaaroundus as sau

# List exclusive economic zones
eezs = sau.list_regions("eez")

# Catch data for Brazil (EEZ id 76) as a wide year-by-species table
catch = sau.catch_data("eez", 76)

# Top 3 taxa only
catch_top3 = sau.catch_data("eez", 76, limit=3)

# Value by reporting status
value = sau.catch_data("eez", 76, measure="value", dimension="reporting-status")

# Long/tidy format (useful for ggplot-style workflows)
long = sau.catch_data_long("eez", 76, dimension="functionalgroup")

# Catch-data reliability / uncertainty scores (1 = least, 4 = most reliable)
scores = sau.reliability_score("eez", 76)

# Marine trophic index (deprecated: endpoint currently returns HTTP 500)
mti = sau.marine_trophic_index("eez", 76)
fib = sau.marine_trophic_index("eez", 76, mti_type="fib_index", transfer_efficiency=0.25)

# Global EEZ vs. high-seas percentages (deprecated: endpoint currently unavailable)
global_split = sau.eez_vs_high_seas()

# Spatial cell queries (deprecated: endpoints currently return HTTP 403)
cells = sau.get_cells(
    "POLYGON ((-48.17 15.84, -54.96 28.96, -35.96 27.60, -48.17 15.84))"
)
cell_catch = sau.get_cell_data(cells, year=2005)

Plotting and maps

import seaaroundus as sau

fig, ax = sau.plot_catch_data("eez", 76, measure="tonnage", dimension="taxon")
fig, ax = sau.plot_mti("eez", 76)
fig, ax = sau.region_map("eez", 76)

Batch downloads for multiple countries

import pandas as pd
import seaaroundus as sau

countries = pd.DataFrame(
    {
        "iso_a3": ["BRA", "IDN"],
        "country": ["Brazil", "Indonesia"],
    }
)

totals = sau.download_country_fisheries_timeseries(
    countries,
    years=10,
    measure="value",
    show_progress=True,
)

breakdown = sau.download_country_fisheries_breakdown(
    countries,
    dimension="functionalgroup",
    measure="value",
)

API reference

Regions

• eez
• lme
• rfmo
• eez-bordering
• taxon
• fishing-entity

Measures

• tonnage — reconstructed catch in metric tonnes
• value — real 2019 million US dollars

Dimensions

• taxon (not available for the taxon region type)
• commercialgroup
• functionalgroup
• country (fishing country)
• gear
• enduse
• sector
• catchtype
• reporting-status
• layer
• eez (only for eez-bordering and taxon regions)
• highseas — not currently usable (404 for EEZ; empty for taxon)

Reconstructed catch is currently available through 2019.

Endpoint availability notes

The Sea Around Us public API is upstream and may change without notice. As of the latest probe in this repository:

• /api/v1/eez/marine-trophic-index/ returns HTTP 500
• /api/v1/global/eez-vs-high-seas/ is timing out
• /api/v1/eez/tonnage/highseas/ returns HTTP 404
• /api/v1/spatial/r/shape returns HTTP 403
• /api/v1/spatial/r/cells returns HTTP 403

Related wrapper functions are marked deprecated in code and README until (and if) these endpoints are restored.

Custom client

from seaaroundus import SeaAroundUsClient, catch_data

client = SeaAroundUsClient(
    base_url="http://api.seaaroundus.org/api/v1",
    request_source="my-research-project",
    timeout=60,
)
catch = catch_data("eez", 76, client=client)

Usage note

When querying the API, please be respectful of the resources required to provide this data. Cache results locally (handled by the repository's default behaviour) and avoid repeated requests for duplicate information.

Development

Clone the repository and install in editable mode:

git clone https://github.com/orlando-code/py-seaaroundus.git
cd py-seaaroundus
pip install -e ".[dev]"
pre-commit install   # run ruff + pytest on each commit
pytest               # run tests manually

CI runs the same checks on push and pull requests via GitHub Actions.

License

See LICENSE for more information.