def get_identifications(**params) -> JsonResponse:
"""Search identifications
.. rubric:: Notes
* API reference: :v1:`GET /identifications <Identifications/get_identifications>`
Example:
Get all of your own species-level identifications:
>>> response = get_identifications(user_login='******', rank='species')
>>> print([f"{i['user']['login']}: {i['taxon_id']} ({i['category']})" for i in response['results']])
[155043569] Species: 76465 (leading) added on 2021-02-15 10:46:27-06:00 by jkcook
[153668189] Species: 76465 (supporting) added on 2021-02-06 17:43:37+00:00 by jkcook
[147500725] Species: 1163860 (improving) added on 2020-12-24 23:52:30+00:00 by jkcook
...
.. admonition:: Example Response
:class: toggle
.. literalinclude:: ../sample_data/get_identifications.py
Returns:
Response dict containing identification records
"""
params = convert_rank_range(params)
if params.get('page') == 'all':
identifications = paginate_all(get_v1, 'identifications', **params)
else:
identifications = get_v1('identifications', **params).json()
identifications['results'] = convert_all_timestamps(
identifications['results'])
return identifications
def get_observation_taxonomy(user_id: IntOrStr = None,
**params) -> JsonResponse:
"""Get observation counts for all taxa in a full taxonomic tree. In the web UI, these are used
for life lists.
Args:
user_id: iNaturalist user ID or username
Example:
>>> response = get_observation_taxonomy(user_id='my_username')
.. admonition:: Example Response
:class: toggle
.. literalinclude:: ../sample_data/get_observation_taxonomy.json
:language: JSON
Returns:
Response dict containing taxon records with counts
"""
if params.get('page') == 'all':
return paginate_all(get_v1,
'observations/taxonomy',
user_id=user_id,
**params)
else:
return get_v1('observations/taxonomy', user_id=user_id,
**params).json()
def get_observation_species_counts(**params) -> JsonResponse:
"""Get all species (or other 'leaf taxa') associated with observations matching the search
criteria, and the count of observations they are associated with.
**Leaf taxa** are the leaves of the taxonomic tree, e.g., species, subspecies, variety, etc.
.. rubric:: Notes
* API reference: :v1:`GET /observations/species_counts <Observations/get_observations_species_counts>`
Example:
>>> response = get_observation_species_counts(user_login='******', quality_grade='research')
>>> pprint(response)
[62060] Species: Palomena prasina (Green Shield Bug): 10
[84804] Species: Graphosoma italicum (European Striped Shield Bug): 8
[55727] Species: Cymbalaria muralis (Ivy-leaved toadflax): 3
...
.. admonition:: Example Response
:class: toggle
.. literalinclude:: ../sample_data/get_observation_species_counts.py
Returns:
Response dict containing taxon records with counts
"""
if params.get('page') == 'all':
return paginate_all(get_v1, 'observations/species_counts', **params)
else:
return get_v1('observations/species_counts', **params).json()
def get_taxa(**params) -> JsonResponse:
"""Search taxa
.. rubric:: Notes
* API reference: :v1:`GET /taxa <Taxa/get_taxa>`
Example:
>>> response = get_taxa(q='vespi', rank=['genus', 'family'])
>>> pprint(response)
[52747] Family: Vespidae (Hornets, Paper Wasps, Potter Wasps, and Allies)
[92786] Genus: Vespicula
[646195] Genus: Vespiodes
...
.. admonition:: Example Response
:class: toggle
.. literalinclude:: ../sample_data/get_taxa.json
:language: JSON
Returns:
Response dict containing taxon records
"""
params = convert_rank_range(params)
if params.get('page') == 'all':
taxa = paginate_all(get_v1, 'taxa', **params)
else:
taxa = get_v1('taxa', **params).json()
taxa['results'] = convert_all_timestamps(taxa['results'])
return taxa
def get_observations(**params) -> JsonResponse:
"""Search observations
.. rubric:: Notes
* API reference: :v1:`GET /observations <Observations/get_observations>`
Examples:
Get observations of Monarch butterflies with photos + public location info,
on a specific date in the provice of Saskatchewan, CA (place ID 7953):
>>> response = get_observations(
>>> taxon_name='Danaus plexippus',
>>> created_on='2020-08-27',
>>> photos=True,
>>> geo=True,
>>> geoprivacy='open',
>>> place_id=7953,
>>> )
Get basic info for observations in response:
>>> pprint(response)
'[57754375] Species: Danaus plexippus (Monarch) observed by samroom on 2020-08-27 at Railway Ave, Wilcox, SK'
'[57707611] Species: Danaus plexippus (Monarch) observed by ingridt3 on 2020-08-26 at Michener Dr, Regina, SK'
.. admonition:: Example Response
:class: toggle
.. literalinclude:: ../sample_data/get_observations_node.py
Returns:
Response dict containing observation records
"""
validate_multiple_choice_param(params, 'order_by',
V1_OBS_ORDER_BY_PROPERTIES)
if params.get('page') == 'all':
observations = paginate_all(get_v1,
'observations',
method='id',
**params)
else:
observations = get_v1('observations', **params).json()
observations['results'] = convert_all_coordinates(observations['results'])
observations['results'] = convert_all_timestamps(observations['results'])
return observations
def get_all_observations(**params) -> List[JsonResponse]:
"""Deprecated; use ``get_observations(page='all')`` instead"""
msg = "get_all_observations() is deprecated; please use get_observations(page='all') instead"
warn(DeprecationWarning(msg))
return paginate_all(get_observations, method='id', **params)['results']