mangru 0.1.0

Python client for the Mangru sensor data API — a planetary network of public environmental sensors.

mangru — Python client for the Mangru sensor data API

Mangru 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 DataFrames (or geopandas GeoDataFrames, with the [geo] extra).

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

Quick start

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 [e-mail].

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.