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 formats currently supported:

• CSV (From either API results or the iNaturalist export tool)
• JSON (from API results, either via pyinaturalist, requests, or another HTTP client)
• pyinaturalist.Observation objects
• Parquet

Import formats with partial support:

• iNaturalist open data on Amazon
• iNaturalist GBIF Archive
• iNaturalist Taxonomy Archive

Export formats currently supported:

• CSV, Excel, and anything else supported by tablib
• Feather, Parquet, and anything else supported by pandas
• GeoJSON and GPX
• Darwin Core

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 formats you want. See pyproject.toml for the full list (TODO: docs on optional dependencies).

To install all of the things:

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_gpx(observations, 'my_observations.gpx')
to_hdf(observations, 'my_observations.hdf')
to_parquet(observations, 'my_observations.parquet')
df = to_dataframe(observations)
geo_obs = to_geojson(observations)

Import

Load your observations from the iNat Export tool, convert to be consistent with API results, and save to Parquet:

df = load_csv_exports('my_observations.csv')
df.to_parquet('my_observations.parquet')

Download

Download the complete research-greade observations dataset:

download_dwca()

Or the complete taxonomy dataset:

download_dwca_taxa()

Load taxonomy and common name data into a full text search database:

load_taxon_fts_table(languages=['english', 'german'])

And get lightning-fast autocomplete results from it:

ta = TaxonAutocompleter()
ta.search('aves')
ta.search('flughund', language='german')

Planned and Possible Features

• Convert to an HTML report
• Convert to print-friendly format
• Export to any SQLAlchemy-compatible database engine
• Note: see API Recommended Practices for details on which data sources are best suited to different use cases