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']