Metadata-Version: 2.4
Name: sondio
Version: 0.1.2
Summary: Python SDK for the Sondio data platform — energy and environmental data as pandas DataFrames.
Project-URL: Homepage, https://sondio.io
Project-URL: Documentation, https://sondio.io/developers
Project-URL: Repository, https://github.com/sondio-io/sondio-python
Author-email: Sondio <dev@sondio.io>
License-Expression: MIT
License-File: LICENSE
Keywords: api,energy,environmental,geospatial,pandas,sdk,sondio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pandas>=2.0
Provides-Extra: all
Requires-Dist: geopandas>=0.14; extra == 'all'
Requires-Dist: shapely>=2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: geopandas>=0.14; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: shapely>=2.0; extra == 'dev'
Provides-Extra: geo
Requires-Dist: geopandas>=0.14; extra == 'geo'
Requires-Dist: shapely>=2.0; extra == 'geo'
Description-Content-Type: text/markdown

# sondio

Python SDK for the [Sondio](https://sondio.io) data platform. Energy and
environmental data as pandas DataFrames.

```bash
pip install sondio              # core
pip install 'sondio[geo]'       # adds geopandas for boundary polygons
```

## Quickstart

```python
import sondio

sondio.api_key = "sk_sondio_..."  # or set SONDIO_API_KEY

# Vertical-rule datasets — country is a parameter, not a prefix
wells    = sondio.oilgas.wells(country="US", state="TX", basin="permian")
prod     = sondio.oilgas.production(wells.iloc[0]["external_id"], months=120)
quakes   = sondio.earthquakes(state="TX", min_mag=3.0, days=30)
turbines = sondio.wind_turbines(state="TX", min_year=2020)
rails    = sondio.rail_lines(country="US", state="TX")

# Agency-rule datasets: sondio.<country>.<agency>.<resource>
ae     = sondio.us.epa.aquifer_exemptions(state="TX")
ghg    = sondio.us.ghg.facilities(state="TX")
pl     = sondio.us.phmsa.pipeline_incidents(state="TX")
npdes  = sondio.us.npdes.permits(state="TX")
svi    = sondio.us.cdc.svi_tracts(state="LA", min_rpl=0.9)

# Geographic reference data
states = sondio.geo.subdivisions(country="US")
states_geo = sondio.geo.subdivisions(country="US", with_geometry=True)  # GeoDataFrame
```

Every call returns a `pandas.DataFrame` — or a `geopandas.GeoDataFrame` when
you ask for geometry.

## Configuration

```python
import sondio
sondio.api_key  = "sk_sondio_..."                   # explicit
sondio.base_url = "http://localhost:8791/api/v1"    # dev override
```

Resolution order: explicit attribute → `SONDIO_API_KEY` env var →
`~/.sondio/config` (`[default]` section, `api_key = ...`).

## Pagination

Opt-in to protect against unintentional 3M-row walks:

```python
# First page only (default). Emits a UserWarning if more pages exist.
wells = sondio.oilgas.wells(country="US", state="TX")

# Full iteration
wells = sondio.oilgas.wells(country="US", state="TX", all_pages=True)

# Specific page
wells = sondio.oilgas.wells(country="US", state="TX", page=3)
```

Auto-pagination is capped at 500 pages — hitting the cap raises a warning.

## Type coercion

Several API columns come back as strings (`magnitude`, `depth_ft`,
`total_co2e`). The SDK coerces known numeric/datetime columns per endpoint;
unknown columns pass through untouched.

## Errors

```python
from sondio import SondioError, SondioAPIError

try:
    sondio.earthquakes()
except SondioAPIError as e:
    print(e.status_code, e.body)
except SondioError as e:
    print("config problem:", e)
```

## Namespace shape

Matches the Sondio [dataset naming convention](https://github.com/sondio-io/sondio/blob/main/docs/reference/dataset-naming.md):

| Category                    | Shape                                               | Example                                  |
|-----------------------------|-----------------------------------------------------|------------------------------------------|
| Vertical-rule               | `sondio.<vertical>.<resource>(country=...)`          | `sondio.oilgas.wells(country="US")`      |
| Vertical-rule, global       | `sondio.<resource>(...)`                             | `sondio.earthquakes(...)`                |
| Agency-rule                 | `sondio.<country>.<agency>.<resource>(...)`          | `sondio.us.epa.aquifer_exemptions(...)`  |
| Geographic reference        | `sondio.geo.<resource>(...)`                         | `sondio.geo.subdivisions(...)`           |

## License

MIT — see [LICENSE](LICENSE).
