py-seaaroundus 1.0.2

Python wrapper for the Sea Around Us fisheries catch API

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")

# 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

Python	R equivalent	Description
list_regions(region)	listregions()	List region IDs and titles
list_fishing_entities()	—	List fishing countries/territories
catch_data(...)	catchdata()	Wide catch table (years × categories)
catch_data_long(...)	—	Long/tidy catch table
region_map(region, id=...)	regionmap()	Region map (requires [maps])
plot_catch_data(...)	catchdata(..., chart=TRUE)	Stacked area chart
marine_trophic_index(...)	marinetrophicindex()	Deprecated: endpoint currently returns HTTP 500
eez_vs_high_seas()	eezsvshighseas()	Deprecated: endpoint currently times out/unavailable
get_cells(shape)	getcells()	Deprecated: endpoint currently returns HTTP 403
get_cell_data(cells, year=...)	getcelldata()	Deprecated: endpoint currently returns HTTP 403
plot_mti(...)	marinetrophicindex(..., chart=TRUE)	Deprecated: depends on deprecated MTI endpoint
plot_eez_vs_high_seas()	eezsvshighseas(chart=TRUE)	Deprecated: depends on unavailable endpoint

Regions

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

Measures

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

Dimensions

• taxon (not available for the taxon region type)
• commercialgroup
• functionalgroup
• country (fishing country)
• sector
• catchtype
• reporting-status
• layer
• eez (only for eez-bordering and taxon regions)
• highseas (only for taxon region)

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