High-level Python clients for discovering, filtering, previewing, and retrieving
ecological field data from the TERN EcoPlots Portal.
Supports two operational modes — observations and samples — and returns
tidy structures ready for analysis (geojson, pandas.DataFrame, geopandas.GeoDataFrame).
- 🔬 Two modes: observations (ecological plots) and samples (physical specimens)
- 🔎 Validated, human-friendly filters with fuzzy name resolution
- ⚡ Preview result pages before committing to full downloads
- 🗺️ Interactive spatial selection widget (draw a polygon on a map)
- 🧭 Two clients: synchronous
EcoPlotsand asynchronousAsyncEcoPlots - 💾 Save / load projects via
.ecoprojfiles for reproducible workflows
Documentation: https://terndata-ecoplots.readthedocs.io
pip install terndata.ecoplots
Supported Python: 3.10+
Retrieve ecological observation data — site visits, feature types, and measured properties — across Australia's TERN monitoring network.
from terndata.ecoplots import EcoPlots
ec = EcoPlots() # mode="observations" by default
ec.select(dataset="TERN Surveillance",
site_id="TCFTNS0002")
ec.preview() # quick look (first page)
gdf = ec.get_data() # full pull as GeoDataFrameRetrieve physical specimens — soil pit samples, plant voucher specimens, plant tissue samples, and more — with access to IGSN identifiers and sample images.
from terndata.ecoplots import EcoPlots
ec = EcoPlots(mode="samples")
ec.select(material_sample_type="Plant Voucher Specimen",
has_images=True)
df = ec.get_data(dformat="pd")Note: In samples mode the TERN Ecosystem Surveillance dataset is applied automatically and cannot be removed.
Both modes provide notebook widgets for interactive data exploration:
| Widget | Mode | Method |
|---|---|---|
| Spatial selector | Both | ec.select_spatial() |
| IGSN viewer | Samples | ec.view_sample_igsn() |
| Sample image viewer | Samples | ec.view_sample_images() |
from terndata.ecoplots import AsyncEcoPlots
ec = AsyncEcoPlots()
ec.select(site_id="TCFTNS0002")
gdf = await ec.get_data() # non-blocking fetch| Mode | Notebook |
|---|---|
| Observations | examples/demo.ipynb |
| Samples | examples/demo_samples.ipynb |
- 📚 Docs: https://terndata-ecoplots.readthedocs.io/en/latest/
- 🧭 EcoPlots Portal: https://ecoplots.tern.org.au
- 🧑💻 Source: https://github.com/ternaustralia/terndata.ecoplots
- 📦 PyPI: https://pypi.org/project/terndata.ecoplots/
Issues and pull requests are welcome — please open an issue to discuss substantial changes.
Build docs locally:
pip install -r docs/requirements.txt
make -C docs html
Run tests:
make test
Build wheels locally:
make build
For questions or issues, email esupport@tern.org.au.
Terrestrial Ecosystem Research Network (2026). terndata.ecoplots: A Python package for accessing TERN EcoPlots data. https://pypi.org/project/terndata.ecoplots/
Licensed under the terms in LICENSE.
Copyright © 2026 TDSA (TERN Data Services and Analytics).
Author: Avinash Chandra.