pyinaturalist-convert
This package provides tools to convert iNaturalist observation data to and from a wide variety of useful formats. This is mainly intended for use with the iNaturalist API via pyinaturalist, but also works with other data sources.
Complete project documentation can be found at pyinaturalist-convert.readthedocs.io.
Formats
Import
- CSV (From either API results or the iNaturalist export tool)
- JSON (from API results) and GeoJSON
pyinaturalist.Observationobjects- Dataframes, Feather, Parquet, and anything else supported by pandas
- Darwin Core
- iNaturalist GBIF Archive
- iNaturalist Taxonomy Archive
- iNaturalist Open Data on Amazon
- Note: see API Recommended Practices for details on which data sources are best suited to different use cases
Export
- CSV, Excel, and anything else supported by tablib
- Dataframes, Feather, Parquet, and anything else supported by pandas
- Darwin Core
- GeoJSON
- GPX
- SQLite
- SQLite + FTS5 text search for taxonomy and observation text
Installation
Install with pip:
pip install pyinaturalist-convert
Or with conda:
conda install -c conda-forge pyinaturalist-convert
To keep things modular, many format-specific dependencies are not installed by default, so you may need to install some more packages depending on which features you want. Each module's docs lists any extra dependencies needed, and a full list can be found in pyproject.toml.
For getting started, it's recommended to install all optional dependencies:
pip install pyinaturalist-convert[all]
Usage
Export
Get your own observations and save to CSV:
from pyinaturalist import get_observations
from pyinaturalist_convert import *
observations = get_observations(user_id='my_username')
to_csv(observations, 'my_observations.csv')
Or any other supported format:
to_dwc(observations, 'my_observations.dwc')
to_excel(observations, 'my_observations.xlsx')
to_feather(observations, 'my_observations.feather')
to_geojson(observations, 'my_observations.geojson')
to_gpx(observations, 'my_observations.gpx')
to_hdf(observations, 'my_observations.hdf')
to_json(observations, 'my_observations.json')
to_parquet(observations, 'my_observations.parquet')
df = to_dataframe(observations)
Import
Most file formats can be loaded via pyinaturalist_convert.read():
observations = read('my_observations.csv')
observations = read('my_observations.xlsx')
observations = read('my_observations.feather')
observations = read('my_observations.hdf')
observations = read('my_observations.json')
observations = read('my_observations.parquet')
Download
Download the complete research-grade observations dataset:
download_dwca_observations()
And load it into a SQLite database:
load_dwca_observations()
And do the same with the complete taxonomy dataset:
download_dwca_taxa()
load_dwca_taxa()
Load taxonomy data into a full text search database:
load_fts_taxa(languages=['english', 'german'])
And get lightning-fast autocomplete results from it:
ta = TaxonAutocompleter()
ta.search('aves')
ta.search('flughund', language='de')
Feedback
If you have any problems, suggestions, or questions about pyinaturalist-convert, you are welcome to create an issue or discussion. Also, PRs are welcome!
Metadata
Release files for pyinaturalist-convert 0.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyinaturalist_convert-0.9.1.tar.gz | 52.5 kB | With provenance | Details for pyinaturalist_convert-0.9.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyinaturalist_convert-0.9.1-py3-none-any.whl | Python 3 | none | any | Details for pyinaturalist_convert-0.9.1-py3-none-any.whl |
Total release size: 118.3 kB
Release files / pyinaturalist_convert-0.9.1.tar.gz
| Download URL | pyinaturalist_convert-0.9.1.tar.gz |
|---|---|
| Size | 52.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
59774b11761c67887cb599b223516e3e104ed34bab5fdb0a5a40feebe210c23b
|
|
BLAKE2b-256 checksum How to use checksums |
4eb2f2aa19975899f127ef198fb5207cdcba6aab946bae60b8e115cc407530b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / pyinaturalist_convert-0.9.1-py3-none-any.whl
| Download URL | pyinaturalist_convert-0.9.1-py3-none-any.whl |
|---|---|
| Size | 65.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
79359e644053b4f0ca795403fabdb1ccf76593f431c5c27ff753a0c78c7297e0
|
|
BLAKE2b-256 checksum How to use checksums |
f01e00204050279cf9b89b08bba58ccef85563415bc59cd69a4a66da4fb9e6a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logSecurity for pyinaturalist-convert 0.9.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pyinaturalist_convert-0.9.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.