Metadata-Version: 2.4
Name: mangru
Version: 0.1.0
Summary: Python client for the Mangru sensor data API — a planetary network of public environmental sensors.
Project-URL: Homepage, https://mangru.live
Project-URL: Documentation, https://docs.mangru.live
Project-URL: Repository, https://github.com/saewon-rami-chang/mangru-python
Project-URL: Issues, https://github.com/saewon-rami-chang/mangru-python/issues
Author-email: Sae-won Rami Chang <changrami@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: air-quality,api-client,environmental-data,research,sensors,weather
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: pandas>=2.0
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: responses>=0.24; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: geo
Requires-Dist: geopandas>=0.13; extra == 'geo'
Requires-Dist: shapely>=2.0; extra == 'geo'
Description-Content-Type: text/markdown

# mangru — Python client for the Mangru sensor data API

[Mangru](https://mangru.live) is a planetary network of public environmental
sensors — weather, air quality, hydrology, ocean buoys — aggregated from
33+ public networks worldwide and served through a single API.

This package is a thin synchronous client that returns
[pandas](https://pandas.pydata.org/) DataFrames (or
[geopandas](https://geopandas.org/) GeoDataFrames, with the `[geo]` extra).

```bash
pip install mangru             # core
pip install 'mangru[geo]'      # + GeoDataFrame support
```

## Quick start

```python
from mangru import Client

m = Client(api_key="msk_live_...")   # or set MANGRU_API_KEY env var

# Latest reading from every active METAR airport in a bounding box around Seoul
df = m.readings(network="metar", bbox=(126, 37, 128, 38))
df.head()
#       id network        lat        lng          ts country  air_temp  ...
# 0   RKSI   metar  37.469101  126.450996  1779152400      KR     23.0  ...

# Same query as a GeoDataFrame, ready for plotting
gdf = m.readings(network="metar", bbox=(126, 37, 128, 38), geo=True)
gdf.plot(column="air_temp", legend=True)

# Time series for a single station (last 24 hours)
ts = m.history(network="aws", station="108")
ts.plot(x="ts", y="air_temp")
```

## What you get

| Method                  | Returns                                | Notes                              |
|-------------------------|----------------------------------------|------------------------------------|
| `m.readings(...)`       | DataFrame, one row per station         | Filter by network, bbox, variable  |
| `m.stations(...)`       | DataFrame, station inventory           | No values, just geography          |
| `m.history(network=, station=)` | DataFrame, time series         | One row per timestep               |
| `m.networks()`          | DataFrame, network registry            | Plus `m.network_types()`           |
| `m.variables()`         | DataFrame, variable registry           | Canonical units                    |
| `m.status()`            | DataFrame, per-network freshness       | No API key required                |

Any method that returns a DataFrame of readings or stations accepts
`format="long"` (one row per station × variable) and `geo=True`
(GeoDataFrame, requires `[geo]` extra). Pagination is automatic; pass
`paginate=False` to fetch only the first page.

## Getting a key

This project is in its early phase and not yet open for general key
issuance. For inquiries, contact <changrami@gmail.com>.

## Documentation

Full API reference, including all filter parameters and response fields,
is at <https://docs.mangru.live>.

## Citing

If you use Mangru data in published research, please cite Mangru
alongside the original upstream network for each source — see the
"Data sources and attribution" section of the docs for the full list
with attribution URLs.

## License

MIT. Mangru aggregates data from many upstream networks; each operates
under its own license and Mangru passes their data through without
re-licensing. See the docs for per-network attribution requirements.