Identifications

Summary

Classes

Functions

get_identifications(current_taxon, ...)	Search identifications
get_identifications_by_id(identification_id, ...)	Get one or more identification records by ID

Module Contents

pyinaturalist.v1.identifications.get_identifications(current_taxon, own_observation, is_change, taxon_active, observation_taxon_active, id, ...) → dict[str, Any]

Search identifications

Notes

• API reference: GET /identifications

Parameters:

• current_taxon (bool | None) – ID’s taxon is the same it’s observation’s taxon

• own_observation (bool | None) – ID was added by the observer

• is_change (bool | None) – ID was created as a results of a taxon change

• taxon_active (bool | None) – ID’s taxon is currently an active taxon

• observation_taxon_active (bool | None) – Observation’s taxon is currently an active taxon

• id (int | Iterable[int] | None) – Identification ID

• rank (str | Iterable[str] | None) – ID’s taxon must have this rank # Multiple choice

• observation_rank (str | Iterable[str] | None) – Observation’s taxon must have this rank # Multiple choice

• user_id (int | Iterable[int] | str | Iterable[str] | None) – Identifier must have this user ID

• user_login (str | Iterable[str] | None) – Identifier must have this user login

• current (bool | None) – Most recent Identification on a observation by a user

• category (Union[Literal['improving', 'supporting', 'leading', 'maverick'], Iterable[Literal['improving', 'supporting', 'leading', 'maverick']], None]) – Type of identification

• place_id (int | Iterable[int] | None) – Observation must occur in this place

• quality_grade (Union[Literal['casual', 'needs_id', 'research'], Iterable[Literal['casual', 'needs_id', 'research']], None]) – Observation must have this quality grade

• taxon_id (int | Iterable[int] | None) – Identification taxa must match the given taxa or their descendants

• observation_taxon_id (int | Iterable[int] | None) – Observation taxa must match the given taxa or their descendants

• iconic_taxon_id (int | Iterable[int] | None) – Identification iconic taxon ID

• observation_iconic_taxon_id (int | Iterable[int] | None) – Observation iconic taxon ID

• lrank (str | None) – Identification taxon must have this rank or higher

• hrank (str | None) – Identification taxon must have this rank or lower

• observation_lrank (str | None) – Observation taxon must have this rank or higher

• observation_hrank (str | None) – Observation taxon must have this rank or lower

• without_taxon_id (int | Iterable[int] | None) – Exclude Identifications of these taxa and their descendants

• without_observation_taxon_id (int | Iterable[int] | None) – Exclude Identifications of observations of these taxa and their descendants

• d1 (date | datetime | str | None) – Must be observed on or after this date

• d2 (date | datetime | str | None) – Must be observed on or before this date

• observation_created_d1 (date | datetime | str | None) – Observation must be created on or after this date

• observation_created_d2 (date | datetime | str | None) – Observation must be created on or before this date

• observed_d1 (date | datetime | str | None) – Observation must be observed on or after this date

• observed_d2 (date | datetime | str | None) – Observation must be observed on or before this date

• id_above (int | None) – Must have an ID above this value

• id_below (int | None) – Must have an ID below this value

• page (int | None) – Page number of results to return

• per_page (int | None) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted

• order (Optional[Literal['asc', 'desc']]) – Sort order

• order_by (str | None) – Field to sort on

• count_only (bool | None) – Only return a count of results; alias for per_page=0

• reverse (bool | None) – Reverse the order of results; alias for order='descending'

• only_id (bool | None) – Return only the record IDs

• dry_run (bool | None) – Just log the request instead of sending a real request

• session (Session | None) – An existing Session object to use instead of creating a new one

Example

Get all of your own species-level identifications:

>>> response = get_identifications(user_login='my_username', 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
...

Example Response

from datetime import datetime

from dateutil.tz import tzoffset

{
    'total_results': 873,
    'page': 1,
    'per_page': 2,
    'results': [
        {
            'id': 155554373,
            'uuid': '88031477-a183-46c6-8de3-06bac7b5f220',
            'user': {
                'id': 2115051,
                'login': 'jkcook',
                'spam': False,
                'suspended': False,
                'created_at': '2019-08-10T17:52:01+00:00',
                'login_autocomplete': 'jkcook',
                'login_exact': 'jkcook',
                'name': 'Jordan Cook',
                'name_autocomplete': 'Jordan Cook',
                'orcid': None,
                'icon': 'https://static.inaturalist.org/attachments/users/icons/2115051/thumb.jpeg?1591994381',
                'observations_count': 706,
                'identifications_count': 542,
                'journal_posts_count': 0,
                'activity_count': 1248,
                'species_count': 357,
                'universal_search_rank': 706,
                'roles': [],
                'site_id': 1,
                'icon_url': 'https://static.inaturalist.org/attachments/users/icons/2115051/medium.jpeg?1591994381',
            },
            'created_at': datetime(2021, 2, 18, 20, 31, 32, tzinfo=tzoffset(None, -21600)),
            'created_at_details': {
                'date': '2021-02-18',
                'day': 18,
                'month': 2,
                'year': 2021,
                'hour': 20,
                'week': 7,
            },
            'body': None,
            'category': 'supporting',
            'current': True,
            'flags': [],
            'own_observation': True,
            'taxon_change': None,
            'vision': False,
            'disagreement': False,
            'previous_observation_taxon_id': 60132,
            'spam': False,
            'taxon_id': 60132,
            'hidden': False,
            'current_taxon': True,
            'taxon': {
                'id': 60132,
                'rank': 'species',
                'rank_level': 10,
                'iconic_taxon_id': 47126,
                'ancestor_ids': [
                    47126,
                    211194,
                    47125,
                    47124,
                    47605,
                    47604,
                    201654,
                    632883,
                    632885,
                    48561,
                    60132,
                ],
                'is_active': True,
                'min_species_taxon_id': 60132,
                'min_species_ancestry': '47126,211194,47125,47124,47605,47604,201654,632883,632885,48561,60132',
            },
            'observation': 'TRUNCATED',
            'moderator_actions': [],
            'observed_on': None,
        },
        {
            'id': 155554077,
            'uuid': '12922da1-a203-46f2-b0f2-fd21917b4b07',
            'user': {
                'id': 2115051,
                'login': 'jkcook',
                'spam': False,
                'suspended': False,
                'created_at': '2019-08-10T17:52:01+00:00',
                'login_autocomplete': 'jkcook',
                'login_exact': 'jkcook',
                'name': 'Jordan Cook',
                'name_autocomplete': 'Jordan Cook',
                'orcid': None,
                'icon': 'https://static.inaturalist.org/attachments/users/icons/2115051/thumb.jpeg?1591994381',
                'observations_count': 706,
                'identifications_count': 542,
                'journal_posts_count': 0,
                'activity_count': 1248,
                'species_count': 357,
                'universal_search_rank': 706,
                'roles': [],
                'site_id': 1,
                'icon_url': 'https://static.inaturalist.org/attachments/users/icons/2115051/medium.jpeg?1591994381',
            },
            'created_at': datetime(2021, 2, 18, 20, 29, 6, tzinfo=tzoffset(None, -21600)),
            'created_at_details': {
                'date': '2021-02-18',
                'day': 18,
                'month': 2,
                'year': 2021,
                'hour': 20,
                'week': 7,
            },
            'body': None,
            'category': 'supporting',
            'current': True,
            'flags': [],
            'own_observation': True,
            'taxon_change': None,
            'vision': False,
            'disagreement': False,
            'previous_observation_taxon_id': 61340,
            'spam': False,
            'taxon_id': 61340,
            'hidden': False,
            'current_taxon': True,
            'taxon': {
                'id': 61340,
                'rank': 'species',
                'rank_level': 10,
                'iconic_taxon_id': 47126,
                'ancestor_ids': [
                    47126,
                    211194,
                    47125,
                    47124,
                    47605,
                    47604,
                    201654,
                    632883,
                    632885,
                    48561,
                    61340,
                ],
                'is_active': True,
                'min_species_taxon_id': 61340,
                'min_species_ancestry': '47126,211194,47125,47124,47605,47604,201654,632883,632885,48561,61340',
            },
            'observation': 'TRUNCATED',
            'moderator_actions': [],
            'observed_on': None,
        },
    ],
}

Return type:

dict[str, Any]

Returns:

Response dict containing identification records

pyinaturalist.v1.identifications.get_identifications_by_id(identification_id, **params) → dict[str, Any]

Get one or more identification records by ID

Notes

• API reference: GET /identifications/{id}

Example

>>> get_identifications_by_id(155554373)

Example Response

from datetime import datetime

from dateutil.tz import tzoffset

{
    'total_results': 873,
    'page': 1,
    'per_page': 2,
    'results': [
        {
            'id': 155554373,
            'uuid': '88031477-a183-46c6-8de3-06bac7b5f220',
            'user': {
                'id': 2115051,
                'login': 'jkcook',
                'spam': False,
                'suspended': False,
                'created_at': '2019-08-10T17:52:01+00:00',
                'login_autocomplete': 'jkcook',
                'login_exact': 'jkcook',
                'name': 'Jordan Cook',
                'name_autocomplete': 'Jordan Cook',
                'orcid': None,
                'icon': 'https://static.inaturalist.org/attachments/users/icons/2115051/thumb.jpeg?1591994381',
                'observations_count': 706,
                'identifications_count': 542,
                'journal_posts_count': 0,
                'activity_count': 1248,
                'species_count': 357,
                'universal_search_rank': 706,
                'roles': [],
                'site_id': 1,
                'icon_url': 'https://static.inaturalist.org/attachments/users/icons/2115051/medium.jpeg?1591994381',
            },
            'created_at': datetime(2021, 2, 18, 20, 31, 32, tzinfo=tzoffset(None, -21600)),
            'created_at_details': {
                'date': '2021-02-18',
                'day': 18,
                'month': 2,
                'year': 2021,
                'hour': 20,
                'week': 7,
            },
            'body': None,
            'category': 'supporting',
            'current': True,
            'flags': [],
            'own_observation': True,
            'taxon_change': None,
            'vision': False,
            'disagreement': False,
            'previous_observation_taxon_id': 60132,
            'spam': False,
            'taxon_id': 60132,
            'hidden': False,
            'current_taxon': True,
            'taxon': {
                'id': 60132,
                'rank': 'species',
                'rank_level': 10,
                'iconic_taxon_id': 47126,
                'ancestor_ids': [
                    47126,
                    211194,
                    47125,
                    47124,
                    47605,
                    47604,
                    201654,
                    632883,
                    632885,
                    48561,
                    60132,
                ],
                'is_active': True,
                'min_species_taxon_id': 60132,
                'min_species_ancestry': '47126,211194,47125,47124,47605,47604,201654,632883,632885,48561,60132',
            },
            'observation': 'TRUNCATED',
            'moderator_actions': [],
            'observed_on': None,
        },
        {
            'id': 155554077,
            'uuid': '12922da1-a203-46f2-b0f2-fd21917b4b07',
            'user': {
                'id': 2115051,
                'login': 'jkcook',
                'spam': False,
                'suspended': False,
                'created_at': '2019-08-10T17:52:01+00:00',
                'login_autocomplete': 'jkcook',
                'login_exact': 'jkcook',
                'name': 'Jordan Cook',
                'name_autocomplete': 'Jordan Cook',
                'orcid': None,
                'icon': 'https://static.inaturalist.org/attachments/users/icons/2115051/thumb.jpeg?1591994381',
                'observations_count': 706,
                'identifications_count': 542,
                'journal_posts_count': 0,
                'activity_count': 1248,
                'species_count': 357,
                'universal_search_rank': 706,
                'roles': [],
                'site_id': 1,
                'icon_url': 'https://static.inaturalist.org/attachments/users/icons/2115051/medium.jpeg?1591994381',
            },
            'created_at': datetime(2021, 2, 18, 20, 29, 6, tzinfo=tzoffset(None, -21600)),
            'created_at_details': {
                'date': '2021-02-18',
                'day': 18,
                'month': 2,
                'year': 2021,
                'hour': 20,
                'week': 7,
            },
            'body': None,
            'category': 'supporting',
            'current': True,
            'flags': [],
            'own_observation': True,
            'taxon_change': None,
            'vision': False,
            'disagreement': False,
            'previous_observation_taxon_id': 61340,
            'spam': False,
            'taxon_id': 61340,
            'hidden': False,
            'current_taxon': True,
            'taxon': {
                'id': 61340,
                'rank': 'species',
                'rank_level': 10,
                'iconic_taxon_id': 47126,
                'ancestor_ids': [
                    47126,
                    211194,
                    47125,
                    47124,
                    47605,
                    47604,
                    201654,
                    632883,
                    632885,
                    48561,
                    61340,
                ],
                'is_active': True,
                'min_species_taxon_id': 61340,
                'min_species_ancestry': '47126,211194,47125,47124,47605,47604,201654,632883,632885,48561,61340',
            },
            'observation': 'TRUNCATED',
            'moderator_actions': [],
            'observed_on': None,
        },
    ],
}

Parameters:

identification_id (int | Iterable[int]) – Get taxa with this ID. Multiple values are allowed.

Return type:

dict[str, Any]

Returns:

Response dict containing identification records