Metadata-Version: 2.4
Name: py-seaaroundus
Version: 1.0.1
Summary: Python wrapper for the Sea Around Us fisheries catch API
Author-email: Orlando Timmerman <rt582@cam.ac.uk>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/orlando-code/py-seaaroundus
Project-URL: Repository, https://github.com/orlando-code/py-seaaroundus
Project-URL: Documentation, https://github.com/orlando-code/py-seaaroundus#readme
Project-URL: Sea Around Us, http://www.seaaroundus.org/
Keywords: fisheries,sea-around-us,catch-data,marine
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Provides-Extra: maps
Requires-Dist: geopandas>=0.14; extra == "maps"
Requires-Dist: matplotlib>=3.7; extra == "maps"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Provides-Extra: notebook
Requires-Dist: ipykernel>=7.3.0; extra == "notebook"
Provides-Extra: all
Requires-Dist: py-seaaroundus[dev,maps,plot]; extra == "all"
Dynamic: license-file

# py-seaaroundus

[![PyPI version](https://img.shields.io/pypi/v/py-seaaroundus.svg)](https://pypi.org/project/py-seaaroundus/)
[![Python versions](https://img.shields.io/pypi/pyversions/py-seaaroundus.svg)](https://pypi.org/project/py-seaaroundus/)

Python wrapper for the [Sea Around Us API](http://api.seaaroundus.org), inspired by the R [`rseaaroundus`](https://github.com/robsalasco/rseaaroundus) package. Install as `py-seaaroundus`; import as `seaaroundus`.

Install from [PyPI](https://pypi.org/project/py-seaaroundus/):

```bash
pip install py-seaaroundus
```

Optional extras:

```bash
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](https://creativecommons.org/licenses/by-nc-sa/4.0/). Please read the data use policy in [`DATA_USE`](DATA_USE).

## Quick start

```python
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

```python
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

```python
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

```python
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:

```bash
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`](LICENSE) for more information.
