pyinaturalist.node_api module

Code to access the (read-only, but fast) Node based public iNaturalist API See: http://api.inaturalist.org/v1/docs/

pyinaturalist.node_api.get_all_observations(params: Dict, user_agent: Optional[str] = None) → List[Dict[str, Any]][source]

Like get_observations() but handles pagination so you get all the results in one shot.

Some params will be overwritten: order_by, order, per_page, id_above (do NOT specify page when using this).

Returns

A list of dicts (one entry per observation)

pyinaturalist.node_api.get_geojson_observations(properties: Optional[List[str]] = None, **kwargs) → Dict[str, Any][source]

Get all observation results combined into a GeoJSON FeatureCollection. By default this includes some basic observation properties as GeoJSON Feature properties. The properties argument can be used to override these defaults.

Example

>>> get_geojson_observations(observation_id=16227955, properties=["photo_url"])
{"type": "FeatureCollection",
    "features": [{
            "type": "Feature",
            "geometry": {"type": "Point", "coordinates": [4.360086, 50.646894]},
            "properties": {
                "photo_url": "https://static.inaturalist.org/photos/24355315/square.jpeg?1536150659"
            }
        }
    ]
}
Parameters

  • properties – Properties from observation results to include as GeoJSON properties

  • kwargs – Arguments for get_observations()

Returns

A FeatureCollection containing observation results as Feature dicts.

pyinaturalist.node_api.get_observation(observation_id: int, user_agent: Optional[str] = None) → Dict[str, Any][source]

Get details about an observation.

Parameters

  • observation_id – Observation ID

  • user_agent – a user-agent string that will be passed to iNaturalist.

Returns

A dict with details on the observation

Raises

ObservationNotFound –

pyinaturalist.node_api.get_observations(params: Dict, user_agent: Optional[str] = None) → Dict[str, Any][source]

Search observations. See: http://api.inaturalist.org/v1/docs/#!/Observations/get_observations.

Returns

The parsed JSON returned by iNaturalist (observations in r[‘results’], a list of dicts)

pyinaturalist.node_api.get_taxa(user_agent: Optional[str] = None, min_rank: Optional[str] = None, max_rank: Optional[str] = None, **params) → Dict[str, Any][source]

Given zero to many of following parameters, returns taxa matching the search criteria. See https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa

Parameters

  • q – Name must begin with this value

  • is_active – Taxon is active

  • taxon_id – Only show taxa with this ID, or its descendants

  • parent_id – Taxon’s parent must have this ID

  • rank – Taxon must have this exact rank

  • min_rank – Taxon must have this rank or higher; overrides rank

  • max_rank – Taxon must have this rank or lower; overrides rank

  • rank_level – Taxon must have this rank level. Some example values are 70 (kingdom), 60 (phylum), 50 (class), 40 (order), 30 (family), 20 (genus), 10 (species), 5 (subspecies)

  • id_above – Must have an ID above this value

  • id_below – Must have an ID below this value

  • per_page – Number of results to return in a page. The maximum value is generally 200 unless otherwise noted

  • locale – Locale preference for taxon common names

  • preferred_place_id – Place preference for regional taxon common names

  • only_id – Return only the record IDs

  • all_names – Include all taxon names in the response

Returns

A list of dicts containing taxa results

pyinaturalist.node_api.get_taxa_autocomplete(user_agent: Optional[str] = None, minify: bool = False, **params) → Dict[str, Any][source]

Given a query string, returns taxa with names starting with the search term See: https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa_autocomplete

Note: There appears to currently be a bug in the API that causes per_page to not have any effect.

Parameters

  • q – Name must begin with this value

  • is_active – Taxon is active

  • taxon_id – Only show taxa with this ID, or its descendants

  • rank – Taxon must have this rank

  • rank_level – Taxon must have this rank level. Some example values are 70 (kingdom), 60 (phylum), 50 (class), 40 (order), 30 (family), 20 (genus), 10 (species), 5 (subspecies)

  • per_page – Number of results to return in a page. The maximum value is generally 200 unless otherwise noted

  • locale – Locale preference for taxon common names

  • preferred_place_id – Place preference for regional taxon common names

  • all_names – Include all taxon names in the response

  • minify – Condense each match into a single string containg taxon ID, rank, and name

Returns

A list of dicts containing taxa results

pyinaturalist.node_api.get_taxa_by_id(taxon_id: int, user_agent: Optional[str] = None) → Dict[str, Any][source]

Get one or more taxa by ID. See: https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa_id

Parameters

taxon_id – Get taxa with this ID. Multiple values are allowed.

Returns

A list of dicts containing taxa results

pyinaturalist.node_api.make_inaturalist_api_get_call(endpoint: str, params: Dict, user_agent: Optional[str] = None, **kwargs) → requests.models.Response[source]

Make an API call to iNaturalist.

Parameters

  • endpoint – The name of an endpoint not including the base URL e.g. ‘observations’

  • kwargs – Arguments for requests.request()