Detailed API Documentation

Module read

inattrails.read.readGpx(file_names: List[str]) → Tuple[shapely.geometry.MultiLineString, Tuple[Tuple[float, float], Tuple[float, float]]]

Reads .gpx files of tracks and returns a MultiLineString and the bounding box.

Parameters:

file_names (List[str]) – list of .gpx file names

Returns:

a tuple consisting of a MultiLineString instance and the bounding box

Module cache

inattrails.cache.OBSERVATION_EXPIRATION = 28800

8 hours in seconds

inattrails.cache.PLACES_EXPIRATION = 604800

1 week in seconds

inattrails.cache.TAXA_EXPIRATION = 1209600

2 weeks in seconds

inattrails.cache.TRAILS_EXPIRATION = 2419200

4 weeks in seconds

inattrails.cache.defaultHook(obj)

Called by writeJson() to convert type datetime.datetime to string.

inattrails.cache.readJson(file_name: str)

Read json data from file.

Parameters:

file_name (str) – Name of file to read json data from.

Returns:

json (list or dict)

inattrails.cache.scale_bbox(bbox: Tuple[Tuple[float, float], Tuple[float, float]], precision: int)

Scale a bounding box to a given precision. Call with precision=100 to scale to lat/lon precision of two decimals. Returns scaled bounding box.

Parameters:

  • bbox (pair of two pairs, the min longitude and latitude and the max longitude and latitude) – bounding box

  • precision (int, a power of 10) – the precision, number of decimals desired

inattrails.cache.writeJson(file_name: str, data)

Write json data to file.

Parameters:

  • file_name (str) – Name of file to write json data to.

  • data (json (list or dict)) – json data

Module api

class inattrails.api.iNaturalistAPI

This class issues iNaturalist API calls and overpass API calls in parallel using asyncio.

CALL_LIMIT = 60

Limit of API calls/minute.

DOWNLOAD_LIMIT = 10000

At most 10,000 observations can be obtained.

PER_PAGE = 200

Maximal 200 observations/page.

async api_call(cmd, **params) → None

Make an API call to iNaturalist and overpass API’s.

Parameters:

  • cmd (str) – The command to send to the API, e.g. ‘obervations’

  • params (Dict[str, object]) – dict of parameters to send to iNaturalist API.

getResults()

Return result obtained by API command.

Returns:

a string from the overpass API or a list of json results from iNaturalist.

get_all_observations(**params)

Method to get multiple pages of iNaturalist observations. All pages will be combined in one list and can be obtained with getResults().

Returns:

list of json results from iNaturalist.

async get_all_observations_async(params) → None

Asynchronous method to get multiple pages of iNaturalist observations.

Returns:

a string from the overpass API or a json list from iNaturalist.

get_overpass(query: str) → str

Query the overpass API.

Parameters:

query (str) – the overpass query, a string

Returns:

str

get_places_by_id(id: int | Set[int])

Get places by numeric id.

Parameters:

id (Union[int, Set[int]]) – numeric place id or set of numeric place ids

Returns:

a list of iNaturalist json results

async get_places_by_id_async(id: int | str | Set[int], params: Dict[str, int]) → None

Get places by numeric id.

Parameters:

  • id (Union[int, Set[int]]) – numeric place id or set of numeric place ids

  • params (Dict[str, object]) – dict of parameters to send to iNaturalist API.

get_places_nearby(**params)

Get places nearby.

Parameters:

params (Dict[str, object]) – dict of parameters to send to iNaturalist API.

Returns:

a list of iNaturalist json results

async get_places_nearby_async(params) → None

Get places nearby.

Parameters:

params (Dict[str, object]) – dict of parameters to send to iNaturalist API.

get_taxa_by_id(ids: List[str], **params) → List[Dict[str, object]]

Method to get iNaturalist taxa by id. ids is a list of numeric taxon ids. params are parameters to pass to the iNaturalist API. This function returns a list of json dicts for the taxa.

Parameters:

  • ids (List[str]) – List of numeric taxon ids.

  • params (Dict[str, object]) – dict of parameters to send to iNaturalist API.

Returns:

a list of iNaturalist json results

async get_taxa_by_id_async(ids: List[str], params) → None

Asynchronous method to get taxa by id. ids is a list of numeric taxon ids. params are parameters to pass to the iNaturalist API.

iNaturalist returns up to 30 taxa in one call. This function breaks down ids into chunks of not more than 30 taxa and sends those to the iNaturalist API.

Parameters:

  • ids (List[str]) – List of numeric taxon ids.

  • params (Dict[str, object]) – dict of parameters to send to iNaturalist API.

initCommand() → None

Initalize for one API command. An single API command may request multiple pages.

async throttleCalls() → None

Limit us to 60 API calls per minute.

Module trails

class inattrails.trails.Trails(bbox: Tuple[Tuple[float, float], Tuple[float, float]], bufferPolygon: shapely.geometry.Polygon)

Class Trails downloads all named roads and trails within the bounding box from the overpass API or our local cache. It intersects these roads and trails with the buffer polygon. It inserts non-empty intersections into an STRTree that allows us to look up the closest trail for given coordinates.

Parameters:

  • bbox (tuple consiting of two pairs, a pair of the min longitude and min latitude and other pair of the max longitude and max latitude) –

  • bufferPolygon (shapely.geometry.Polygon) – buffer polygon around the tracks of the hike

nearestTrail(lat: float, lon: float) → str | None

Return name of nearest trails to (lat, lon) or None.

Parameters:

  • lat (float) – latitude

  • lon (float) – latitude

Returns:

name of nearest trails or None

Module inat_taxon

class inattrails.inat_taxon.Taxon(id: int, name: str, common_name: str, square_url: str, iconic: str)

This class stores an iNaturalist taxon.

Parameters:

  • id (int) – numeric taxon id

  • name (str) – scientific name

  • common_name (str or None) – common name or None

  • square_url (str or None) – URL to a load thumbnail image for this taxon

  • iconic (str) – this taxon’s iconic taxon

add_observation(observation: Observation)

Append an observation to this taxon’s list of observations.

Parameters:

observation (Observation) – an instance of class Observation

html_name(with_common_name=False) → str

Return the html-formatted name for this taxon, the scientific name italicized as a whole or in parts. Optionally, append the common name in parentheses.

Parameters:

with_common_name (bool) – If True append the common name in parentheses.

inattrails.inat_taxon.taxonInfo(taxon: Dict[str, object]) → Tuple[int, str, str, str, str]

Extract components for class Taxon from json downloaded from iNaturalist.

Parameters:

taxon (dict) – json data for taxon obtained from iNaturalist API

Returns:

5-tuple consisting of taxon id, scientific name, common name or None, url for thumbnail image, name of iconic taxon

Module inat_status

class inattrails.inat_status.Status(means: str, place: int | str)

Status consists of an establishment means and a place.

means: str

establishment means, e.g. ‘native’ or ‘introduced’

place: int | str

place name or numeric place id

inattrails.inat_status.listedTaxa(taxon, places: List[Place]) → Status | None

Get the status of a taxon - like introduced or native - for a list of places.

Parameters:

  • taxon (list of dict) – iNaturalist taxon in json

  • places (list of Place) – list of places

Returns:

list of Status

Module inat_place

class inattrails.inat_place.Place(id: int, name: str, bbox_area: float, geometry_geojson: dict, ancestor_place_ids: List[int])

Class Place represents a named place.

ancestor_place_ids: List[int]

place ids of this place’s ancestors

bbox_area: float

area of the bounding box

geometry_geojson: dict

geojson of the place

id: int

numeric place id

name: str

place name

inattrails.inat_place.getPlacesById(id: int | Set[int]) → List[Place]

Get single place or multiple places by numeric id.

Parameters:

id (int or set of int) – numeric place id or set of numeric place ids

Returns:

a list of instances of class Place in increasing order of bbox area

inattrails.inat_place.getPlacesNearby(bbox: Tuple[Tuple[float, float], Tuple[float, float]], bufferPolygon: shapely.geometry.Polygon) → List[Place]

Download list of places for given bounding box. Return list of those that intersect buffer polygon.

Parameters:

  • bbox (pair of two pairs, the min longitude and latitude and the max longitude and latitude) – bounding box

  • bufferPolygon (shapely.geometry.Polygon) – buffer polygon around the tracks of the hike

Returns:

a list of instances of class Place in increasing order of bbox area

Module inat_observation

inattrails.inat_observation.ACCURACY = 25

observation accuracy in meters; skip less accurate observations

class inattrails.inat_observation.Observation(id: int, obscured: bool, accuracy: float | None, lat: float, lon: float, date: datetime, login: str, user: str, quality: str, trail: str | None)

This class represents a single iNaturalist observation.

Parameters:

  • id (int) – numeric observation id

  • obscured (bool) – is the locatin obscured?

  • accuracy (float or None) – location accuracy in meters or None

  • lat (float) – latitude

  • lon (float) – longitude

  • date (str) – date is ISO format

  • login (str) – login name of user who made this observation

  • user (str) – user name if there is one, login name otherwise

  • quality (str) – observation’s quality-grade: casual, needs_id, research

  • trail (str or None) – trail name or - for off-trail observations - None

inattrails.inat_observation.ancestorInfo(bbox: Tuple[Tuple[float, float], Tuple[float, float]], observations: List[Taxon], bufferPolygon: shapely.geometry.Polygon) → Tuple[List[Taxon], str]

For a list of taxa with observations, return if list of iconic taxa and a suggestion for the place name.

The iconc taxa are roots of trees. Each iconic taxon has children which are families. The children of these families are the leaf taxa with observations. The lists of iconic taxa, lists of families and lists of leaf taxa are all sorted by scientific names in alphabetical order.

Parameters:

  • bbox (pair of two pairs, the min longitude and latitude and the max longitude and latitude) – bounding box

  • observations – list of taxa; each taxon has a list of observations

  • observations – list of instances of Taxon

  • bufferPolygon (shapely.geometry.Polygon) – buffer polygon around the tracks of the hike

Returns:

tuple consisting of a list of iconic taxa; the children of these iconic taxa are taxa of families; the children of the taxa of families contain the observations and a suggestion for the place name

inattrails.inat_observation.getObservations(bbox: Tuple[Tuple[float, float], Tuple[float, float]], bufferPolygon: shapely.geometry.Polygon, iconic_taxa: str, quality_grade: str, month: bool, trails: Trails) → Tuple[List[Taxon], str]

Returns trees of taxa. Observations are stored at the taxa. Each list of taxa is alphabetically ordered by scientific name. Taxa contain lists of observations.

Parameters:

  • bbox (pair of two pairs, the min longitude and latitude and the max longitude and latitude) – bounding box

  • bufferPolygon (shapely.geometry.Polygon) – buffer polygon around the tracks of the hike

  • quality_grade (str) – ‘all’ or ‘casual’, ‘needs_id’, ‘research’

  • month (bool) – download observations only of current, previous and next months

  • trails (Trails) – instance of class Trails to lookup trail name

Returns:

tuple consisting of a list of iconic taxa; the children of these iconic taxa are taxa of families; the children of the taxa of families contain the observations and a suggestion for the place name

inattrails.inat_observation.iconic_taxa2color = {'Actinopterygii': 'blue', 'Amphibia': 'blue', 'Animalia': 'blue', 'Arachnida': 'red', 'Aves': 'blue', 'Chromista': 'darkred', 'Fungi': 'purple', 'Insecta': 'red', 'Mammalia': 'blue', 'Mollusca': 'red', 'Plantae': 'green', 'Protozoa': 'purple', 'Reptilia': 'blue'}

Color coding for iNaturalist iconic taxa.

inattrails.inat_observation.quality_grades = ['casual', 'needs_id', 'research']

Quality grades of iNaturalist observations.

Module gen_map

inattrails.gen_map.getMap(bbox: Tuple[Tuple[float, float], Tuple[float, float]], iconic_taxa: List[Taxon], lineStrings: shapely.geometry.MultiLineString, bufferPolygon: shapely.geometry.Polygon) → folium.Map

Based on folium write an interactive map to an html file and open it in a browser.

Parameters:

  • bbox (pair of two pairs, the min longitude and latitude and the max longitude and latitude) – bounding box

  • iconic_taxa (list of instances of Taxon) – list of iconic taxa; the children of iconic taxa are taxa of families; the children of those families are taxa that contain observations

  • lineStrings (shapely.geometry.MultiLineString) – the track of a hike represented as line strings

  • bufferPolygon (shapely.geometry.Polygon) – buffer polygon around the tracks of the hike

Module write_table

inattrails.write_table.writeTable(iconic_taxa: List[Taxon], iconic_taxa_arg: str, quality_grade: str, month: bool, place_name: str, logins: bool) → None

Write html table of observations and the trails they are found on.

Parameters:

  • iconic_taxa (list of instances of Taxon) – list of iconic taxa; the children of iconic taxa are taxa of families; the children of those families are taxa that contain observations

  • iconic_taxa_arg (str) – the iconic taxon from the command-line, used in file name

  • quality_grade (str) – ‘all’ or ‘casual’, ‘needs_id’, ‘research’; used in file name

  • month (bool) – parameter month from command-line; used in file name

  • place_name (str) – place name used in file name

  • logins (bool) – if True use observer’s login name in table; use numeric observation id if False

Module write_waypoint

inattrails.write_waypoints.writeWaypoints(iconic_taxa: List[Taxon], iconic_taxa_arg: str, quality_grade: str, place_name: str) → None

Write waypoints for off-line mapping app OsmAnd on iPhone and Android.

Parameters:

  • iconic_taxa (list of instances of Taxon) – list of iconic taxa; the children of iconic taxa are taxa of families; the children of those families are taxa that contain observations

  • iconic_taxa_arg (str) – the iconic taxon from the command-line, used in file name

  • quality_grade (str) – ‘all’ or ‘casual’, ‘needs_id’, ‘research’; used in file name

  • place_name (str) – place name used in file name

Module main

inattrails.main.fileName(fn: str) → str

Is argument a valid filename?

Parameters:

fn (str) – file name

Raises:

argparse.ArgumentTypeError – if the argument is not a valid file name

Returns:

fn

inattrails.main.iconicTaxa(iconic: str) → str

Is iconic a valid iconic taxon?

Parameters:

iconic (str) – ‘all’ or ‘Actinopterygii’, …

Raises:

argparse.ArgumentTypeError – if the argument is not ‘all’ or a valid iconic taxon

Returns:

‘all’ or iconic with first letter capitalized

inattrails.main.main()

Main program, parses command line, reads gps tracks, computes buffer polygon, downloads road and trails, downloads observations, writes waypoints, table, and map.

inattrails.main.qualityGrade(quality: str) → str

Is quality a valid quality-grade?

Parameters:

quality (str) – ‘casual’, ‘needs_id’, ‘research’, or ‘all’

Raises:

argparse.ArgumentTypeError – if the argument is not ‘all’ or a valid quality grade

Returns:

quality in lower case