pyinaturalist.node_api module¶

Code to access the Node-based iNaturalist API See: http://api.inaturalist.org/v1/docs/

Most recent API version tested: 1.3.0

Functions¶

`get_controlled_terms`	List controlled terms and their possible values.
`get_identifications_by_id`	Get one or more identification records by ID.
`get_identifications`	Search identifications.
`get_observation`	Get details about a single observation by ID
`get_observation_histogram`	Search observations and return histogram data for the given time interval
`get_observations`	Search observations.
`get_observation_species_counts`	Get all species (or other ‘leaf taxa’) associated with observations matching the search criteria, and the count of observations they are associated with.
`get_geojson_observations`	Get all observation results combined into a GeoJSON `FeatureCollection`.
`get_observation_observers`	Get observers of observations matching the search criteria and the count of observations and distinct taxa of rank species they have observed.
`get_observation_identifiers`	Get identifiers of observations matching the search criteria and the count of observations they have identified.
`get_places_by_id`	Get one or more places by ID.
`get_places_nearby`	Given an bounding box, and an optional name query, return places nearby
`get_places_autocomplete`	Given a query string, get places with names starting with the search term
`get_projects`	Given zero to many of following parameters, get projects matching the search criteria.
`get_projects_by_id`	Get one or more projects by ID.
`get_taxa`	Given zero to many of following parameters, get taxa matching the search criteria.
`get_taxa_by_id`	Get one or more taxa by ID.
`get_taxa_autocomplete`	Given a query string, return taxa with names starting with the search term
`get_user_by_id`	Get a user by ID.
`get_users_autocomplete`	Given a query string, return users with names or logins starting with the search term
`search`	A unified search endpoint for places, projects, taxa, and/or users

pyinaturalist.node_api.get_controlled_terms(taxon_id=None, user_agent=None)[source]¶

List controlled terms and their possible values. A taxon ID can optionally be provided to show only terms that are valid for that taxon. Otherwise, all controlled terms will be returned.

API reference:

Example

>>> response = get_controlled_terms()
>>> print(format_controlled_terms(response))
1: Life Stage
    2: Adult
    3: Teneral
    4: Pupa
...

Example Response (all terms)

{
  "total_results": 4,
  "page": 1,
  "per_page": 30,
  "results": [
    {
      "id": 12,
      "ontology_uri": "",
      "uri": "",
      "is_value": false,
      "multivalued": true,
      "uuid": "e997f5f1-1e22-4f1e-bb51-425d70d07b1a",
      "values": [
        {
          "id": 21,
          "ontology_uri": "",
          "uri": "",
          "blocking": true,
          "uuid": "943f8dac-764a-4736-86b5-2f419bbd368b",
          "taxon_ids": [
            47125
          ],
          "label": "No Evidence of Flowering"
        },
        {
          "id": 13,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "84aa676e-2921-42cf-ae01-034a98425b5c",
          "taxon_ids": [
            47125
          ],
          "label": "Flowering"
        },
        {
          "id": 14,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "503cef8b-770b-4c2d-a0b0-e0ea9f7df465",
          "taxon_ids": [
            47125
          ],
          "label": "Fruiting"
        },
        {
          "id": 15,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "9c9d28a1-4ad3-408e-9f2b-30af803f5eb9",
          "taxon_ids": [
            47125
          ],
          "label": "Flower Budding"
        }
      ],
      "taxon_ids": [
        47126
      ],
      "label": "Plant Phenology"
    },
    {
      "id": 9,
      "ontology_uri": "",
      "uri": "",
      "is_value": false,
      "multivalued": false,
      "uuid": "6a659546-c3aa-45ff-8f6c-0706f2361cfe",
      "values": [
        {
          "id": 10,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "3288a7bd-6ca7-413e-9890-5c4c541331de",
          "label": "Female"
        },
        {
          "id": 11,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "207a8f33-ee23-44c9-88a5-e6a036a7d950",
          "label": "Male"
        },
        {
          "id": 20,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "1e75ade7-f1c2-4ef7-994b-c5b07d52713e",
          "label": "Cannot Be Determined"
        }
      ],
      "excepted_taxon_ids": [
        47170,
        333586,
        63081,
        47113
      ],
      "label": "Sex"
    },
    {
      "id": 17,
      "ontology_uri": "",
      "uri": "",
      "is_value": false,
      "multivalued": false,
      "values": [
        {
          "id": 18,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "label": "Alive"
        },
        {
          "id": 19,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "label": "Dead"
        },
        {
          "id": 20,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "label": "Cannot Be Determined"
        }
      ],
      "taxon_ids": [
        1
      ],
      "label": "Alive or Dead"
    },
    {
      "id": 1,
      "ontology_uri": "",
      "uri": "",
      "is_value": false,
      "multivalued": false,
      "uuid": "f895e9ce-fb2d-4a63-a486-ac424f497e02",
      "values": [
        {
          "id": 2,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "48722062-360d-4b6e-b72c-129c7066b3fa",
          "taxon_ids": [
            1
          ],
          "label": "Adult"
        },
        {
          "id": 3,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "b3b6e6d0-cbce-4886-bb2b-55bd99d44586",
          "taxon_ids": [
            47792,
            50190
          ],
          "label": "Teneral"
        },
        {
          "id": 4,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "c883d7b5-4eb5-4ad1-8cbc-56f5e2555869",
          "taxon_ids": [
            47208,
            48763,
            49369,
            47157,
            47822,
            47201,
            62164,
            47864,
            83204,
            83202,
            47794
          ],
          "label": "Pupa"
        },
        {
          "id": 5,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "0f0c03c2-4741-46db-a19a-7cac8a96d667",
          "taxon_ids": [
            47793,
            81769,
            56834,
            47744,
            47792,
            47651,
            47504,
            48011,
            48112,
            53795,
            47198,
            83187,
            83201,
            83200
          ],
          "label": "Nymph"
        },
        {
          "id": 6,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "8ff477bd-0949-4a7a-9c67-64a8e3786876",
          "taxon_ids": [
            20978,
            47208,
            47822,
            47201,
            47157,
            49369,
            47864,
            48763,
            47794,
            83204,
            83202,
            62164
          ],
          "label": "Larva"
        },
        {
          "id": 7,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "fe58aedb-4375-4096-a61f-1cd718cf319f",
          "taxon_ids": [
            43233,
            47120,
            47114,
            47459,
            85497,
            47178,
            20978,
            3,
            49231,
            47273,
            60450,
            49099,
            26036
          ],
          "label": "Egg"
        },
        {
          "id": 8,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "3245d167-ffff-44ce-a366-cfc8f711d73f",
          "taxon_ids": [
            1
          ],
          "excepted_taxon_ids": [
            184884
          ],
          "label": "Juvenile"
        },
        {
          "id": 16,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "6ff4f9f8-7bc0-4d50-bee5-7072d11a04ef",
          "taxon_ids": [
            48011
          ],
          "label": "Subimago"
        }
      ],
      "taxon_ids": [
        1
      ],
      "label": "Life Stage"
    }
  ]
}

Example Response (for a specific taxon)

{
  "total_results": 1,
  "page": 1,
  "per_page": 30,
  "results": [
    {
      "id": 9,
      "ontology_uri": "",
      "uri": "",
      "is_value": false,
      "multivalued": false,
      "uuid": "6a659546-c3aa-45ff-8f6c-0706f2361cfe",
      "values": [
        {
          "id": 10,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "3288a7bd-6ca7-413e-9890-5c4c541331de",
          "label": "Female"
        },
        {
          "id": 11,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "207a8f33-ee23-44c9-88a5-e6a036a7d950",
          "label": "Male"
        },
        {
          "id": 20,
          "ontology_uri": "",
          "uri": "",
          "blocking": false,
          "uuid": "1e75ade7-f1c2-4ef7-994b-c5b07d52713e",
          "label": "Cannot Be Determined"
        }
      ],
      "excepted_taxon_ids": [
        47170,
        333586,
        63081,
        47113
      ],
      "label": "Sex"
    }
  ]
}

Parameters

taxon_id (Optional[int]) – ID of taxon to get controlled terms for
user_agent (Optional[str]) – a user-agent string that will be passed to iNaturalist.

Return type

Dict[str, Any]

Returns

A dict containing details on controlled terms and their values

Raises

TaxonNotFound –

pyinaturalist.node_api.get_geojson_observations(properties=None, **params)[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'])

Example Response

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [4.360086, 50.646894]
            },
            "properties": {
                "id": 16227955,
                "photo_url": "https://static.inaturalist.org/photos/24355315/square.jpeg?1536150659",
                "positional_accuracy": 23,
                "preferred_common_name": null,
                "quality_grade": "research",
                "taxon_id": 493595,
                "taxon_name": "Lixus bardanae",
                "time_observed_at": "2018-09-05T14:06:00+02:00",
                "uri": "https://www.inaturalist.org/observations/16227955"
            }
        }
    ]
}

Parameters

q (str) – Search observation properties
d1 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or after this date
d2 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or before this date
day (Union[int, List[int]]) – Must be observed within this day of the month
month (Union[int, List[int]]) – Must be observed within this month
year (Union[int, List[int]]) – Must be observed within this year
license (Union[str, List[str]]) – Observation must have this license
photo_license (Union[str, List[str]]) – Must have at least one photo with this license
out_of_range (bool) – Observations whose taxa are outside their known ranges
list_id (int) – Taxon must be in the list with this ID
quality_grade (str) – Must have this quality grade
id (Union[int, List[int]]) – Must have this observation ID
taxon_id (Union[int, List[int]]) – Only show observations of these taxa and their descendants
taxon_name (Union[str, List[str]]) – Taxon must have a scientific or common name matching this string
iconic_taxa (Union[str, List[str]]) – Taxon must by within this iconic taxon
updated_since (Union[datetime.date, datetime.datetime, str]) – Must be updated since this time
acc (bool) – Whether or not positional accuracy / coordinate uncertainty has been specified
captive (bool) – Captive or cultivated observations
endemic (bool) – Observations whose taxa are endemic to their location
geo (bool) – Observations that are georeferenced
id_please (bool) – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified (bool) – Observations that have community identifications
introduced (bool) – Observations whose taxa are introduced in their location
mappable (bool) – Observations that show on map tiles
native (bool) – Observations whose taxa are native to their location
pcid (bool) – Observations identified by the curator of a project. If the project_id parameter is also specified, this will only consider observations identified by curators of the specified project(s)
photos (bool) – Observations with photos
popular (bool) – Observations that have been favorited by at least one user
sounds (bool) – Observations with sounds
taxon_is_active (bool) – Observations of active taxon concepts
threatened (bool) – Observations whose taxa are threatened in their location
verifiable (bool) – Observations with a quality_grade of either needs_id or research. Equivalent to quality_grade=needs_id,research
not_id (Union[int, List[int]]) – Must not have this ID
place_id (Union[int, List[int]]) – Must be observed within the place with this ID
project_id (Union[int, List[int]]) – Must be added to the project this ID or slug
rank (Union[str, List[str]]) – Taxon must have this rank
site_id (Union[str, List[str]]) – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype (Union[str, List[str]]) – Must have an observation field value with this datatype
sound_license (Union[str, List[str]]) – Must have at least one sound with this license
without_taxon_id (Union[int, List[int]]) – Exclude observations of these taxa and their descendants
user_id (Union[int, List[int], str, List[str]]) – Observer must have this user ID or login
user_login (Union[str, List[str]]) – Observer must have this user login
ident_user_id (Union[int, List[int], str, List[str]]) – Identifier must have this user ID or login
term_id (Union[int, List[int]]) – Must have an annotation using this controlled term ID
term_value_id (Union[int, List[int]]) – Must have an annotation using this controlled value ID. Must be combined with the term_id parameter
without_term_value_id (Union[int, List[int]]) – Exclude observations with annotations using this controlled value ID. Must be combined with the term_id parameter
acc_above (str) – Must have an positional accuracy above this value (meters)
acc_below (str) – Must have an positional accuracy below this value (meters)
created_d1 (Union[datetime.date, datetime.datetime, str]) – Must be created at or after this time
created_d2 (Union[datetime.date, datetime.datetime, str]) – Must be created at or before this time
created_on (Union[datetime.date, datetime.datetime, str]) – Must be created on this date
observed_on (Union[datetime.date, datetime.datetime, str]) – Must be observed on this date
unobserved_by_user_id (int) – Must not be of a taxon previously observed by this user
apply_project_rules_for (str) – Must match the rules of the project with this ID or slug
cs (str) – Taxon must have this conservation status code. If the place_id parameter is also specified, this will only consider statuses specific to that place
csa (str) – Taxon must have a conservation status from this authority. If the place_id parameter is also specified, this will only consider statuses specific to that place
csi (Union[str, List[str]]) – Taxon must have this IUCN conservation status. If the place_id parameter is also specified, this will only consider statuses specific to that place
geoprivacy (Union[str, List[str]]) – Must have this geoprivacy setting
taxon_geoprivacy (Union[str, List[str]]) – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank (str) – Taxon must have this rank or lower
lrank (str) – Taxon must have this rank or higher
id_above (int) – Must have an ID above this value
id_below (int) – Must have an ID below this value
identifications (str) – Identifications must meet these criteria
lat (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
lng (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
radius (float) – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project (Union[int, str]) – Must not be in the project with this ID or slug
not_matching_project_rules_for (Union[int, str]) – Must not match the rules of the project with this ID or slug
search_on (str) – Properties to search on, when combined with q. Searches across all properties by default
viewer_id (int) – See reviewed
reviewed (bool) – Observations have been reviewed by the user with ID equal to the value of the viewer_id parameter
locale (str) – Locale preference for taxon common names
preferred_place_id (int) – Place preference for regional taxon common names
ttl (str) – Set the Cache-Control HTTP header with this value as max-age, in seconds
nelat (float) – NE latitude of bounding box
nelng (float) – NE longitude of bounding box
swlat (float) – SW latitude of bounding box
swlng (float) – SW longitude of bounding box
properties (Optional[List[str]]) – Properties from observation results to include as GeoJSON properties
user_agent (str) – A custom user-agent string to provide to the iNaturalist API
max_rank (str) –
min_rank (str) –

Return type

Dict[str, Any]

Returns

A FeatureCollection containing observation results as Feature dicts.

pyinaturalist.node_api.get_identifications(**params)[source]¶

Search identifications.

API reference: https://api.inaturalist.org/v1/docs/#!/Identifications/get_identifications

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,
        },
    ],
}

Parameters

current_taxon (bool) – ID’s taxon is the same it’s observation’s taxon
own_observation (bool) – ID was added by the observer
is_change (bool) – ID was created as a results of a taxon change
taxon_active (bool) – ID’s taxon is currently an active taxon
observation_taxon_active (bool) – Observation’s taxon is currently an active taxon
id (Union[int, List[int]]) – Identification ID
rank (Union[str, List[str]]) – ID’s taxon must have this rank # Multiple choice
observation_rank (Union[str, List[str]]) – Observation’s taxon must have this rank # Multiple choice
user_id (Union[int, List[int], str, List[str]]) – Identifier must have this user ID
user_login (Union[str, List[str]]) – Identifier must have this user login
current (bool) – Most recent Identification on a observation by a user
category (Union[str, List[str]]) – Type of identification
place_id (Union[int, List[int]]) – Observation must occur in this place
quality_grade (Union[str, List[str]]) – Observation must have this quality grade
taxon_id (Union[int, List[int]]) – Identification taxa must match the given taxa or their descendants
observation_taxon_id (Union[int, List[int]]) – Observation taxa must match the given taxa or their descendants
iconic_taxon_id (Union[int, List[int]]) – Identification iconic taxon ID
observation_iconic_taxon_id (Union[int, List[int]]) – Observation iconic taxon ID
lrank (str) – Identification taxon must have this rank or higher
hrank (str) – Identification taxon must have this rank or lower
observation_lrank (str) – Observation taxon must have this rank or higher
observation_hrank (str) – Observation taxon must have this rank or lower
without_taxon_id (Union[int, List[int]]) – Exclude Identifications of these taxa and their descendants
without_observation_taxon_id (Union[int, List[int]]) – Exclude Identifications of observations of these taxa and their descendants
d1 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or after this date
d2 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or before this date
observation_created_d1 (Union[datetime.date, datetime.datetime, str]) – Observation must be created on or after this date
observation_created_d2 (Union[datetime.date, datetime.datetime, str]) – Observation must be created on or before this date
observed_d1 (Union[datetime.date, datetime.datetime, str]) – Observation must be observed on or after this date
observed_d2 (Union[datetime.date, datetime.datetime, str]) – Observation must be observed on or before this date
id_above (int) – Must have an ID above this value
id_below (int) – Must have an ID below this value
page (int) – Page number of results to return
per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (str) – Sort order
order_by (str) – Field to sort on
count_only (bool) – Only return a count of results; alias for per_page=0
only_id (bool) – Return only the record IDs
user_agent (str) – A custom user-agent string to provide to the iNaturalist API

Return type

Dict[str, Any]

Returns

Response dict containing identification records

pyinaturalist.node_api.get_identifications_by_id(identification_id, user_agent=None)[source]¶

Get one or more identification records by ID.

API reference: https://api.inaturalist.org/v1/docs/#!/Identifications/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 (Union[int, List[int]]) – Get taxa with this ID. Multiple values are allowed.
user_agent (Optional[str]) –

Return type

Dict[str, Any]

Returns

Response dict containing identification records

pyinaturalist.node_api.get_observation(observation_id, user_agent=None)[source]¶

Get details about a single observation by ID

API reference: https://api.inaturalist.org/v1/docs/#!/Observations/get_observations_id

Example

>>> response = get_observation(16227955)
>>> print(format_observations(response))
[16227955] [493595] Species: Lixus bardanae observed on 2018-09-05 14:06:00+01:00 by niconoe at 54 rue des Badauds

Example Response

from datetime import datetime
from dateutil.tz import tzoffset

{
    'quality_grade': 'research',
    'time_observed_at': '2018-09-05T14:06:00+02:00',
    'taxon_geoprivacy': None,
    'annotations': [
        {
            'user_id': 886482,
            'concatenated_attr_val': '1|2',
            'controlled_attribute_id': 1,
            'votes': [],
            'uuid': '14bbd34f-73f8-4b99-b591-8517913788a1',
            'vote_score': 0,
            'controlled_value_id': 2,
            'user': {
                'id': 886482,
                'login': 'niconoe',
                'spam': False,
                'suspended': False,
                'created_at': '2018-04-23T17:11:14+00:00',
                'login_autocomplete': 'niconoe',
                'login_exact': 'niconoe',
                'name': 'Nicolas Noé',
                'name_autocomplete': 'Nicolas Noé',
                'orcid': 'https://orcid.org/0000-0002-9503-4750',
                'icon': 'https://static.inaturalist.org/attachments/users/icons/886482/thumb.jpg?1529671435',
                'observations_count': 928,
                'identifications_count': 118,
                'journal_posts_count': 0,
                'activity_count': 1046,
                'species_count': 395,
                'universal_search_rank': 928,
                'roles': [],
                'site_id': 1,
                'icon_url': 'https://static.inaturalist.org/attachments/users/icons/886482/medium.jpg?1529671435',
            },
        }
    ],
    'uuid': '6448d03a-7f9a-4099-86aa-ca09a7740b00',
    'id': 16227955,
    'cached_votes_total': 0,
    'identifications_most_agree': True,
    'species_guess': 'Lixus bardanae',
    'identifications_most_disagree': False,
    'tags': [],
    'positional_accuracy': 23,
    'comments_count': 2,
    'site_id': 1,
    'license_code': 'cc0',
    'quality_metrics': [],
    'public_positional_accuracy': 23,
    'reviewed_by': [180811, 886482, 1226913],
    'oauth_application_id': None,
    'flags': [],
    'created_at': datetime(2018, 9, 5, 14, 31, 8, tzinfo=tzoffset(None, 7200)),
    'description': '',
    'project_ids_with_curator_id': [],
    'updated_at': datetime(2018, 9, 22, 19, 19, 27, tzinfo=tzoffset(None, 7200)),
    'sounds': [],
    'place_ids': [
        7008,
        8657,
        14999,
        59614,
        67952,
        80627,
        81490,
        96372,
        96794,
        97391,
        97582,
        108692,
    ],
    'captive': False,
    'taxon': {
        'is_active': True,
        'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372852/60473/48736/272543/507383/71157/1101667',
        'min_species_ancestry': '48460,1,47120,372739,47158,184884,47208,71130,372852,60473,48736,272543,507383,71157,1101667,493595',
        'endemic': False,
        'iconic_taxon_id': 47158,
        'min_species_taxon_id': 493595,
        'threatened': False,
        'rank_level': 10,
        'introduced': False,
        'native': False,
        'parent_id': 1101667,
        'name': 'Lixus bardanae',
        'rank': 'species',
        'extinct': False,
        'id': 493595,
        'ancestor_ids': [
            48460,
            1,
            47120,
            372739,
            47158,
            184884,
            47208,
            71130,
            372852,
            60473,
            48736,
            272543,
            507383,
            71157,
            1101667,
            493595,
        ],
        'photos_locked': False,
        'taxon_schemes_count': 1,
        'wikipedia_url': None,
        'current_synonymous_taxon_ids': None,
        'created_at': '2016-04-25T22:35:20+00:00',
        'taxon_changes_count': 0,
        'complete_species_count': None,
        'universal_search_rank': 44,
        'observations_count': 44,
        'flag_counts': {'unresolved': 0, 'resolved': 0},
        'atlas_id': None,
        'default_photo': {
            'square_url': 'https://static.inaturalist.org/photos/69087254/square.jpg?1587876286',
            'attribution': '(c) Andy Van de Velde, all rights reserved',
            'flags': [],
            'medium_url': 'https://static.inaturalist.org/photos/69087254/medium.jpg?1587876286',
            'id': 69087254,
            'license_code': None,
            'original_dimensions': {'width': 2048, 'height': 1638},
            'url': 'https://static.inaturalist.org/photos/69087254/square.jpg?1587876286',
        },
        'iconic_taxon_name': 'Insecta',
    },
    'ident_taxon_ids': [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47208,
        71130,
        372852,
        60473,
        48736,
        272543,
        507383,
        71157,
        1101667,
        493595,
    ],
    'outlinks': [{'source': 'GBIF', 'url': 'http://www.gbif.org/occurrence/1914197587'}],
    'faves_count': 0,
    'ofvs': [],
    'num_identification_agreements': 2,
    'preferences': {'prefers_community_taxon': None},
    'comments': [
        {
            'moderator_actions': [],
            'hidden': False,
            'flags': [],
            'created_at': '2018-09-05T14:08:09.350Z',
            'id': 2071611,
            'created_at_details': {
                'date': '2018-09-05',
                'week': 36,
                'month': 9,
                'hour': 14,
                'year': 2018,
                'day': 5,
            },
            'body': 'suspect L. bardanae - but sits on Solanum (non-host)',
            'uuid': 'e6fc62ea-e22b-4427-bb65-1ba3bc591c77',
            'user': {
                'created_at': '2016-02-18T10:19:19+00:00',
                'id': 180811,
                'login': 'borisb',
                'spam': False,
                'suspended': False,
                'login_autocomplete': 'borisb',
                'login_exact': 'borisb',
                'name': '',
                'name_autocomplete': '',
                'orcid': None,
                'icon': None,
                'observations_count': 0,
                'identifications_count': 286253,
                'journal_posts_count': 0,
                'activity_count': 286253,
                'species_count': 0,
                'universal_search_rank': 0,
                'roles': ['curator'],
                'site_id': 1,
                'icon_url': None,
            },
        },
        {
            'moderator_actions': [],
            'hidden': False,
            'flags': [],
            'created_at': '2018-09-05T16:03:40.937Z',
            'id': 2071896,
            'created_at_details': {
                'date': '2018-09-05',
                'week': 36,
                'month': 9,
                'hour': 16,
                'year': 2018,
                'day': 5,
            },
            'body': 'I now see: Bonus species on observation! You may make a duplicate . . . \n(Flea beetle Epitrix pubescens on Solanum bud) \n',
            'uuid': '4d401d20-1b08-464a-8287-351f5b57443e',
            'user': {
                'created_at': '2016-02-18T10:19:19+00:00',
                'id': 180811,
                'login': 'borisb',
                'spam': False,
                'suspended': False,
                'login_autocomplete': 'borisb',
                'login_exact': 'borisb',
                'name': '',
                'name_autocomplete': '',
                'orcid': None,
                'icon': None,
                'observations_count': 0,
                'identifications_count': 286253,
                'journal_posts_count': 0,
                'activity_count': 286253,
                'species_count': 0,
                'universal_search_rank': 0,
                'roles': ['curator'],
                'site_id': 1,
                'icon_url': None,
            },
        },
    ],
    'map_scale': 17,
    'uri': 'https://www.inaturalist.org/observations/16227955',
    'project_ids': [],
    'community_taxon_id': 493595,
    'geojson': {'coordinates': [4.360086, 50.646894], 'type': 'Point'},
    'owners_identification_from_vision': True,
    'identifications_count': 2,
    'obscured': False,
    'num_identification_disagreements': 0,
    'geoprivacy': None,
    'location': [50.646894, 4.360086],
    'votes': [],
    'spam': False,
    'user': {
        'site_id': 1,
        'created_at': '2018-04-23T17:11:14+00:00',
        'id': 886482,
        'login': 'niconoe',
        'spam': False,
        'suspended': False,
        'preferences': {},
        'login_autocomplete': 'niconoe',
        'login_exact': 'niconoe',
        'name': 'Nicolas Noé',
        'name_autocomplete': 'Nicolas Noé',
        'orcid': 'https://orcid.org/0000-0002-9503-4750',
        'icon': 'https://static.inaturalist.org/attachments/users/icons/886482/thumb.jpg?1529671435',
        'observations_count': 928,
        'identifications_count': 118,
        'journal_posts_count': 0,
        'activity_count': 1046,
        'species_count': 395,
        'universal_search_rank': 928,
        'roles': [],
        'icon_url': 'https://static.inaturalist.org/attachments/users/icons/886482/medium.jpg?1529671435',
    },
    'mappable': True,
    'identifications_some_agree': True,
    'project_ids_without_curator_id': [],
    'place_guess': '54 rue des Badauds',
    'identifications': 'TRUNCATED',
    'project_observations': [],
    'photos': [
        {
            'id': 24355315,
            'license_code': 'cc-by',
            'url': 'https://static.inaturalist.org/photos/24355315/square.jpeg?1536150664',
            'attribution': '(c) Nicolas Noé, some rights reserved (CC BY)',
            'original_dimensions': {'width': 1445, 'height': 1057},
            'flags': [],
        },
        {
            'id': 24355313,
            'license_code': 'cc-by',
            'url': 'https://static.inaturalist.org/photos/24355313/square.jpeg?1536150659',
            'attribution': '(c) Nicolas Noé, some rights reserved (CC BY)',
            'original_dimensions': {'width': 2048, 'height': 1364},
            'flags': [],
        },
    ],
    'observation_photos': [
        {
            'id': 22080796,
            'position': 0,
            'uuid': '76b54495-3497-4e96-b07c-7ad346939a02',
            'photo': {
                'id': 24355315,
                'license_code': 'cc-by',
                'url': 'https://static.inaturalist.org/photos/24355315/square.jpeg?1536150664',
                'attribution': '(c) Nicolas Noé, some rights reserved (CC BY)',
                'original_dimensions': {'width': 1445, 'height': 1057},
                'flags': [],
            },
        },
        {
            'id': 22080797,
            'position': 1,
            'uuid': '06b90a88-d98d-4447-b14c-5d354d2d68d1',
            'photo': {
                'id': 24355313,
                'license_code': 'cc-by',
                'url': 'https://static.inaturalist.org/photos/24355313/square.jpeg?1536150659',
                'attribution': '(c) Nicolas Noé, some rights reserved (CC BY)',
                'original_dimensions': {'width': 2048, 'height': 1364},
                'flags': [],
            },
        },
    ],
    'faves': [],
    'non_owner_ids': 'TRUNCATED',
    'observed_on': datetime(2018, 9, 5, 14, 6, tzinfo=tzoffset('Europe/Paris', 3600)),
}

Parameters

observation_id (int) – Observation ID
user_agent (Optional[str]) – a user-agent string that will be passed to iNaturalist.

Return type

Dict[str, Any]

Returns

A dict with details on the observation

Raises

ObservationNotFound –

pyinaturalist.node_api.get_observation_histogram(**params)[source]¶

Search observations and return histogram data for the given time interval

API reference: https://api.inaturalist.org/v1/docs/#!/Observations/get_observations_histogram

Notes:

Search parameters are the same as get_observations(), with the addition of date_field and interval.
date_field may be either ‘observed’ (default) or ‘created’.
Observed date ranges can be filtered by parameters d1 and d2
Created date ranges can be filtered by parameters created_d1 and created_d2
interval may be one of: ‘year’, ‘month’, ‘week’, ‘day’, ‘hour’, ‘month_of_year’, or ‘week_of_year’; spaces are also allowed instead of underscores, e.g. ‘month of year’.
The year, month, week, day, and hour interval options will set default values for d1 and created_d1, to limit the number of groups returned. You can override those values if you want data from a longer or shorter time span.
The ‘hour’ interval only works with date_field='created'

Example

Get observations per month during 2020 in Austria (place ID 8057)

>>> response = get_observation_histogram(
>>>     interval='month',
>>>     d1='2020-01-01',
>>>     d2='2020-12-31',
>>>     place_id=8057,
>>> )

Example Response (observations per month of year)

Example Response (observations per month)

from datetime import datetime

{
    datetime(2020, 1, 1, 0, 0): 272,
    datetime(2020, 2, 1, 0, 0): 253,
    datetime(2020, 3, 1, 0, 0): 992,
    datetime(2020, 4, 1, 0, 0): 3925,
    datetime(2020, 5, 1, 0, 0): 7983,
    datetime(2020, 6, 1, 0, 0): 7080,
    datetime(2020, 7, 1, 0, 0): 9150,
    datetime(2020, 8, 1, 0, 0): 8895,
    datetime(2020, 9, 1, 0, 0): 8374,
    datetime(2020, 10, 1, 0, 0): 6060,
    datetime(2020, 11, 1, 0, 0): 920,
    datetime(2020, 12, 1, 0, 0): 382,
}

Example Response (observations per day)

from datetime import datetime

{
    datetime(2020, 1, 1, 0, 0): 11,
    datetime(2020, 1, 2, 0, 0): 6,
    datetime(2020, 1, 3, 0, 0): 2,
    datetime(2020, 1, 4, 0, 0): 3,
    datetime(2020, 1, 5, 0, 0): 13,
    datetime(2020, 1, 6, 0, 0): 4,
    datetime(2020, 1, 7, 0, 0): 4,
    datetime(2020, 1, 8, 0, 0): 0,
    datetime(2020, 1, 9, 0, 0): 1,
    datetime(2020, 1, 10, 0, 0): 5,
    datetime(2020, 1, 11, 0, 0): 6,
    datetime(2020, 1, 12, 0, 0): 7,
    datetime(2020, 1, 13, 0, 0): 2,
    datetime(2020, 1, 14, 0, 0): 7,
    datetime(2020, 1, 15, 0, 0): 11,
    datetime(2020, 1, 16, 0, 0): 0,
    datetime(2020, 1, 17, 0, 0): 5,
    datetime(2020, 1, 18, 0, 0): 13,
    datetime(2020, 1, 19, 0, 0): 1,
    datetime(2020, 1, 20, 0, 0): 5,
    datetime(2020, 1, 21, 0, 0): 3,
    datetime(2020, 1, 22, 0, 0): 8,
    datetime(2020, 1, 23, 0, 0): 21,
    datetime(2020, 1, 24, 0, 0): 7,
    datetime(2020, 1, 25, 0, 0): 14,
    datetime(2020, 1, 26, 0, 0): 62,
    datetime(2020, 1, 27, 0, 0): 10,
    datetime(2020, 1, 28, 0, 0): 17,
    datetime(2020, 1, 29, 0, 0): 7,
    datetime(2020, 1, 30, 0, 0): 9,
    datetime(2020, 1, 31, 0, 0): 7,
}

Parameters

q (str) – Search observation properties
d1 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or after this date
d2 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or before this date
day (Union[int, List[int]]) – Must be observed within this day of the month
month (Union[int, List[int]]) – Must be observed within this month
year (Union[int, List[int]]) – Must be observed within this year
license (Union[str, List[str]]) – Observation must have this license
photo_license (Union[str, List[str]]) – Must have at least one photo with this license
out_of_range (bool) – Observations whose taxa are outside their known ranges
list_id (int) – Taxon must be in the list with this ID
quality_grade (str) – Must have this quality grade
id (Union[int, List[int]]) – Must have this observation ID
taxon_id (Union[int, List[int]]) – Only show observations of these taxa and their descendants
taxon_name (Union[str, List[str]]) – Taxon must have a scientific or common name matching this string
iconic_taxa (Union[str, List[str]]) – Taxon must by within this iconic taxon
updated_since (Union[datetime.date, datetime.datetime, str]) – Must be updated since this time
acc (bool) – Whether or not positional accuracy / coordinate uncertainty has been specified
captive (bool) – Captive or cultivated observations
endemic (bool) – Observations whose taxa are endemic to their location
geo (bool) – Observations that are georeferenced
id_please (bool) – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified (bool) – Observations that have community identifications
introduced (bool) – Observations whose taxa are introduced in their location
mappable (bool) – Observations that show on map tiles
native (bool) – Observations whose taxa are native to their location
pcid (bool) – Observations identified by the curator of a project. If the project_id parameter is also specified, this will only consider observations identified by curators of the specified project(s)
photos (bool) – Observations with photos
popular (bool) – Observations that have been favorited by at least one user
sounds (bool) – Observations with sounds
taxon_is_active (bool) – Observations of active taxon concepts
threatened (bool) – Observations whose taxa are threatened in their location
verifiable (bool) – Observations with a quality_grade of either needs_id or research. Equivalent to quality_grade=needs_id,research
not_id (Union[int, List[int]]) – Must not have this ID
place_id (Union[int, List[int]]) – Must be observed within the place with this ID
project_id (Union[int, List[int]]) – Must be added to the project this ID or slug
rank (Union[str, List[str]]) – Taxon must have this rank
site_id (Union[str, List[str]]) – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype (Union[str, List[str]]) – Must have an observation field value with this datatype
sound_license (Union[str, List[str]]) – Must have at least one sound with this license
without_taxon_id (Union[int, List[int]]) – Exclude observations of these taxa and their descendants
user_id (Union[int, List[int], str, List[str]]) – Observer must have this user ID or login
user_login (Union[str, List[str]]) – Observer must have this user login
ident_user_id (Union[int, List[int], str, List[str]]) – Identifier must have this user ID or login
term_id (Union[int, List[int]]) – Must have an annotation using this controlled term ID
term_value_id (Union[int, List[int]]) – Must have an annotation using this controlled value ID. Must be combined with the term_id parameter
without_term_value_id (Union[int, List[int]]) – Exclude observations with annotations using this controlled value ID. Must be combined with the term_id parameter
acc_above (str) – Must have an positional accuracy above this value (meters)
acc_below (str) – Must have an positional accuracy below this value (meters)
created_d1 (Union[datetime.date, datetime.datetime, str]) – Must be created at or after this time
created_d2 (Union[datetime.date, datetime.datetime, str]) – Must be created at or before this time
created_on (Union[datetime.date, datetime.datetime, str]) – Must be created on this date
observed_on (Union[datetime.date, datetime.datetime, str]) – Must be observed on this date
unobserved_by_user_id (int) – Must not be of a taxon previously observed by this user
apply_project_rules_for (str) – Must match the rules of the project with this ID or slug
cs (str) – Taxon must have this conservation status code. If the place_id parameter is also specified, this will only consider statuses specific to that place
csa (str) – Taxon must have a conservation status from this authority. If the place_id parameter is also specified, this will only consider statuses specific to that place
csi (Union[str, List[str]]) – Taxon must have this IUCN conservation status. If the place_id parameter is also specified, this will only consider statuses specific to that place
geoprivacy (Union[str, List[str]]) – Must have this geoprivacy setting
taxon_geoprivacy (Union[str, List[str]]) – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank (str) – Taxon must have this rank or lower
lrank (str) – Taxon must have this rank or higher
id_above (int) – Must have an ID above this value
id_below (int) – Must have an ID below this value
identifications (str) – Identifications must meet these criteria
lat (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
lng (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
radius (float) – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project (Union[int, str]) – Must not be in the project with this ID or slug
not_matching_project_rules_for (Union[int, str]) – Must not match the rules of the project with this ID or slug
search_on (str) – Properties to search on, when combined with q. Searches across all properties by default
viewer_id (int) – See reviewed
reviewed (bool) – Observations have been reviewed by the user with ID equal to the value of the viewer_id parameter
locale (str) – Locale preference for taxon common names
preferred_place_id (int) – Place preference for regional taxon common names
ttl (str) – Set the Cache-Control HTTP header with this value as max-age, in seconds
nelat (float) – NE latitude of bounding box
nelng (float) – NE longitude of bounding box
swlat (float) – SW latitude of bounding box
swlng (float) – SW longitude of bounding box
date_field (str) – Histogram basis: either when the observation was created or observed
interval (str) – Time interval for histogram, with groups starting on or contained within the group value.
user_agent (str) – A custom user-agent string to provide to the iNaturalist API
max_rank (str) –
min_rank (str) –

Return type

Dict[Union[date, datetime, int], int]

Returns

Dict of {time_key: observation_count}. Keys are ints for ‘month of year’ and ‘week of year’ intervals, and datetime objects for all other intervals.

pyinaturalist.node_api.get_observation_identifiers(**params)[source]¶

Get identifiers of observations matching the search criteria and the count of observations they have identified. By default, results are sorted by ID count in descending.

API reference: https://api.inaturalist.org/v1/docs/#!/Observations/get_observations_identifiers

Note: This endpoint will only return up to 500 results.

Example

>>> response = get_observation_identifiers(place_id=72645)
>>> print(format_users(response, align=True))
[409010  ] jdoe42 (Jane Doe)
[691216  ] jbrown252 (James Brown)
[3959037 ] tnsparkleberry

Example Response

{
  "total_results": 2999,
  "page": 1,
  "per_page": 500,
  "results": [
    {
      "user_id": 53153,
      "count": 1787,
      "user": {
        "id": 53153,
        "login": "willkuhn",
        "spam": false,
        "suspended": false,
        "created_at": "2014-09-15T18:38:59+00:00",
        "login_autocomplete": "willkuhn",
        "login_exact": "willkuhn",
        "name": "Will Kuhn",
        "name_autocomplete": "Will Kuhn",
        "orcid": "https://orcid.org/0000-0002-5506-6379",
        "icon": "https://static.inaturalist.org/attachments/users/icons/53153/thumb.jpeg?1606488424",
        "observations_count": 2945,
        "identifications_count": 3895,
        "journal_posts_count": 0,
        "activity_count": 6840,
        "species_count": 1230,
        "universal_search_rank": 2945,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/53153/medium.jpeg?1606488424"
      }
    },
    {
      "user_id": 105391,
      "count": 1165,
      "user": {
        "id": 105391,
        "login": "jtuttle",
        "spam": false,
        "suspended": false,
        "created_at": "2015-05-25T21:56:21+00:00",
        "login_autocomplete": "jtuttle",
        "login_exact": "jtuttle",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/105391/thumb.jpg?1475546106",
        "observations_count": 12473,
        "identifications_count": 27628,
        "journal_posts_count": 0,
        "activity_count": 40101,
        "species_count": 3217,
        "universal_search_rank": 12473,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/105391/medium.jpg?1475546106"
      }
    },
    {
      "user_id": 32654,
      "count": 1012,
      "user": {
        "id": 32654,
        "login": "eraskin",
        "spam": false,
        "suspended": false,
        "created_at": "2014-03-19T18:35:39+00:00",
        "login_autocomplete": "eraskin",
        "login_exact": "eraskin",
        "name": "Evan M. Raskin",
        "name_autocomplete": "Evan M. Raskin",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/32654/thumb.jpg?1533126488",
        "observations_count": 5150,
        "identifications_count": 18213,
        "journal_posts_count": 3,
        "activity_count": 23366,
        "species_count": 2320,
        "universal_search_rank": 5150,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/32654/medium.jpg?1533126488"
      }
    },
    {
      "user_id": 1064292,
      "count": 907,
      "user": {
        "id": 1064292,
        "login": "syrherp",
        "spam": false,
        "suspended": false,
        "created_at": "2018-07-04T04:58:43+00:00",
        "login_autocomplete": "syrherp",
        "login_exact": "syrherp",
        "name": "Anthony Brais",
        "name_autocomplete": "Anthony Brais",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1064292/thumb.jpg?1537157949",
        "observations_count": 3788,
        "identifications_count": 33279,
        "journal_posts_count": 0,
        "activity_count": 37067,
        "species_count": 472,
        "universal_search_rank": 3788,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1064292/medium.jpg?1537157949"
      }
    },
    {
      "user_id": 2233645,
      "count": 851,
      "user": {
        "id": 2233645,
        "login": "jak2113",
        "spam": false,
        "suspended": false,
        "created_at": "2019-09-09T15:42:57+00:00",
        "login_autocomplete": "jak2113",
        "login_exact": "jak2113",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": null,
        "observations_count": 287,
        "identifications_count": 1623,
        "journal_posts_count": 0,
        "activity_count": 1910,
        "species_count": 206,
        "universal_search_rank": 287,
        "roles": [],
        "site_id": 1,
        "icon_url": null
      }
    },
    {
      "user_id": 19073,
      "count": 781,
      "user": {
        "id": 19073,
        "login": "choess",
        "spam": false,
        "suspended": false,
        "created_at": "2013-07-13T18:27:48+00:00",
        "login_autocomplete": "choess",
        "login_exact": "choess",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/19073/thumb.jpg?1475537701",
        "observations_count": 5067,
        "identifications_count": 152943,
        "journal_posts_count": 11,
        "activity_count": 158021,
        "species_count": 1284,
        "universal_search_rank": 5067,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/19073/medium.jpg?1475537701"
      }
    },
    {
      "user_id": 26905,
      "count": 668,
      "user": {
        "id": 26905,
        "login": "polemoniaceae",
        "spam": false,
        "suspended": false,
        "created_at": "2013-12-04T20:28:55+00:00",
        "login_autocomplete": "polemoniaceae",
        "login_exact": "polemoniaceae",
        "name": "Jeff",
        "name_autocomplete": "Jeff",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/26905/thumb.jpg?1475541432",
        "observations_count": 251,
        "identifications_count": 129664,
        "journal_posts_count": 0,
        "activity_count": 129915,
        "species_count": 222,
        "universal_search_rank": 251,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/26905/medium.jpg?1475541432"
      }
    },
    {
      "user_id": 854537,
      "count": 622,
      "user": {
        "id": 854537,
        "login": "maxallen",
        "spam": false,
        "suspended": false,
        "created_at": "2018-04-16T22:12:08+00:00",
        "login_autocomplete": "maxallen",
        "login_exact": "maxallen",
        "name": "",
        "name_autocomplete": "",
        "orcid": "https://orcid.org/0000-0001-8976-889X",
        "icon": "https://static.inaturalist.org/attachments/users/icons/854537/thumb.jpg?1529523533",
        "observations_count": 1938,
        "identifications_count": 524561,
        "journal_posts_count": 4,
        "activity_count": 526503,
        "species_count": 675,
        "universal_search_rank": 1938,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/854537/medium.jpg?1529523533"
      }
    },
    {
      "user_id": 755672,
      "count": 621,
      "user": {
        "id": 755672,
        "login": "ddennism",
        "spam": false,
        "suspended": false,
        "created_at": "2018-01-30T02:28:08+00:00",
        "login_autocomplete": "ddennism",
        "login_exact": "ddennism",
        "name": "Daniel McClosky",
        "name_autocomplete": "Daniel McClosky",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/755672/thumb.jpg?1571254550",
        "observations_count": 3369,
        "identifications_count": 38204,
        "journal_posts_count": 8,
        "activity_count": 41581,
        "species_count": 774,
        "universal_search_rank": 3369,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/755672/medium.jpg?1571254550"
      }
    },
    {
      "user_id": 2229996,
      "count": 616,
      "user": {
        "id": 2229996,
        "login": "annkatrinrose",
        "spam": false,
        "suspended": false,
        "created_at": "2019-09-08T18:45:38+00:00",
        "login_autocomplete": "annkatrinrose",
        "login_exact": "annkatrinrose",
        "name": "Annkatrin Rose",
        "name_autocomplete": "Annkatrin Rose",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/2229996/thumb.jpg?1567997735",
        "observations_count": 3799,
        "identifications_count": 9286,
        "journal_posts_count": 6,
        "activity_count": 13091,
        "species_count": 1024,
        "universal_search_rank": 3799,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/2229996/medium.jpg?1567997735"
      }
    },
    {
      "user_id": 324885,
      "count": 599,
      "user": {
        "id": 324885,
        "login": "lucareptile",
        "spam": false,
        "suspended": false,
        "created_at": "2016-09-09T00:19:57+00:00",
        "login_autocomplete": "lucareptile",
        "login_exact": "lucareptile",
        "name": "Luca Catanzaro",
        "name_autocomplete": "Luca Catanzaro",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/324885/thumb.jpg?1566422568",
        "observations_count": 21480,
        "identifications_count": 109080,
        "journal_posts_count": 0,
        "activity_count": 130560,
        "species_count": 2470,
        "universal_search_rank": 21480,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/324885/medium.jpg?1566422568"
      }
    },
    {
      "user_id": 1210028,
      "count": 577,
      "user": {
        "id": 1210028,
        "login": "pynklynx",
        "spam": false,
        "suspended": false,
        "created_at": "2018-09-15T03:55:25+00:00",
        "login_autocomplete": "pynklynx",
        "login_exact": "pynklynx",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1210028/thumb.jpg?1538262214",
        "observations_count": 6673,
        "identifications_count": 74690,
        "journal_posts_count": 0,
        "activity_count": 81363,
        "species_count": 1310,
        "universal_search_rank": 6673,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1210028/medium.jpg?1538262214"
      }
    },
    {
      "user_id": 1168695,
      "count": 530,
      "user": {
        "id": 1168695,
        "login": "trscavo",
        "spam": false,
        "suspended": false,
        "created_at": "2018-08-28T18:14:51+00:00",
        "login_autocomplete": "trscavo",
        "login_exact": "trscavo",
        "name": "Tom Scavo",
        "name_autocomplete": "Tom Scavo",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1168695/thumb.png?1535480090",
        "observations_count": 4541,
        "identifications_count": 30780,
        "journal_posts_count": 0,
        "activity_count": 35321,
        "species_count": 554,
        "universal_search_rank": 4541,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1168695/medium.png?1535480090"
      }
    },
    {
      "user_id": 187480,
      "count": 468,
      "user": {
        "id": 187480,
        "login": "wdvanhem",
        "spam": false,
        "suspended": false,
        "created_at": "2016-03-03T13:54:17+00:00",
        "login_autocomplete": "wdvanhem",
        "login_exact": "wdvanhem",
        "name": "Will Van Hemessen",
        "name_autocomplete": "Will Van Hemessen",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/187480/thumb.jpeg?1586740535",
        "observations_count": 8050,
        "identifications_count": 145345,
        "journal_posts_count": 1,
        "activity_count": 153396,
        "species_count": 2482,
        "universal_search_rank": 8050,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/187480/medium.jpeg?1586740535"
      }
    }
  ]
}

Parameters

q (str) – Search observation properties
d1 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or after this date
d2 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or before this date
day (Union[int, List[int]]) – Must be observed within this day of the month
month (Union[int, List[int]]) – Must be observed within this month
year (Union[int, List[int]]) – Must be observed within this year
license (Union[str, List[str]]) – Observation must have this license
photo_license (Union[str, List[str]]) – Must have at least one photo with this license
out_of_range (bool) – Observations whose taxa are outside their known ranges
list_id (int) – Taxon must be in the list with this ID
quality_grade (str) – Must have this quality grade
id (Union[int, List[int]]) – Must have this observation ID
taxon_id (Union[int, List[int]]) – Only show observations of these taxa and their descendants
taxon_name (Union[str, List[str]]) – Taxon must have a scientific or common name matching this string
iconic_taxa (Union[str, List[str]]) – Taxon must by within this iconic taxon
updated_since (Union[datetime.date, datetime.datetime, str]) – Must be updated since this time
acc (bool) – Whether or not positional accuracy / coordinate uncertainty has been specified
captive (bool) – Captive or cultivated observations
endemic (bool) – Observations whose taxa are endemic to their location
geo (bool) – Observations that are georeferenced
id_please (bool) – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified (bool) – Observations that have community identifications
introduced (bool) – Observations whose taxa are introduced in their location
mappable (bool) – Observations that show on map tiles
native (bool) – Observations whose taxa are native to their location
pcid (bool) – Observations identified by the curator of a project. If the project_id parameter is also specified, this will only consider observations identified by curators of the specified project(s)
photos (bool) – Observations with photos
popular (bool) – Observations that have been favorited by at least one user
sounds (bool) – Observations with sounds
taxon_is_active (bool) – Observations of active taxon concepts
threatened (bool) – Observations whose taxa are threatened in their location
verifiable (bool) – Observations with a quality_grade of either needs_id or research. Equivalent to quality_grade=needs_id,research
not_id (Union[int, List[int]]) – Must not have this ID
place_id (Union[int, List[int]]) – Must be observed within the place with this ID
project_id (Union[int, List[int]]) – Must be added to the project this ID or slug
rank (Union[str, List[str]]) – Taxon must have this rank
site_id (Union[str, List[str]]) – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype (Union[str, List[str]]) – Must have an observation field value with this datatype
sound_license (Union[str, List[str]]) – Must have at least one sound with this license
without_taxon_id (Union[int, List[int]]) – Exclude observations of these taxa and their descendants
user_id (Union[int, List[int], str, List[str]]) – Observer must have this user ID or login
user_login (Union[str, List[str]]) – Observer must have this user login
ident_user_id (Union[int, List[int], str, List[str]]) – Identifier must have this user ID or login
term_id (Union[int, List[int]]) – Must have an annotation using this controlled term ID
term_value_id (Union[int, List[int]]) – Must have an annotation using this controlled value ID. Must be combined with the term_id parameter
without_term_value_id (Union[int, List[int]]) – Exclude observations with annotations using this controlled value ID. Must be combined with the term_id parameter
acc_above (str) – Must have an positional accuracy above this value (meters)
acc_below (str) – Must have an positional accuracy below this value (meters)
created_d1 (Union[datetime.date, datetime.datetime, str]) – Must be created at or after this time
created_d2 (Union[datetime.date, datetime.datetime, str]) – Must be created at or before this time
created_on (Union[datetime.date, datetime.datetime, str]) – Must be created on this date
observed_on (Union[datetime.date, datetime.datetime, str]) – Must be observed on this date
unobserved_by_user_id (int) – Must not be of a taxon previously observed by this user
apply_project_rules_for (str) – Must match the rules of the project with this ID or slug
cs (str) – Taxon must have this conservation status code. If the place_id parameter is also specified, this will only consider statuses specific to that place
csa (str) – Taxon must have a conservation status from this authority. If the place_id parameter is also specified, this will only consider statuses specific to that place
csi (Union[str, List[str]]) – Taxon must have this IUCN conservation status. If the place_id parameter is also specified, this will only consider statuses specific to that place
geoprivacy (Union[str, List[str]]) – Must have this geoprivacy setting
taxon_geoprivacy (Union[str, List[str]]) – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank (str) – Taxon must have this rank or lower
lrank (str) – Taxon must have this rank or higher
id_above (int) – Must have an ID above this value
id_below (int) – Must have an ID below this value
identifications (str) – Identifications must meet these criteria
lat (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
lng (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
radius (float) – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project (Union[int, str]) – Must not be in the project with this ID or slug
not_matching_project_rules_for (Union[int, str]) – Must not match the rules of the project with this ID or slug
search_on (str) – Properties to search on, when combined with q. Searches across all properties by default
viewer_id (int) – See reviewed
reviewed (bool) – Observations have been reviewed by the user with ID equal to the value of the viewer_id parameter
locale (str) – Locale preference for taxon common names
preferred_place_id (int) – Place preference for regional taxon common names
ttl (str) – Set the Cache-Control HTTP header with this value as max-age, in seconds
nelat (float) – NE latitude of bounding box
nelng (float) – NE longitude of bounding box
swlat (float) – SW latitude of bounding box
swlng (float) – SW longitude of bounding box
page (int) – Page number of results to return
per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (str) – Sort order
order_by (str) – Field to sort on
count_only (bool) – Only return a count of results; alias for per_page=0
user_agent (str) – A custom user-agent string to provide to the iNaturalist API
max_rank (str) –
min_rank (str) –

Return type

Dict[str, Any]

Returns

Response dict of identifiers

pyinaturalist.node_api.get_observation_observers(**params)[source]¶

Get observers of observations matching the search criteria and the count of observations and distinct taxa of rank species they have observed.

Notes

Options for order_by are ‘observation_count’ (default) or ‘species_count’
This endpoint will only return up to 500 results
See this issue for more details: https://github.com/inaturalist/iNaturalistAPI/issues/235

API reference: https://api.inaturalist.org/v1/docs/#!/Observations/get_observations_observers

Example

>>> response = get_observation_observers(place_id=72645, order_by='species_count')
>>> print(format_users(response, align=True))
[1566366 ] fossa1211
[674557  ] schurchin
[5813    ] fluffberger (Fluff Berger)

Example Response

{
  "total_results": 3948,
  "page": 1,
  "per_page": 500,
  "results": [
    {
      "user_id": 15723,
      "observation_count": 2346,
      "species_count": 605,
      "user": {
        "id": 15723,
        "login": "reallifeecology",
        "spam": false,
        "suspended": false,
        "created_at": "2013-04-27T19:32:15+00:00",
        "login_autocomplete": "reallifeecology",
        "login_exact": "reallifeecology",
        "name": "Jonathan (JC) Carpenter",
        "name_autocomplete": "Jonathan (JC) Carpenter",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/15723/thumb.jpg?1475535710",
        "observations_count": 36365,
        "identifications_count": 2086,
        "journal_posts_count": 3,
        "activity_count": 38454,
        "species_count": 5740,
        "universal_search_rank": 36365,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/15723/medium.jpg?1475535710"
      }
    },
    {
      "user_id": 1085809,
      "observation_count": 1125,
      "species_count": 393,
      "user": {
        "id": 1085809,
        "login": "anneturner",
        "spam": false,
        "suspended": false,
        "created_at": "2018-07-14T16:12:14+00:00",
        "login_autocomplete": "anneturner",
        "login_exact": "anneturner",
        "name": "Anne Turner",
        "name_autocomplete": "Anne Turner",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1085809/thumb.jpeg?1555073435",
        "observations_count": 1441,
        "identifications_count": 125,
        "journal_posts_count": 0,
        "activity_count": 1566,
        "species_count": 553,
        "universal_search_rank": 1441,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1085809/medium.jpeg?1555073435"
      }
    },
    {
      "user_id": 53153,
      "observation_count": 890,
      "species_count": 324,
      "user": {
        "id": 53153,
        "login": "willkuhn",
        "spam": false,
        "suspended": false,
        "created_at": "2014-09-15T18:38:59+00:00",
        "login_autocomplete": "willkuhn",
        "login_exact": "willkuhn",
        "name": "Will Kuhn",
        "name_autocomplete": "Will Kuhn",
        "orcid": "https://orcid.org/0000-0002-5506-6379",
        "icon": "https://static.inaturalist.org/attachments/users/icons/53153/thumb.jpeg?1606488424",
        "observations_count": 2945,
        "identifications_count": 3895,
        "journal_posts_count": 0,
        "activity_count": 6840,
        "species_count": 1230,
        "universal_search_rank": 2945,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/53153/medium.jpeg?1606488424"
      }
    },
    {
      "user_id": 176684,
      "observation_count": 806,
      "species_count": 348,
      "user": {
        "id": 176684,
        "login": "gmontgomery",
        "spam": false,
        "suspended": false,
        "created_at": "2016-02-06T21:58:36+00:00",
        "login_autocomplete": "gmontgomery",
        "login_exact": "gmontgomery",
        "name": "Graham Montgomery",
        "name_autocomplete": "Graham Montgomery",
        "orcid": "https://orcid.org/0000-0002-8217-8800",
        "icon": "https://static.inaturalist.org/attachments/users/icons/176684/thumb.jpeg?1600827496",
        "observations_count": 7986,
        "identifications_count": 4072,
        "journal_posts_count": 0,
        "activity_count": 12058,
        "species_count": 4146,
        "universal_search_rank": 7986,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/176684/medium.jpeg?1600827496"
      }
    },
    {
      "user_id": 1019810,
      "observation_count": 791,
      "species_count": 279,
      "user": {
        "id": 1019810,
        "login": "jduffy",
        "spam": false,
        "suspended": false,
        "created_at": "2018-06-11T15:58:21+00:00",
        "login_autocomplete": "jduffy",
        "login_exact": "jduffy",
        "name": "Jim",
        "name_autocomplete": "Jim",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1019810/thumb.jpg?1551496934",
        "observations_count": 823,
        "identifications_count": 2,
        "journal_posts_count": 0,
        "activity_count": 825,
        "species_count": 313,
        "universal_search_rank": 823,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1019810/medium.jpg?1551496934"
      }
    },
    {
      "user_id": 906019,
      "observation_count": 693,
      "species_count": 190,
      "user": {
        "id": 906019,
        "login": "akfishmom",
        "spam": false,
        "suspended": false,
        "created_at": "2018-04-26T20:56:39+00:00",
        "login_autocomplete": "akfishmom",
        "login_exact": "akfishmom",
        "name": null,
        "name_autocomplete": null,
        "orcid": null,
        "icon": null,
        "observations_count": 822,
        "identifications_count": 6,
        "journal_posts_count": 0,
        "activity_count": 828,
        "species_count": 322,
        "universal_search_rank": 822,
        "roles": [],
        "site_id": 1,
        "icon_url": null
      }
    },
    {
      "user_id": 17201,
      "observation_count": 661,
      "species_count": 328,
      "user": {
        "id": 17201,
        "login": "matthewherron",
        "spam": false,
        "suspended": false,
        "created_at": "2013-05-29T02:13:48+00:00",
        "login_autocomplete": "matthewherron",
        "login_exact": "matthewherron",
        "name": "Matthew Herron",
        "name_autocomplete": "Matthew Herron",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/17201/thumb.jpeg?1475536451",
        "observations_count": 7694,
        "identifications_count": 1467,
        "journal_posts_count": 0,
        "activity_count": 9161,
        "species_count": 2195,
        "universal_search_rank": 7694,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/17201/medium.jpeg?1475536451"
      }
    },
    {
      "user_id": 282998,
      "observation_count": 640,
      "species_count": 212,
      "user": {
        "id": 282998,
        "login": "dunhamkc",
        "spam": false,
        "suspended": false,
        "created_at": "2016-08-06T13:19:36+00:00",
        "login_autocomplete": "dunhamkc",
        "login_exact": "dunhamkc",
        "name": "Keely Dunham",
        "name_autocomplete": "Keely Dunham",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/282998/thumb.jpg?1526954269",
        "observations_count": 2418,
        "identifications_count": 725,
        "journal_posts_count": 0,
        "activity_count": 3143,
        "species_count": 796,
        "universal_search_rank": 2418,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/282998/medium.jpg?1526954269"
      }
    },
    {
      "user_id": 843086,
      "observation_count": 562,
      "species_count": 235,
      "user": {
        "id": 843086,
        "login": "b_georgic",
        "spam": false,
        "suspended": false,
        "created_at": "2018-04-10T16:31:49+00:00",
        "login_autocomplete": "b_georgic",
        "login_exact": "b_georgic",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/843086/thumb.jpg?1606070123",
        "observations_count": 1151,
        "identifications_count": 0,
        "journal_posts_count": 0,
        "activity_count": 1151,
        "species_count": 653,
        "universal_search_rank": 1151,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/843086/medium.jpg?1606070123"
      }
    },
    {
      "user_id": 574477,
      "observation_count": 442,
      "species_count": 171,
      "user": {
        "id": 574477,
        "login": "pinus_taeda",
        "spam": false,
        "suspended": false,
        "created_at": "2017-08-10T18:00:10+00:00",
        "login_autocomplete": "pinus_taeda",
        "login_exact": "pinus_taeda",
        "name": null,
        "name_autocomplete": null,
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/574477/thumb.jpg?1527608024",
        "observations_count": 1846,
        "identifications_count": 1141,
        "journal_posts_count": 0,
        "activity_count": 2987,
        "species_count": 551,
        "universal_search_rank": 1846,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/574477/medium.jpg?1527608024"
      }
    },
    {
      "user_id": 2148023,
      "observation_count": 420,
      "species_count": 149,
      "user": {
        "id": 2148023,
        "login": "christopher514",
        "spam": false,
        "suspended": false,
        "created_at": "2019-08-19T02:14:52+00:00",
        "login_autocomplete": "christopher514",
        "login_exact": "christopher514",
        "name": "Christopher Gontarski",
        "name_autocomplete": "Christopher Gontarski",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/2148023/thumb.jpeg?1566180892",
        "observations_count": 567,
        "identifications_count": 0,
        "journal_posts_count": 0,
        "activity_count": 567,
        "species_count": 287,
        "universal_search_rank": 567,
        "roles": [],
        "site_id": null,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/2148023/medium.jpeg?1566180892"
      }
    },
    {
      "user_id": 362446,
      "observation_count": 398,
      "species_count": 237,
      "user": {
        "id": 362446,
        "login": "pwdeacon",
        "spam": false,
        "suspended": false,
        "created_at": "2016-11-02T20:47:19+00:00",
        "login_autocomplete": "pwdeacon",
        "login_exact": "pwdeacon",
        "name": "Pat Deacon",
        "name_autocomplete": "Pat Deacon",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/362446/thumb.jpeg?1575167373",
        "observations_count": 12962,
        "identifications_count": 7883,
        "journal_posts_count": 0,
        "activity_count": 20845,
        "species_count": 3029,
        "universal_search_rank": 12962,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/362446/medium.jpeg?1575167373"
      }
    },
    {
      "user_id": 93979,
      "observation_count": 373,
      "species_count": 23,
      "user": {
        "id": 93979,
        "login": "mcaterino",
        "spam": false,
        "suspended": false,
        "created_at": "2015-04-28T12:18:05+00:00",
        "login_autocomplete": "mcaterino",
        "login_exact": "mcaterino",
        "name": "Michael Caterino",
        "name_autocomplete": "Michael Caterino",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/93979/thumb.jpg?1568554017",
        "observations_count": 1708,
        "identifications_count": 153,
        "journal_posts_count": 0,
        "activity_count": 1861,
        "species_count": 174,
        "universal_search_rank": 1708,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/93979/medium.jpg?1568554017"
      }
    },
    {
      "user_id": 17283,
      "observation_count": 334,
      "species_count": 252,
      "user": {
        "id": 17283,
        "login": "layla",
        "spam": false,
        "suspended": false,
        "created_at": "2013-05-30T20:06:01+00:00",
        "login_autocomplete": "layla",
        "login_exact": "layla",
        "name": "Layla Dishman",
        "name_autocomplete": "Layla Dishman",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/17283/thumb.jpg?1475536494",
        "observations_count": 2831,
        "identifications_count": 1414,
        "journal_posts_count": 0,
        "activity_count": 4245,
        "universal_search_rank": 2831,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/17283/medium.jpg?1475536494"
      }
    },
    {
      "user_id": 2346515,
      "observation_count": 317,
      "species_count": 77,
      "user": {
        "id": 2346515,
        "login": "sarahroth",
        "spam": false,
        "suspended": false,
        "created_at": "2019-10-08T15:37:36+00:00",
        "login_autocomplete": "sarahroth",
        "login_exact": "sarahroth",
        "name": "Sarah Roth",
        "name_autocomplete": "Sarah Roth",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/2346515/thumb.png?1570549056",
        "observations_count": 473,
        "identifications_count": 0,
        "journal_posts_count": 0,
        "activity_count": 473,
        "species_count": 126,
        "universal_search_rank": 473,
        "roles": [],
        "site_id": null,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/2346515/medium.png?1570549056"
      }
    },
    {
      "user_id": 159616,
      "observation_count": 314,
      "species_count": 149,
      "user": {
        "id": 159616,
        "login": "cdance",
        "spam": false,
        "suspended": false,
        "created_at": "2015-12-09T19:36:11+00:00",
        "login_autocomplete": "cdance",
        "login_exact": "cdance",
        "name": "CDance",
        "name_autocomplete": "CDance",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/159616/thumb.jpg?1566762916",
        "observations_count": 2900,
        "identifications_count": 264,
        "journal_posts_count": 3,
        "activity_count": 3167,
        "species_count": 1165,
        "universal_search_rank": 2900,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/159616/medium.jpg?1566762916"
      }
    },
    {
      "user_id": 1359300,
      "observation_count": 310,
      "species_count": 148,
      "user": {
        "id": 1359300,
        "login": "spyingnaturalist",
        "spam": false,
        "suspended": false,
        "created_at": "2018-11-20T01:19:01+00:00",
        "login_autocomplete": "spyingnaturalist",
        "login_exact": "spyingnaturalist",
        "name": "",
        "name_autocomplete": "",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/1359300/thumb.jpg?1552909758",
        "observations_count": 8286,
        "identifications_count": 5371,
        "journal_posts_count": 0,
        "activity_count": 13657,
        "species_count": 2749,
        "universal_search_rank": 8286,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/1359300/medium.jpg?1552909758"
      }
    },
    {
      "user_id": 899236,
      "observation_count": 292,
      "species_count": 177,
      "user": {
        "id": 899236,
        "login": "palustris314",
        "spam": false,
        "suspended": false,
        "created_at": "2018-04-25T17:22:45+00:00",
        "login_autocomplete": "palustris314",
        "login_exact": "palustris314",
        "name": "Greg J Schmidt",
        "name_autocomplete": "Greg J Schmidt",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/899236/thumb.jpg?1526651056",
        "observations_count": 1599,
        "identifications_count": 139,
        "journal_posts_count": 0,
        "activity_count": 1738,
        "species_count": 1013,
        "universal_search_rank": 1599,
        "roles": [],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/899236/medium.jpg?1526651056"
      }
    },
    {
      "user_id": 187480,
      "observation_count": 252,
      "species_count": 172,
      "user": {
        "id": 187480,
        "login": "wdvanhem",
        "spam": false,
        "suspended": false,
        "created_at": "2016-03-03T13:54:17+00:00",
        "login_autocomplete": "wdvanhem",
        "login_exact": "wdvanhem",
        "name": "Will Van Hemessen",
        "name_autocomplete": "Will Van Hemessen",
        "orcid": null,
        "icon": "https://static.inaturalist.org/attachments/users/icons/187480/thumb.jpeg?1586740535",
        "observations_count": 8050,
        "identifications_count": 145345,
        "journal_posts_count": 1,
        "activity_count": 153396,
        "species_count": 2482,
        "universal_search_rank": 8050,
        "roles": [
          "curator"
        ],
        "site_id": 1,
        "icon_url": "https://static.inaturalist.org/attachments/users/icons/187480/medium.jpeg?1586740535"
      }
    }
  ]
}

Parameters

q (str) – Search observation properties
d1 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or after this date
d2 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or before this date
day (Union[int, List[int]]) – Must be observed within this day of the month
month (Union[int, List[int]]) – Must be observed within this month
year (Union[int, List[int]]) – Must be observed within this year
license (Union[str, List[str]]) – Observation must have this license
photo_license (Union[str, List[str]]) – Must have at least one photo with this license
out_of_range (bool) – Observations whose taxa are outside their known ranges
list_id (int) – Taxon must be in the list with this ID
quality_grade (str) – Must have this quality grade
id (Union[int, List[int]]) – Must have this observation ID
taxon_id (Union[int, List[int]]) – Only show observations of these taxa and their descendants
taxon_name (Union[str, List[str]]) – Taxon must have a scientific or common name matching this string
iconic_taxa (Union[str, List[str]]) – Taxon must by within this iconic taxon
updated_since (Union[datetime.date, datetime.datetime, str]) – Must be updated since this time
acc (bool) – Whether or not positional accuracy / coordinate uncertainty has been specified
captive (bool) – Captive or cultivated observations
endemic (bool) – Observations whose taxa are endemic to their location
geo (bool) – Observations that are georeferenced
id_please (bool) – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified (bool) – Observations that have community identifications
introduced (bool) – Observations whose taxa are introduced in their location
mappable (bool) – Observations that show on map tiles
native (bool) – Observations whose taxa are native to their location
pcid (bool) – Observations identified by the curator of a project. If the project_id parameter is also specified, this will only consider observations identified by curators of the specified project(s)
photos (bool) – Observations with photos
popular (bool) – Observations that have been favorited by at least one user
sounds (bool) – Observations with sounds
taxon_is_active (bool) – Observations of active taxon concepts
threatened (bool) – Observations whose taxa are threatened in their location
verifiable (bool) – Observations with a quality_grade of either needs_id or research. Equivalent to quality_grade=needs_id,research
not_id (Union[int, List[int]]) – Must not have this ID
place_id (Union[int, List[int]]) – Must be observed within the place with this ID
project_id (Union[int, List[int]]) – Must be added to the project this ID or slug
rank (Union[str, List[str]]) – Taxon must have this rank
site_id (Union[str, List[str]]) – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype (Union[str, List[str]]) – Must have an observation field value with this datatype
sound_license (Union[str, List[str]]) – Must have at least one sound with this license
without_taxon_id (Union[int, List[int]]) – Exclude observations of these taxa and their descendants
user_id (Union[int, List[int], str, List[str]]) – Observer must have this user ID or login
user_login (Union[str, List[str]]) – Observer must have this user login
ident_user_id (Union[int, List[int], str, List[str]]) – Identifier must have this user ID or login
term_id (Union[int, List[int]]) – Must have an annotation using this controlled term ID
term_value_id (Union[int, List[int]]) – Must have an annotation using this controlled value ID. Must be combined with the term_id parameter
without_term_value_id (Union[int, List[int]]) – Exclude observations with annotations using this controlled value ID. Must be combined with the term_id parameter
acc_above (str) – Must have an positional accuracy above this value (meters)
acc_below (str) – Must have an positional accuracy below this value (meters)
created_d1 (Union[datetime.date, datetime.datetime, str]) – Must be created at or after this time
created_d2 (Union[datetime.date, datetime.datetime, str]) – Must be created at or before this time
created_on (Union[datetime.date, datetime.datetime, str]) – Must be created on this date
observed_on (Union[datetime.date, datetime.datetime, str]) – Must be observed on this date
unobserved_by_user_id (int) – Must not be of a taxon previously observed by this user
apply_project_rules_for (str) – Must match the rules of the project with this ID or slug
cs (str) – Taxon must have this conservation status code. If the place_id parameter is also specified, this will only consider statuses specific to that place
csa (str) – Taxon must have a conservation status from this authority. If the place_id parameter is also specified, this will only consider statuses specific to that place
csi (Union[str, List[str]]) – Taxon must have this IUCN conservation status. If the place_id parameter is also specified, this will only consider statuses specific to that place
geoprivacy (Union[str, List[str]]) – Must have this geoprivacy setting
taxon_geoprivacy (Union[str, List[str]]) – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank (str) – Taxon must have this rank or lower
lrank (str) – Taxon must have this rank or higher
id_above (int) – Must have an ID above this value
id_below (int) – Must have an ID below this value
identifications (str) – Identifications must meet these criteria
lat (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
lng (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
radius (float) – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project (Union[int, str]) – Must not be in the project with this ID or slug
not_matching_project_rules_for (Union[int, str]) – Must not match the rules of the project with this ID or slug
search_on (str) – Properties to search on, when combined with q. Searches across all properties by default
viewer_id (int) – See reviewed
reviewed (bool) – Observations have been reviewed by the user with ID equal to the value of the viewer_id parameter
locale (str) – Locale preference for taxon common names
preferred_place_id (int) – Place preference for regional taxon common names
ttl (str) – Set the Cache-Control HTTP header with this value as max-age, in seconds
nelat (float) – NE latitude of bounding box
nelng (float) – NE longitude of bounding box
swlat (float) – SW latitude of bounding box
swlng (float) – SW longitude of bounding box
page (int) – Page number of results to return
per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (str) – Sort order
order_by (str) – Field to sort on
count_only (bool) – Only return a count of results; alias for per_page=0
user_agent (str) – A custom user-agent string to provide to the iNaturalist API
max_rank (str) –
min_rank (str) –

Return type

Dict[str, Any]

Returns

Response dict of observers

pyinaturalist.node_api.get_observation_species_counts(**params)[source]¶

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.

API reference: https://api.inaturalist.org/v1/docs/#!/Observations/get_observations_species_counts

Example

>>> response = get_observation_species_counts(user_login='my_username', quality_grade='research')
>>> print(format_species_counts(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
...

Example Response

{
    'total_results': 243,
    'page': 1,
    'per_page': 500,
    'results': [
        {
            'count': 32,
            'taxon': {
                'observations_count': 81696,
                'taxon_schemes_count': 2,
                'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372852/471714/48486/333790/333796/48487',
                'is_active': True,
                'flag_counts': {'unresolved': 0, 'resolved': 3},
                'wikipedia_url': 'http://en.wikipedia.org/wiki/Harmonia_axyridis',
                'current_synonymous_taxon_ids': None,
                'iconic_taxon_id': 47158,
                'rank_level': 10,
                'taxon_changes_count': 1,
                'atlas_id': 1241,
                'complete_species_count': None,
                'parent_id': 48487,
                'name': 'Harmonia axyridis',
                'rank': 'species',
                'extinct': False,
                'id': 48484,
                'default_photo': {
                    'square_url': 'https://static.inaturalist.org/photos/30978499/square.jpg?1549228178',
                    'attribution': '(c) Paolo Mazzei, all rights reserved',
                    'flags': [],
                    'medium_url': 'https://static.inaturalist.org/photos/30978499/medium.jpg?1549228178',
                    'id': 30978499,
                    'license_code': None,
                    'original_dimensions': {'width': 800, 'height': 600},
                    'url': 'https://static.inaturalist.org/photos/30978499/square.jpg?1549228178',
                },
                'ancestor_ids': [
                    48460,
                    1,
                    47120,
                    372739,
                    47158,
                    184884,
                    47208,
                    71130,
                    372852,
                    471714,
                    48486,
                    333790,
                    333796,
                    48487,
                    48484,
                ],
                'iconic_taxon_name': 'Insecta',
                'preferred_common_name': 'Asian Lady Beetle',
            },
        },
        {
            'count': 19,
            'taxon': {
                'observations_count': 43187,
                'taxon_schemes_count': 3,
                'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372852/471714/48486/333790/333796/51703',
                'is_active': True,
                'flag_counts': {'unresolved': 0, 'resolved': 1},
                'wikipedia_url': 'http://en.wikipedia.org/wiki/Coccinella_septempunctata',
                'current_synonymous_taxon_ids': None,
                'iconic_taxon_id': 47158,
                'rank_level': 10,
                'taxon_changes_count': 1,
                'atlas_id': None,
                'complete_species_count': None,
                'parent_id': 51703,
                'name': 'Coccinella septempunctata',
                'rank': 'species',
                'extinct': False,
                'id': 51702,
                'default_photo': {
                    'square_url': 'https://static.inaturalist.org/photos/5669923/square.jpg?1480658715',
                    'attribution': '(c) Katja Schulz, some rights reserved (CC BY)',
                    'flags': [],
                    'medium_url': 'https://static.inaturalist.org/photos/5669923/medium.jpg?1480658715',
                    'id': 5669923,
                    'license_code': 'cc-by',
                    'original_dimensions': {'width': 2048, 'height': 1536},
                    'url': 'https://static.inaturalist.org/photos/5669923/square.jpg?1480658715',
                },
                'ancestor_ids': [
                    48460,
                    1,
                    47120,
                    372739,
                    47158,
                    184884,
                    47208,
                    71130,
                    372852,
                    471714,
                    48486,
                    333790,
                    333796,
                    51703,
                    51702,
                ],
                'iconic_taxon_name': 'Insecta',
                'preferred_common_name': 'Seven-spotted Lady Beetle',
            },
        },
    ],
}

Parameters

q (str) – Search observation properties
d1 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or after this date
d2 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or before this date
day (Union[int, List[int]]) – Must be observed within this day of the month
month (Union[int, List[int]]) – Must be observed within this month
year (Union[int, List[int]]) – Must be observed within this year
license (Union[str, List[str]]) – Observation must have this license
photo_license (Union[str, List[str]]) – Must have at least one photo with this license
out_of_range (bool) – Observations whose taxa are outside their known ranges
list_id (int) – Taxon must be in the list with this ID
quality_grade (str) – Must have this quality grade
id (Union[int, List[int]]) – Must have this observation ID
taxon_id (Union[int, List[int]]) – Only show observations of these taxa and their descendants
taxon_name (Union[str, List[str]]) – Taxon must have a scientific or common name matching this string
iconic_taxa (Union[str, List[str]]) – Taxon must by within this iconic taxon
updated_since (Union[datetime.date, datetime.datetime, str]) – Must be updated since this time
acc (bool) – Whether or not positional accuracy / coordinate uncertainty has been specified
captive (bool) – Captive or cultivated observations
endemic (bool) – Observations whose taxa are endemic to their location
geo (bool) – Observations that are georeferenced
id_please (bool) – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified (bool) – Observations that have community identifications
introduced (bool) – Observations whose taxa are introduced in their location
mappable (bool) – Observations that show on map tiles
native (bool) – Observations whose taxa are native to their location
pcid (bool) – Observations identified by the curator of a project. If the project_id parameter is also specified, this will only consider observations identified by curators of the specified project(s)
photos (bool) – Observations with photos
popular (bool) – Observations that have been favorited by at least one user
sounds (bool) – Observations with sounds
taxon_is_active (bool) – Observations of active taxon concepts
threatened (bool) – Observations whose taxa are threatened in their location
verifiable (bool) – Observations with a quality_grade of either needs_id or research. Equivalent to quality_grade=needs_id,research
not_id (Union[int, List[int]]) – Must not have this ID
place_id (Union[int, List[int]]) – Must be observed within the place with this ID
project_id (Union[int, List[int]]) – Must be added to the project this ID or slug
rank (Union[str, List[str]]) – Taxon must have this rank
site_id (Union[str, List[str]]) – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype (Union[str, List[str]]) – Must have an observation field value with this datatype
sound_license (Union[str, List[str]]) – Must have at least one sound with this license
without_taxon_id (Union[int, List[int]]) – Exclude observations of these taxa and their descendants
user_id (Union[int, List[int], str, List[str]]) – Observer must have this user ID or login
user_login (Union[str, List[str]]) – Observer must have this user login
ident_user_id (Union[int, List[int], str, List[str]]) – Identifier must have this user ID or login
term_id (Union[int, List[int]]) – Must have an annotation using this controlled term ID
term_value_id (Union[int, List[int]]) – Must have an annotation using this controlled value ID. Must be combined with the term_id parameter
without_term_value_id (Union[int, List[int]]) – Exclude observations with annotations using this controlled value ID. Must be combined with the term_id parameter
acc_above (str) – Must have an positional accuracy above this value (meters)
acc_below (str) – Must have an positional accuracy below this value (meters)
created_d1 (Union[datetime.date, datetime.datetime, str]) – Must be created at or after this time
created_d2 (Union[datetime.date, datetime.datetime, str]) – Must be created at or before this time
created_on (Union[datetime.date, datetime.datetime, str]) – Must be created on this date
observed_on (Union[datetime.date, datetime.datetime, str]) – Must be observed on this date
unobserved_by_user_id (int) – Must not be of a taxon previously observed by this user
apply_project_rules_for (str) – Must match the rules of the project with this ID or slug
cs (str) – Taxon must have this conservation status code. If the place_id parameter is also specified, this will only consider statuses specific to that place
csa (str) – Taxon must have a conservation status from this authority. If the place_id parameter is also specified, this will only consider statuses specific to that place
csi (Union[str, List[str]]) – Taxon must have this IUCN conservation status. If the place_id parameter is also specified, this will only consider statuses specific to that place
geoprivacy (Union[str, List[str]]) – Must have this geoprivacy setting
taxon_geoprivacy (Union[str, List[str]]) – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank (str) – Taxon must have this rank or lower
lrank (str) – Taxon must have this rank or higher
id_above (int) – Must have an ID above this value
id_below (int) – Must have an ID below this value
identifications (str) – Identifications must meet these criteria
lat (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
lng (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
radius (float) – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project (Union[int, str]) – Must not be in the project with this ID or slug
not_matching_project_rules_for (Union[int, str]) – Must not match the rules of the project with this ID or slug
search_on (str) – Properties to search on, when combined with q. Searches across all properties by default
viewer_id (int) – See reviewed
reviewed (bool) – Observations have been reviewed by the user with ID equal to the value of the viewer_id parameter
locale (str) – Locale preference for taxon common names
preferred_place_id (int) – Place preference for regional taxon common names
ttl (str) – Set the Cache-Control HTTP header with this value as max-age, in seconds
nelat (float) – NE latitude of bounding box
nelng (float) – NE longitude of bounding box
swlat (float) – SW latitude of bounding box
swlng (float) – SW longitude of bounding box
page (int) – Page number of results to return
per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (str) – Sort order
order_by (str) – Field to sort on
count_only (bool) – Only return a count of results; alias for per_page=0
user_agent (str) – A custom user-agent string to provide to the iNaturalist API
max_rank (str) –
min_rank (str) –

Return type

Dict[str, Any]

Returns

Response dict containing taxon records with counts

pyinaturalist.node_api.get_observations(**params)[source]¶

Search observations.

API reference: http://api.inaturalist.org/v1/docs/#!/Observations/get_observations

Example

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:

>>> from pyinaturalist.formatters import format_observations
>>> print(format_observations(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'

Example Response

from datetime import datetime
from dateutil.tz import tzoffset, tzutc

{
    'total_results': 2,
    'page': 1,
    'per_page': 30,
    'results': [
        {
            'quality_grade': 'research',
            'time_observed_at': '2020-08-27T08:57:22+00:00',
            'taxon_geoprivacy': 'open',
            'annotations': [],
            'uuid': 'c44b91f3-534d-48c4-933d-a8b4e1d8f87b',
            'id': 57754375,
            'cached_votes_total': 0,
            'identifications_most_agree': True,
            'species_guess': 'Monarch',
            'identifications_most_disagree': False,
            'tags': [],
            'positional_accuracy': None,
            'comments_count': 2,
            'site_id': 5,
            'license_code': 'cc-by-nc',
            'quality_metrics': [],
            'public_positional_accuracy': None,
            'reviewed_by': [115129, 2852555],
            'oauth_application_id': 3,
            'flags': [],
            'created_at': datetime(2020, 8, 27, 18, 0, 51, tzinfo=tzutc()),
            'description': None,
            'project_ids_with_curator_id': [],
            'updated_at': datetime(2020, 8, 28, 12, 4, 18, tzinfo=tzutc()),
            'sounds': [],
            'place_ids': [
                6712,
                7953,
                9853,
                49224,
                59613,
                64422,
                64423,
                66741,
                78395,
                82256,
                97394,
                145030,
                155145,
                164401,
            ],
            'captive': False,
            'taxon': {
                'is_active': True,
                'ancestry': '48460/1/47120/372739/47158/184884/47157/47224/47922/61244/134169/522900/48663',
                'min_species_ancestry': '48460,1,47120,372739,47158,184884,47157,47224,47922,61244,134169,522900,48663,48662',
                'endemic': False,
                'iconic_taxon_id': 47158,
                'min_species_taxon_id': 48662,
                'threatened': True,
                'rank_level': 10,
                'introduced': False,
                'native': True,
                'parent_id': 48663,
                'name': 'Danaus plexippus',
                'rank': 'species',
                'extinct': False,
                'id': 48662,
                'ancestor_ids': [
                    48460,
                    1,
                    47120,
                    372739,
                    47158,
                    184884,
                    47157,
                    47224,
                    47922,
                    61244,
                    134169,
                    522900,
                    48663,
                    48662,
                ],
                'photos_locked': False,
                'taxon_schemes_count': 6,
                'wikipedia_url': 'http://en.wikipedia.org/wiki/Monarch_butterfly',
                'current_synonymous_taxon_ids': None,
                'created_at': '2008-10-26T20:24:33+00:00',
                'taxon_changes_count': 1,
                'complete_species_count': None,
                'universal_search_rank': 131627,
                'observations_count': 131627,
                'flag_counts': {'unresolved': 1, 'resolved': 7},
                'atlas_id': 1231,
                'default_photo': {
                    'square_url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684',
                    'attribution': '(c) fam-esquivel, some rights reserved (CC BY-NC)',
                    'flags': [],
                    'medium_url': 'https://static.inaturalist.org/photos/13824507/medium.jpg?1545715684',
                    'id': 13824507,
                    'license_code': 'cc-by-nc',
                    'original_dimensions': {'width': 2048, 'height': 1361},
                    'url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684',
                },
                'iconic_taxon_name': 'Insecta',
                'preferred_common_name': 'Monarch',
                'conservation_status': {
                    'user_id': None,
                    'status_name': 'imperiled',
                    'iucn': 40,
                    'authority': 'NatureServe',
                    'geoprivacy': None,
                    'source_id': 8,
                    'place_id': 7953,
                    'status': 's2b',
                },
            },
            'ident_taxon_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47157,
                47224,
                47922,
                61244,
                134169,
                522900,
                48663,
                48662,
            ],
            'outlinks': [{'source': 'GBIF', 'url': 'http://www.gbif.org/occurrence/2856816457'}],
            'faves_count': 0,
            'ofvs': [],
            'num_identification_agreements': 1,
            'preferences': {'prefers_community_taxon': None},
            'comments': [
                {
                    'moderator_actions': [],
                    'hidden': False,
                    'flags': [],
                    'created_at': '2020-08-28T12:04:18.407Z',
                    'id': 5326888,
                    'created_at_details': {
                        'date': '2020-08-28',
                        'week': 35,
                        'month': 8,
                        'hour': 12,
                        'year': 2020,
                        'day': 28,
                    },
                    'body': 'Thankyou ',
                    'uuid': 'b4d00be4-132d-4e51-bfdd-8515a00f161c',
                    'user': {
                        'created_at': '2020-04-26T15:26:56+00:00',
                        'id': 2852555,
                        'login': 'samroom',
                        'spam': False,
                        'suspended': False,
                        'login_autocomplete': 'samroom',
                        'login_exact': 'samroom',
                        'name': None,
                        'name_autocomplete': None,
                        'orcid': None,
                        'icon': None,
                        'observations_count': 59,
                        'identifications_count': 0,
                        'journal_posts_count': 0,
                        'activity_count': 59,
                        'species_count': 52,
                        'universal_search_rank': 59,
                        'roles': [],
                        'site_id': 5,
                        'icon_url': None,
                    },
                },
                {
                    'moderator_actions': [],
                    'hidden': False,
                    'flags': [],
                    'created_at': '2020-08-28T04:54:19.020Z',
                    'id': 5325706,
                    'created_at_details': {
                        'date': '2020-08-28',
                        'week': 35,
                        'month': 8,
                        'hour': 4,
                        'year': 2020,
                        'day': 28,
                    },
                    'body': 'Neat photo! ',
                    'uuid': '25ac67d5-ba09-47a8-91e3-b6e3590a0b72',
                    'user': {
                        'created_at': '2018-03-18T01:34:25+00:00',
                        'id': 792847,
                        'login': 'ingridt3',
                        'spam': False,
                        'suspended': False,
                        'login_autocomplete': 'ingridt3',
                        'login_exact': 'ingridt3',
                        'name': None,
                        'name_autocomplete': None,
                        'orcid': None,
                        'icon': None,
                        'observations_count': 51,
                        'identifications_count': 29,
                        'journal_posts_count': 0,
                        'activity_count': 80,
                        'species_count': 30,
                        'universal_search_rank': 51,
                        'roles': [],
                        'site_id': 5,
                        'icon_url': None,
                    },
                },
            ],
            'map_scale': None,
            'uri': 'https://www.inaturalist.org/observations/57754375',
            'project_ids': [],
            'community_taxon_id': 48662,
            'geojson': {'coordinates': [-104.71929167, 50.0949055], 'type': 'Point'},
            'owners_identification_from_vision': True,
            'identifications_count': 1,
            'obscured': False,
            'num_identification_disagreements': 0,
            'geoprivacy': None,
            'location': [50.0949055, -104.71929167],
            'votes': [],
            'spam': False,
            'user': {
                'site_id': 5,
                'created_at': '2020-04-26T15:26:56+00:00',
                'id': 2852555,
                'login': 'samroom',
                'spam': False,
                'suspended': False,
                'preferences': {},
                'login_autocomplete': 'samroom',
                'login_exact': 'samroom',
                'name': None,
                'name_autocomplete': None,
                'orcid': None,
                'icon': None,
                'observations_count': 59,
                'identifications_count': 0,
                'journal_posts_count': 0,
                'activity_count': 59,
                'species_count': 52,
                'universal_search_rank': 59,
                'roles': [],
                'icon_url': None,
            },
            'mappable': True,
            'identifications_some_agree': True,
            'project_ids_without_curator_id': [],
            'place_guess': 'Railway Ave, Wilcox, SK, CA',
            'identifications': 'TRUNCATED',
            'project_observations': [],
            'photos': [
                {
                    'id': 92152429,
                    'license_code': 'cc-by-nc',
                    'url': 'https://static.inaturalist.org/photos/92152429/square.jpg?1598551272',
                    'attribution': '(c) samroom, some rights reserved (CC BY-NC)',
                    'original_dimensions': {'width': 1188, 'height': 1188},
                    'flags': [],
                }
            ],
            'observation_photos': [
                {
                    'id': 85887066,
                    'position': 0,
                    'uuid': '6f73a9f2-019f-4566-a393-2c2242a3198d',
                    'photo': {
                        'id': 92152429,
                        'license_code': 'cc-by-nc',
                        'url': 'https://static.inaturalist.org/photos/92152429/square.jpg?1598551272',
                        'attribution': '(c) samroom, some rights reserved (CC BY-NC)',
                        'original_dimensions': {'width': 1188, 'height': 1188},
                        'flags': [],
                    },
                }
            ],
            'faves': [],
            'non_owner_ids': 'TRUNCATED',
            'observed_on': datetime(2020, 8, 27, 8, 57, 22, tzinfo=tzoffset('Etc/UTC', 0)),
        },
        {
            'quality_grade': 'research',
            'time_observed_at': '2020-08-26T22:46:10+00:00',
            'taxon_geoprivacy': 'open',
            'annotations': [],
            'uuid': '588c9ad4-c747-497c-a52f-bf856c30d2ff',
            'id': 57707611,
            'cached_votes_total': 0,
            'identifications_most_agree': True,
            'species_guess': 'Monarch',
            'identifications_most_disagree': False,
            'tags': [],
            'positional_accuracy': 374,
            'comments_count': 0,
            'site_id': 5,
            'license_code': None,
            'quality_metrics': [],
            'public_positional_accuracy': 374,
            'reviewed_by': [35013, 115129, 217571, 412189, 792847, 2173064],
            'oauth_application_id': 3,
            'flags': [],
            'created_at': datetime(2020, 8, 27, 4, 50, 17, tzinfo=tzutc()),
            'description': 'Only one today and likely the last one to eclose from the batch of caterpillars from 10-14 days ago. ',
            'project_ids_with_curator_id': [6905],
            'updated_at': datetime(2020, 11, 2, 19, 26, 40, tzinfo=tzutc()),
            'sounds': [],
            'place_ids': [
                6712,
                7953,
                9853,
                49224,
                59613,
                64422,
                64423,
                66741,
                78395,
                82256,
                97394,
                113642,
                120614,
                120671,
                145030,
                155145,
                164401,
            ],
            'captive': False,
            'taxon': {
                'is_active': True,
                'ancestry': '48460/1/47120/372739/47158/184884/47157/47224/47922/61244/134169/522900/48663',
                'min_species_ancestry': '48460,1,47120,372739,47158,184884,47157,47224,47922,61244,134169,522900,48663,48662',
                'endemic': False,
                'iconic_taxon_id': 47158,
                'min_species_taxon_id': 48662,
                'threatened': True,
                'rank_level': 10,
                'introduced': False,
                'native': True,
                'parent_id': 48663,
                'name': 'Danaus plexippus',
                'rank': 'species',
                'extinct': False,
                'id': 48662,
                'ancestor_ids': [
                    48460,
                    1,
                    47120,
                    372739,
                    47158,
                    184884,
                    47157,
                    47224,
                    47922,
                    61244,
                    134169,
                    522900,
                    48663,
                    48662,
                ],
                'photos_locked': False,
                'taxon_schemes_count': 6,
                'wikipedia_url': 'http://en.wikipedia.org/wiki/Monarch_butterfly',
                'current_synonymous_taxon_ids': None,
                'created_at': '2008-10-26T20:24:33+00:00',
                'taxon_changes_count': 1,
                'complete_species_count': None,
                'universal_search_rank': 131627,
                'observations_count': 131627,
                'flag_counts': {'unresolved': 1, 'resolved': 7},
                'atlas_id': 1231,
                'default_photo': {
                    'square_url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684',
                    'attribution': '(c) fam-esquivel, some rights reserved (CC BY-NC)',
                    'flags': [],
                    'medium_url': 'https://static.inaturalist.org/photos/13824507/medium.jpg?1545715684',
                    'id': 13824507,
                    'license_code': 'cc-by-nc',
                    'original_dimensions': {'width': 2048, 'height': 1361},
                    'url': 'https://static.inaturalist.org/photos/13824507/square.jpg?1545715684',
                },
                'iconic_taxon_name': 'Insecta',
                'preferred_common_name': 'Monarch',
                'conservation_status': {
                    'user_id': None,
                    'status_name': 'imperiled',
                    'iucn': 40,
                    'authority': 'NatureServe',
                    'geoprivacy': None,
                    'source_id': 8,
                    'place_id': 7953,
                    'status': 's2b',
                },
            },
            'ident_taxon_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47157,
                47224,
                47922,
                61244,
                134169,
                522900,
                48663,
                48662,
            ],
            'outlinks': [],
            'faves_count': 0,
            'ofvs': [],
            'num_identification_agreements': 5,
            'preferences': {'prefers_community_taxon': None},
            'comments': [],
            'map_scale': None,
            'uri': 'https://www.inaturalist.org/observations/57707611',
            'project_ids': [6905],
            'community_taxon_id': 48662,
            'geojson': {'coordinates': [-104.5628221383, 50.433418274], 'type': 'Point'},
            'owners_identification_from_vision': True,
            'identifications_count': 5,
            'obscured': False,
            'num_identification_disagreements': 0,
            'geoprivacy': None,
            'location': [50.433418274, -104.5628221383],
            'votes': [],
            'spam': False,
            'user': {
                'site_id': 5,
                'created_at': '2018-03-18T01:34:25+00:00',
                'id': 792847,
                'login': 'ingridt3',
                'spam': False,
                'suspended': False,
                'preferences': {},
                'login_autocomplete': 'ingridt3',
                'login_exact': 'ingridt3',
                'name': None,
                'name_autocomplete': None,
                'orcid': None,
                'icon': None,
                'observations_count': 51,
                'identifications_count': 29,
                'journal_posts_count': 0,
                'activity_count': 80,
                'species_count': 30,
                'universal_search_rank': 51,
                'roles': [],
                'icon_url': None,
            },
            'mappable': True,
            'identifications_some_agree': True,
            'project_ids_without_curator_id': [],
            'place_guess': 'Michener Dr, Regina, SK, CA',
            'identifications': 'TRUNCATED',
            'project_observations': [
                {
                    'id': 45561247,
                    'uuid': '912138ca-651d-4d5f-99c1-d89e9c023bb5',
                    'project': {'id': 6905},
                    'user_id': 35013,
                    'preferences': {'allows_curator_coordinate_access': True},
                    'user': {
                        'id': 35013,
                        'login': 'a_b',
                        'spam': False,
                        'suspended': False,
                        'created_at': '2014-04-09T03:27:04+00:00',
                        'login_autocomplete': 'a_b',
                        'login_exact': 'a_b',
                        'name': 'Andrea Benville',
                        'name_autocomplete': 'Andrea Benville',
                        'orcid': None,
                        'icon': 'https://static.inaturalist.org/attachments/users/icons/35013/thumb.jpg?1505750038',
                        'observations_count': 787,
                        'identifications_count': 533,
                        'journal_posts_count': 0,
                        'activity_count': 1320,
                        'species_count': 432,
                        'universal_search_rank': 787,
                        'roles': [],
                        'site_id': 5,
                        'icon_url': 'https://static.inaturalist.org/attachments/users/icons/35013/medium.jpg?1505750038',
                    },
                }
            ],
            'photos': [
                {
                    'id': 92075215,
                    'license_code': None,
                    'url': 'https://static.inaturalist.org/photos/92075215/square.jpg?1598503820',
                    'attribution': '(c) ingridt3, all rights reserved',
                    'original_dimensions': {'width': 1183, 'height': 842},
                    'flags': [],
                }
            ],
            'observation_photos': [
                {
                    'id': 85814399,
                    'position': 0,
                    'uuid': '98dd67ae-79b4-49c6-934b-6a814ea6d6ab',
                    'photo': {
                        'id': 92075215,
                        'license_code': None,
                        'url': 'https://static.inaturalist.org/photos/92075215/square.jpg?1598503820',
                        'attribution': '(c) ingridt3, all rights reserved',
                        'original_dimensions': {'width': 1183, 'height': 842},
                        'flags': [],
                    },
                }
            ],
            'faves': [],
            'non_owner_ids': 'TRUNCATED',
            'observed_on': datetime(2020, 8, 26, 22, 46, 10, tzinfo=tzoffset('Etc/UTC', 0)),
        },
    ],
}

Parameters

q (str) – Search observation properties
d1 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or after this date
d2 (Union[datetime.date, datetime.datetime, str]) – Must be observed on or before this date
day (Union[int, List[int]]) – Must be observed within this day of the month
month (Union[int, List[int]]) – Must be observed within this month
year (Union[int, List[int]]) – Must be observed within this year
license (Union[str, List[str]]) – Observation must have this license
photo_license (Union[str, List[str]]) – Must have at least one photo with this license
out_of_range (bool) – Observations whose taxa are outside their known ranges
list_id (int) – Taxon must be in the list with this ID
quality_grade (str) – Must have this quality grade
id (Union[int, List[int]]) – Must have this observation ID
taxon_id (Union[int, List[int]]) – Only show observations of these taxa and their descendants
taxon_name (Union[str, List[str]]) – Taxon must have a scientific or common name matching this string
iconic_taxa (Union[str, List[str]]) – Taxon must by within this iconic taxon
updated_since (Union[datetime.date, datetime.datetime, str]) – Must be updated since this time
acc (bool) – Whether or not positional accuracy / coordinate uncertainty has been specified
captive (bool) – Captive or cultivated observations
endemic (bool) – Observations whose taxa are endemic to their location
geo (bool) – Observations that are georeferenced
id_please (bool) – Observations with the deprecated ‘ID, Please!’ flag. Note that this will return observations, but that this attribute is no longer used.
identified (bool) – Observations that have community identifications
introduced (bool) – Observations whose taxa are introduced in their location
mappable (bool) – Observations that show on map tiles
native (bool) – Observations whose taxa are native to their location
pcid (bool) – Observations identified by the curator of a project. If the project_id parameter is also specified, this will only consider observations identified by curators of the specified project(s)
photos (bool) – Observations with photos
popular (bool) – Observations that have been favorited by at least one user
sounds (bool) – Observations with sounds
taxon_is_active (bool) – Observations of active taxon concepts
threatened (bool) – Observations whose taxa are threatened in their location
verifiable (bool) – Observations with a quality_grade of either needs_id or research. Equivalent to quality_grade=needs_id,research
not_id (Union[int, List[int]]) – Must not have this ID
place_id (Union[int, List[int]]) – Must be observed within the place with this ID
project_id (Union[int, List[int]]) – Must be added to the project this ID or slug
rank (Union[str, List[str]]) – Taxon must have this rank
site_id (Union[str, List[str]]) – Must be affiliated with the iNaturalist network website with this ID
ofv_datatype (Union[str, List[str]]) – Must have an observation field value with this datatype
sound_license (Union[str, List[str]]) – Must have at least one sound with this license
without_taxon_id (Union[int, List[int]]) – Exclude observations of these taxa and their descendants
user_id (Union[int, List[int], str, List[str]]) – Observer must have this user ID or login
user_login (Union[str, List[str]]) – Observer must have this user login
ident_user_id (Union[int, List[int], str, List[str]]) – Identifier must have this user ID or login
term_id (Union[int, List[int]]) – Must have an annotation using this controlled term ID
term_value_id (Union[int, List[int]]) – Must have an annotation using this controlled value ID. Must be combined with the term_id parameter
without_term_value_id (Union[int, List[int]]) – Exclude observations with annotations using this controlled value ID. Must be combined with the term_id parameter
acc_above (str) – Must have an positional accuracy above this value (meters)
acc_below (str) – Must have an positional accuracy below this value (meters)
created_d1 (Union[datetime.date, datetime.datetime, str]) – Must be created at or after this time
created_d2 (Union[datetime.date, datetime.datetime, str]) – Must be created at or before this time
created_on (Union[datetime.date, datetime.datetime, str]) – Must be created on this date
observed_on (Union[datetime.date, datetime.datetime, str]) – Must be observed on this date
unobserved_by_user_id (int) – Must not be of a taxon previously observed by this user
apply_project_rules_for (str) – Must match the rules of the project with this ID or slug
cs (str) – Taxon must have this conservation status code. If the place_id parameter is also specified, this will only consider statuses specific to that place
csa (str) – Taxon must have a conservation status from this authority. If the place_id parameter is also specified, this will only consider statuses specific to that place
csi (Union[str, List[str]]) – Taxon must have this IUCN conservation status. If the place_id parameter is also specified, this will only consider statuses specific to that place
geoprivacy (Union[str, List[str]]) – Must have this geoprivacy setting
taxon_geoprivacy (Union[str, List[str]]) – Filter observations by the most conservative geoprivacy applied by a conservation status associated with one of the taxa proposed in the current identifications.
hrank (str) – Taxon must have this rank or lower
lrank (str) – Taxon must have this rank or higher
id_above (int) – Must have an ID above this value
id_below (int) – Must have an ID below this value
identifications (str) – Identifications must meet these criteria
lat (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
lng (float) – Must be within a radius kilometer circle around this lat/lng (lat, lng, radius)
radius (float) – Must be within a {radius} kilometer circle around this lat/lng (lat, lng, radius)
not_in_project (Union[int, str]) – Must not be in the project with this ID or slug
not_matching_project_rules_for (Union[int, str]) – Must not match the rules of the project with this ID or slug
search_on (str) – Properties to search on, when combined with q. Searches across all properties by default
viewer_id (int) – See reviewed
reviewed (bool) – Observations have been reviewed by the user with ID equal to the value of the viewer_id parameter
locale (str) – Locale preference for taxon common names
preferred_place_id (int) – Place preference for regional taxon common names
ttl (str) – Set the Cache-Control HTTP header with this value as max-age, in seconds
nelat (float) – NE latitude of bounding box
nelng (float) – NE longitude of bounding box
swlat (float) – SW latitude of bounding box
swlng (float) – SW longitude of bounding box
page (int) – Page number of results to return
per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (str) – Sort order
order_by (str) – Field to sort on
count_only (bool) – Only return a count of results; alias for per_page=0
only_id (bool) – Return only the record IDs
user_agent (str) – A custom user-agent string to provide to the iNaturalist API
max_rank (str) –
min_rank (str) –

Return type

Dict[str, Any]

Returns

Response dict containing observation records

pyinaturalist.node_api.get_places_autocomplete(q=None, **params)[source]¶

Given a query string, get places with names starting with the search term

API reference: https://api.inaturalist.org/v1/docs/#!/Places/get_places_autocomplete

Note: This endpoint accepts a per_page param, up to a max of 20 (default 10). Pages beyond the first page cannot be retrieved. Use page=all to attempt to retrieve additional results. See paginate_autocomplete() for more info.

Example

>>> response = get_places_autocomplete('Irkutsk')
>>> print(format_places(response))
[11803   ] Irkutsk
[41854   ] Irkutskiy rayon
[166186  ] Irkutsk Oblast - ADD
[163077  ] Irkutsk agglomeration

Example Response

{
    'total_results': 4,
    'page': 1,
    'per_page': 4,
    'results': [
        {
            'ancestor_place_ids': [97395, 7161, 11803],
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [95.5820007324, 51.1188278198],
                        [95.5820007324, 64.2834396362],
                        [119.1222915649, 64.2834396362],
                        [119.1222915649, 51.1188278198],
                        [95.5820007324, 51.1188278198],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 309.898790854159,
            'admin_level': 1,
            'place_type': 21,
            'name': 'Irkutsk',
            'location': [57.0842832466, 106.2908666325],
            'id': 11803,
            'display_name': 'Irkutsk, RU',
            'uuid': '5a21bcbc-3975-4d22-81fa-0088543e3247',
            'slug': 'irkutsk',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'Polygon',
            },
        },
        {
            'ancestor_place_ids': [97395, 7161, 11803, 41853],
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [104.175743103, 52.3083381653],
                        [104.175743103, 52.3586273193],
                        [104.2688369751, 52.3586273193],
                        [104.2688369751, 52.3083381653],
                        [104.175743103, 52.3083381653],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 0.00468161207394086,
            'admin_level': 2,
            'place_type': 9,
            'name': 'Irkutsk',
            'location': [52.3330788792, 104.2213639696],
            'id': 41853,
            'display_name': 'Irkutsk, IK, RU',
            'uuid': 'ff9b00cd-491d-4414-a7a6-1d25bc16687b',
            'slug': 'irkutsk-irkutsk-ru',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'MultiPolygon',
            },
        },
        {
            'ancestor_place_ids': [97395, 7161, 11803, 41854],
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [103.3993835449, 51.8282775879],
                        [103.3993835449, 52.7414131165],
                        [105.9679870605, 52.7414131165],
                        [105.9679870605, 51.8282775879],
                        [103.3993835449, 51.8282775879],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 2.34548312891261,
            'admin_level': 2,
            'place_type': 102,
            'name': 'Irkutskiy rayon',
            'location': [52.2449129844, 104.5715345329],
            'id': 41854,
            'display_name': 'Irkutskiy rayon, IK, RU',
            'uuid': '23f656ae-4830-4934-b0e8-0fdc966565d1',
            'slug': 'irkutskiy-rayon',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'Polygon',
            },
        },
        {
            'ancestor_place_ids': [97395, 7161, 163077],
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [103.1875974, 51.6715918],
                        [103.1875974, 53.0498458],
                        [106.1725331, 53.0498458],
                        [106.1725331, 51.6715918],
                        [103.1875974, 51.6715918],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 4.1139995682678,
            'admin_level': None,
            'place_type': 1013,
            'name': 'Irkutsk agglomeration',
            'location': [52.2598446202, 104.6684418399],
            'id': 163077,
            'display_name': 'Irkutsk agglomeration, RU',
            'uuid': '553871d4-762e-4306-a48a-c4c5a3ac18b7',
            'slug': 'irkutsk-agglomeration',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'Polygon',
            },
        },
    ],
}

Parameters

q (Optional[str]) – Name must begin with this value
q – Search query
page (int) – Page number of results to return
per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (str) – Sort order
order_by (str) – Field to sort on
count_only (bool) – Only return a count of results; alias for per_page=0
user_agent (str) – A custom user-agent string to provide to the iNaturalist API

Return type

Dict[str, Any]

Returns

Response dict containing place records

pyinaturalist.node_api.get_places_by_id(place_id, user_agent=None)[source]¶

Get one or more places by ID.

API reference: https://api.inaturalist.org/v1/docs/#!/Places/get_places_id

Example

>>> response = get_places_by_id([67591, 89191])
>>> print(format_places(response))
[89191] Conservation Area Riversdale
[67591] Riversdale Beach

Example Response

{
    'total_results': 2,
    'page': 1,
    'per_page': 2,
    'results': [
        {
            'ancestor_place_ids': [97393, 6803, 8479, 40475, 89191],
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [172.22944733271785, -43.32610616632186],
                        [172.22944733271785, -43.32459953345999],
                        [172.2351855995691, -43.32459953345999],
                        [172.2351855995691, -43.32610616632186],
                        [172.22944733271785, -43.32610616632186],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 8.64546140806803e-06,
            'admin_level': None,
            'place_type': 100,
            'name': 'Conservation Area Riversdale',
            'location': [-43.3254578926, 172.2325124165],
            'id': 89191,
            'display_name': 'Conservation Area Riversdale, CA, NZ',
            'slug': 'conservation-area-riversdale',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'MultiPolygon',
            },
        },
        {
            'ancestor_place_ids': None,
            'bounding_box_geojson': {
                'coordinates': [
                    [
                        [176.0643786192, -41.1114421991],
                        [176.0643786192, -41.0804995501],
                        [176.0837817192, -41.0804995501],
                        [176.0837817192, -41.1114421991],
                        [176.0643786192, -41.1114421991],
                    ]
                ],
                'type': 'Polygon',
            },
            'bbox_area': 0.0006003833128119,
            'admin_level': None,
            'place_type': None,
            'name': 'Riversdale Beach',
            'location': [-41.0959708746, 176.0740801692],
            'id': 67591,
            'display_name': 'Riversdale Beach',
            'uuid': 'c5bca3b0-d9f2-44c3-bdb1-1189734a30a4',
            'slug': 'riversdale-beach',
            'geometry_geojson': {
                'coordinates': 'TRUNCATED',
                'type': 'MultiPolygon',
            },
        },
    ],
}

Parameters

place_id (Union[int, List[int]]) – Get a place with this ID. Multiple values are allowed.
user_agent (Optional[str]) –

Return type

Dict[str, Any]

Returns

Response dict containing place records

pyinaturalist.node_api.get_places_nearby(**params)[source]¶

Given an bounding box, and an optional name query, return places nearby

API reference: https://api.inaturalist.org/v1/docs/#!/Places/get_places_nearby

Example

>>> bounding_box = (150.0, -50.0, -149.999, -49.999)
>>> response = get_places_nearby(*bounding_box)

Response is split into standard (curated) places and community (non-curated) places:

>>> print(len(response['results']['standard']))
10
>>> print(len(response['results']['community']))
10

Show basic info for all places in response:

>>> print(format_places(response, align=True))
Standard:
[97394  ] North America
[97395  ] Asia
[97393  ] Oceania
...
Community:
[166719  ] Burgenland (accurate border)
[11770   ] Mehedinti
[119755  ] Mahurangi College
...

Example Response

{
    'total_results': 2,
    'page': 1,
    'per_page': 2,
    'results': {
        'standard': [
            {
                'ancestor_place_ids': None,
                'bounding_box_geojson': {
                    'coordinates': [
                        [
                            [0.0132, 5.4508],
                            [0.0132, 83.7083],
                            [-0.0033, 83.7083],
                            [-0.0033, 5.4508],
                            [0.0132, 5.4508],
                        ]
                    ],
                    'type': 'Polygon',
                },
                'bbox_area': 28171.40875125,
                'admin_level': -1,
                'place_type': 29,
                'name': 'North America',
                'location': [56.7732555574, -179.68825],
                'id': 97394,
                'display_name': 'North America',
                'uuid': '22e0b04f-5efe-4383-a167-95079e1d5ce1',
                'slug': 'north-america',
                'geometry_geojson': {'coordinates': 'TRUNCATED', 'type': 'MultiPolygon'},
            }
        ],
        'community': [
            {
                'ancestor_place_ids': [97391, 8858, 11770],
                'bounding_box_geojson': {
                    'coordinates': [
                        [
                            [22.004324, 44.104093],
                            [22.004324, 45.119544],
                            [23.481443, 45.119544],
                            [23.481443, 44.104093],
                            [22.004324, 44.104093],
                        ]
                    ],
                    'type': 'Polygon',
                },
                'bbox_area': 1.49994196566895,
                'admin_level': None,
                'place_type': 8,
                'name': 'Mehedinti',
                'location': [44.6118185, 22.7428835],
                'id': 11770,
                'display_name': 'Mehedinti, RO',
                'uuid': 'efa6a122-7d25-4342-a452-15c7036f6e44',
                'slug': 'mehedinti',
                'geometry_geojson': {'coordinates': 'TRUNCATED', 'type': 'Polygon'},
            }
        ],
    },
}

Parameters

nelat (float) – NE latitude of bounding box
nelng (float) – NE longitude of bounding box
swlat (float) – SW latitude of bounding box
swlng (float) – SW longitude of bounding box
name (str) – Name must match this value
user_agent (str) – A custom user-agent string to provide to the iNaturalist API

Return type

Dict[str, Any]

Returns

Response dict containing place records, divided into ‘standard’ and ‘community’ places.

pyinaturalist.node_api.get_projects(**params)[source]¶

Given zero to many of following parameters, get projects matching the search criteria.

API reference: https://api.inaturalist.org/v1/docs/#!/Projects/get_projects

Example

Search for projects about invasive species within 400km of Vancouver, BC:

>>> response = get_projects(
>>>     q='invasive',
>>>     lat=49.27,
>>>     lng=-123.08,
>>>     radius=400,
>>>     order_by='distance',
>>> )

Show basic info for projects in response:

>>> print(format_projects(response, align=True))
[8291    ] PNW Invasive Plant EDDR
[19200   ] King County (WA) Noxious and Invasive Weeds
[102925  ] Keechelus/Kachess Invasive Plants
...

Example Response

from datetime import datetime
from dateutil.tz import tzutc

{
    'total_results': 5,
    'page': 1,
    'per_page': 5,
    'results': [
        {
            'icon': 'https://www.inaturalist.org/attachment_defaults/general/span2.png',
            'flags': [],
            'description': 'To identify plants to report to the Pacific Northwest Invasive Plant Council',
            'created_at': datetime(2016, 7, 20, 23, 0, 5, tzinfo=tzutc()),
            'title': 'PNW Invasive Plant EDDR',
            'banner_color': None,
            'project_observation_rules': [],
            'site_features': [],
            'project_observation_fields': [],
            'updated_at': datetime(2020, 12, 21, 18, 11, 26, tzinfo=tzutc()),
            'terms': None,
            'prefers_user_trust': False,
            'id': 8291,
            'slug': 'pnw-invasive-plant-eddr',
            'place_id': None,
            'icon_file_name': None,
            'project_type': '',
            'user_ids': [
                19344,
                233188,
                300949,
                433100,
                450943,
                484450,
                550199,
                705929,
                800947,
                1257963,
                1299400,
                1325105,
                1447496,
                1559261,
                1572257,
                1574151,
                1781965,
                1935125,
                1973277,
                2025991,
                2026024,
                2069171,
                2162268,
                2269792,
                2354291,
                2410332,
                2453818,
                2499882,
                2581775,
                2714743,
                3145074,
                3272396,
                3387092,
                3908364,
            ],
            'header_image_file_name': None,
            'search_parameters': [
                {
                    'field': 'quality_grade',
                    'value': ['research', 'needs_id'],
                    'value_keyword': ['research', 'needs_id'],
                }
            ],
            'rule_preferences': [{'field': 'quality_grade', 'value': 'research,needs_id'}],
            'user_id': 233188,
            'hide_title': False,
            'location': [48.777404, -122.306929],
            'header_image_contain': False,
            'admins': [
                {
                    'role': 'manager',
                    'user_id': 233188,
                    'project_id': 8291,
                    'id': 142985,
                    'user': {
                        'id': 233188,
                        'login': 'borsope',
                        'spam': False,
                        'suspended': False,
                        'created_at': '2016-05-08T14:01:17+00:00',
                        'login_autocomplete': 'borsope',
                        'login_exact': 'borsope',
                        'name': 'Pam Borso',
                        'name_autocomplete': 'Pam Borso',
                        'orcid': None,
                        'icon': None,
                        'observations_count': 3164,
                        'identifications_count': 0,
                        'journal_posts_count': 0,
                        'activity_count': 3164,
                        'species_count': 1346,
                        'universal_search_rank': 3164,
                        'roles': [],
                        'site_id': 1,
                        'icon_url': None,
                    },
                }
            ],
            'header_image_url': None,
            'latitude': 48.777404,
            'longitude': -122.306929,
            'is_umbrella': False,
            'user': {
                'id': 233188,
                'login': 'borsope',
                'spam': False,
                'suspended': False,
                'created_at': '2016-05-08T14:01:17+00:00',
                'login_autocomplete': 'borsope',
                'login_exact': 'borsope',
                'name': 'Pam Borso',
                'name_autocomplete': 'Pam Borso',
                'orcid': None,
                'icon': None,
                'observations_count': 3164,
                'identifications_count': 0,
                'journal_posts_count': 0,
                'activity_count': 3164,
                'species_count': 1346,
                'universal_search_rank': 3164,
                'roles': [],
                'site_id': 1,
                'icon_url': None,
            },
        },
    ],
}

Parameters

q (str) – Project name must begin with this value
id (Union[int, List[int]]) – Must have this ID
not_id (Union[int, List[int]]) – Must not have this ID
lat (float) – Must be within a radius kilometer circle around this lat/lng
lng (float) – Must be within a radius kilometer circle around this lat/lng
radius (int) – Distance from center ((lat, lng)) to search, in kilometers. Defaults to 500km.
featured (bool) – Must be marked featured for the relevant site
noteworthy (bool) – Must be marked noteworthy for the relevant site
place_id (Union[int, List[int]]) – Must be in the place with this ID
site_id (int) – Site ID that applies to featured and noteworthy. Defaults to the site of the authenticated user, or to the main iNaturalist site
rule_details (bool) – Return more information about project rules, for example return a full taxon object instead of simply an ID
type (Union[str, List[str]]) – Projects must be of this type
member_id (int) – Project must have member with this user ID
has_params (bool) – Must have search parameter requirements
has_posts (bool) – Must have posts
order_by (str) – Sort order. distance only applies if lat and lng are specified. featured only applies if featured or noteworthy are true.
page (int) – Page number of results to return
per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (str) – Sort order
order_by – Field to sort on
count_only (bool) – Only return a count of results; alias for per_page=0
user_agent (str) – A custom user-agent string to provide to the iNaturalist API

Return type

Dict[str, Any]

Returns

Response dict containing project records

pyinaturalist.node_api.get_projects_by_id(project_id, rule_details=None, user_agent=None)[source]¶

Get one or more projects by ID.

API reference: https://api.inaturalist.org/v1/docs/#!/Projects/get_projects_id

Example

>>> response = get_projects_by_id([8348, 6432])
>>> print(format_projects(response))
[8348] Tucson High Native and Invasive Species Inventory
[6432] CBWN Invasive Plants

Example Response

from datetime import datetime
from dateutil.tz import tzutc

{
    'total_results': 1,
    'page': 1,
    'per_page': 1,
    'results': [
        {
            'icon': 'https://static.inaturalist.org/projects/8348-icon-span2.JPG?1505526661',
            'flags': [],
            'description': 'The purpose of this project is to document the native and invasive species (including plants, animals and fungus) present on the Tucson High campus. This is an on-going, open project, with the goal of helping students learn the difference between native and non-native species. ',
            'created_at': datetime(2016, 7, 26, 23, 8, 47, tzinfo=tzutc()),
            'title': 'Tucson High Native and Invasive Species Inventory',
            'banner_color': None,
            'project_observation_rules': [],
            'site_features': [],
            'project_observation_fields': [],
            'updated_at': datetime(2017, 9, 16, 1, 51, 1, tzinfo=tzutc()),
            'terms': None,
            'id': 8348,
            'slug': 'tucson-high-native-and-invasive-species-inventory',
            'place_id': 96103,
            'icon_file_name': 'IMG_1263.JPG',
            'project_type': '',
            'user_ids': [84403, 311743],
            'header_image_file_name': None,
            'search_parameters': [
                {
                    'field': 'quality_grade',
                    'value': ['research', 'needs_id'],
                    'value_keyword': ['research', 'needs_id'],
                },
                {'field': 'place_id', 'value_number': [96103], 'value': [96103]},
            ],
            'rule_preferences': [{'field': 'quality_grade', 'value': 'research,needs_id'}],
            'user_id': 84403,
            'hide_title': False,
            'location': [32.2264416406, -110.9617278383],
            'header_image_contain': False,
            'admins': [
                {
                    'role': 'manager',
                    'user_id': 84403,
                    'project_id': 8348,
                    'id': 144092,
                    'user': {
                        'id': 84403,
                        'login': 'ebmartin',
                        'spam': False,
                        'suspended': False,
                        'created_at': '2015-03-20T22:53:09+00:00',
                        'login_autocomplete': 'ebmartin',
                        'login_exact': 'ebmartin',
                        'name': 'Elena Martin',
                        'name_autocomplete': 'Elena Martin',
                        'orcid': None,
                        'icon': 'https://static.inaturalist.org/attachments/users/icons/84403/thumb.jpg?1475546770',
                        'observations_count': 50,
                        'identifications_count': 0,
                        'journal_posts_count': 0,
                        'activity_count': 50,
                        'species_count': 29,
                        'universal_search_rank': 50,
                        'roles': [],
                        'site_id': 1,
                        'icon_url': 'https://static.inaturalist.org/attachments/users/icons/84403/medium.jpg?1475546770',
                    },
                }
            ],
            'header_image_url': None,
            'latitude': 32.2264416406,
            'longitude': -110.9617278383,
            'is_umbrella': False,
            'user': {
                'id': 84403,
                'login': 'ebmartin',
                'spam': False,
                'suspended': False,
                'created_at': '2015-03-20T22:53:09+00:00',
                'login_autocomplete': 'ebmartin',
                'login_exact': 'ebmartin',
                'name': 'Elena Martin',
                'name_autocomplete': 'Elena Martin',
                'orcid': None,
                'icon': 'https://static.inaturalist.org/attachments/users/icons/84403/thumb.jpg?1475546770',
                'observations_count': 50,
                'identifications_count': 0,
                'journal_posts_count': 0,
                'activity_count': 50,
                'species_count': 29,
                'universal_search_rank': 50,
                'roles': [],
                'site_id': 1,
                'icon_url': 'https://static.inaturalist.org/attachments/users/icons/84403/medium.jpg?1475546770',
            },
        }
    ],
}

Parameters

project_id (Union[int, List[int]]) – Get projects with this ID. Multiple values are allowed.
rule_details (Optional[bool]) – Return more information about project rules, for example return a full taxon object instead of simply an ID
user_agent (Optional[str]) –

Return type

Dict[str, Any]

Returns

Response dict containing project records

pyinaturalist.node_api.get_taxa(**params)[source]¶

Given zero to many of following parameters, get taxa matching the search criteria.

API reference: https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa

Example

>>> response = get_taxa(q='vespi', rank=['genus', 'family'])
>>> print(format_taxa(response))
[52747] Family: Vespidae (Hornets, Paper Wasps, Potter Wasps, and Allies)
[92786] Genus: Vespicula
[646195] Genus: Vespiodes
...

Example Response

{
  "total_results": 35,
  "page": 1,
  "per_page": 30,
  "results": [
    {
      "observations_count": 336,
      "taxon_schemes_count": 2,
      "ancestry": "48460/1/47120/372739/47158/184884/47208/71130/372870/48311/53849/204079/53850",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": "http://en.wikipedia.org/wiki/Nicrophorus_vespilloides",
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 53850,
      "name": "Nicrophorus vespilloides",
      "rank": "species",
      "extinct": false,
      "id": 70118,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/38359335/square.jpg?1557348751",
        "attribution": "(c) salvatore_infanti, some rights reserved (CC BY-NC)",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/38359335/medium.jpg?1557348751",
        "id": 38359335,
        "license_code": "cc-by-nc",
        "original_dimensions": {
          "width": 2048,
          "height": 1365
        },
        "url": "https://static.inaturalist.org/photos/38359335/square.jpg?1557348751"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47208,
        71130,
        372870,
        48311,
        53849,
        204079,
        53850,
        70118
      ],
      "matched_term": "Nicrophorus vespilloides",
      "iconic_taxon_name": "Insecta",
      "preferred_common_name": "Lesser Vespillo Burying Beetle"
    },
    {
      "observations_count": 187,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47208/71130/372870/48311/53849/204079/53850",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": "http://en.wikipedia.org/wiki/Nicrophorus_vespillo",
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 53850,
      "name": "Nicrophorus vespillo",
      "rank": "species",
      "extinct": false,
      "id": 131878,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/24573164/square.jpg?1536478624",
        "attribution": "(c) Robin Bad, some rights reserved (CC BY-NC)",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/24573164/medium.jpg?1536478624",
        "id": 24573164,
        "license_code": "cc-by-nc",
        "original_dimensions": {
          "width": 2048,
          "height": 1365
        },
        "url": "https://static.inaturalist.org/photos/24573164/square.jpg?1536478624"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47208,
        71130,
        372870,
        48311,
        53849,
        204079,
        53850,
        131878
      ],
      "matched_term": "Nicrophorus vespillo",
      "iconic_taxon_name": "Insecta",
      "preferred_common_name": "Vespillo Burying Beetle"
    },
    {
      "observations_count": 55,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47822/48091/372853/414448/49995/326181/488425/520026/124163",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": "http://en.wikipedia.org/wiki/Temnostoma_vespiforme",
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 124163,
      "name": "Temnostoma vespiforme",
      "rank": "species",
      "extinct": false,
      "id": 124162,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/5925301/square.jpg?1545677110",
        "attribution": "(c) Ouwesok, alguns direitos reservados (CC BY-NC)",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/5925301/medium.jpg?1545677110",
        "id": 5925301,
        "license_code": "cc-by-nc",
        "original_dimensions": {
          "width": 1200,
          "height": 1200
        },
        "url": "https://static.inaturalist.org/photos/5925301/square.jpg?1545677110"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47822,
        48091,
        372853,
        414448,
        49995,
        326181,
        488425,
        520026,
        124163,
        124162
      ],
      "matched_term": "Temnostoma vespiforme",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 39,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47157/122746/51573/456401/366342/51684",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": "http://en.wikipedia.org/wiki/Synanthedon_vespiformis",
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 51684,
      "name": "Synanthedon vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 362871,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/1014675/square.jpg?1545557196",
        "attribution": "(c) Tony Morris, some rights reserved (CC BY-NC)",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/1014675/medium.jpg?1545557196",
        "id": 1014675,
        "license_code": "cc-by-nc",
        "original_dimensions": {
          "width": 551,
          "height": 473
        },
        "url": "https://static.inaturalist.org/photos/1014675/square.jpg?1545557196"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47157,
        122746,
        51573,
        456401,
        366342,
        51684,
        362871
      ],
      "matched_term": "S\u00e9sie vespiforme",
      "iconic_taxon_name": "Insecta",
      "preferred_common_name": "Yellow-legged Clearwing"
    },
    {
      "observations_count": 29,
      "taxon_schemes_count": 2,
      "ancestry": "48460/1/47120/372739/47158/184884/83201/372872/245155/252574",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": "http://en.wikipedia.org/wiki/Franklinothrips_vespiformis",
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 252574,
      "name": "Franklinothrips vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 270746,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/5079943/square.jpg?1475364205",
        "attribution": "Sem direitos reservados",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/5079943/medium.jpg?1475364205",
        "id": 5079943,
        "license_code": "cc0",
        "original_dimensions": {
          "width": 819,
          "height": 797
        },
        "url": "https://static.inaturalist.org/photos/5079943/square.jpg?1475364205"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        83201,
        372872,
        245155,
        252574,
        270746
      ],
      "matched_term": "Franklinothrips vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 12,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47201/124417/326777/48740/52747/119344",
      "is_active": true,
      "flag_counts": {
        "unresolved": 1,
        "resolved": 2
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 119344,
      "name": "Vespidae st1",
      "rank": "species",
      "extinct": false,
      "id": 495392,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/5563170/square.jpg?1479599057",
        "attribution": "(c) Stephen Thorpe, some rights reserved (CC BY-NC)",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/5563170/medium.jpg?1479599057",
        "id": 5563170,
        "license_code": "cc-by-nc",
        "original_dimensions": {
          "width": 781,
          "height": 925
        },
        "url": "https://static.inaturalist.org/photos/5563170/square.jpg?1479599057"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47201,
        124417,
        326777,
        48740,
        52747,
        119344,
        495392
      ],
      "matched_term": "Vespidae st1",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 11,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47822/48091/372853/414448/49995/326181/520014/125658",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": "http://en.wikipedia.org/wiki/Ceriana_vespiformis",
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 125658,
      "name": "Ceriana vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 466251,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/3035009/square.jpg?1545634240",
        "attribution": "(c) gailhampshire, some rights reserved (CC BY)",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/3035009/medium.jpg?1545634240",
        "id": 3035009,
        "license_code": "cc-by",
        "original_dimensions": {
          "width": 832,
          "height": 704
        },
        "url": "https://static.inaturalist.org/photos/3035009/square.jpg?1545634240"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47822,
        48091,
        372853,
        414448,
        49995,
        326181,
        520014,
        125658,
        466251
      ],
      "matched_term": "Ceriana vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 7,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47201/124417/326777/47222/51955/210928/210927/507574/53067",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 53067,
      "name": "Bembix vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 882585,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/33808490/square.jpeg?1554036738",
        "attribution": "(c) birdnerd1, all rights reserved",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/33808490/medium.jpeg?1554036738",
        "id": 33808490,
        "license_code": null,
        "original_dimensions": {
          "width": 795,
          "height": 1200
        },
        "url": "https://static.inaturalist.org/photos/33808490/square.jpeg?1554036738"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47201,
        124417,
        326777,
        47222,
        51955,
        210928,
        210927,
        507574,
        53067,
        882585
      ],
      "matched_term": "Bembix vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 7,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47744/61267/372850/133754/48959/320199/482431/129424",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 129424,
      "name": "Zelus vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 633966,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/5292283/square.jpg?1477056217",
        "attribution": "(c) Paul, all rights reserved, uploaded by creaturesnapper",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/5292283/medium.jpg?1477056217",
        "id": 5292283,
        "license_code": null,
        "original_dimensions": {
          "width": 1580,
          "height": 1064
        },
        "url": "https://static.inaturalist.org/photos/5292283/square.jpg?1477056217"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47744,
        61267,
        372850,
        133754,
        48959,
        320199,
        482431,
        129424,
        633966
      ],
      "matched_term": "Zelus vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 4,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47201/124417/326777/48740/54028/201315/366768/563431",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 563431,
      "name": "Ctenagenia vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 560666,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/30741827/square.jpg?1548679524",
        "attribution": "(c) Paolo Mazzei, all rights reserved",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/30741827/medium.jpg?1548679524",
        "id": 30741827,
        "license_code": null,
        "original_dimensions": {
          "width": 800,
          "height": 600
        },
        "url": "https://static.inaturalist.org/photos/30741827/square.jpg?1548679524"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47201,
        124417,
        326777,
        48740,
        54028,
        201315,
        366768,
        563431,
        560666
      ],
      "matched_term": "Ctenagenia vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 4,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47201/124417/326777/48740/52747/343248/531700/752711",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 1,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 752711,
      "name": "Pseudopolybia vespiceps",
      "rank": "species",
      "extinct": false,
      "id": 752716,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/54013958/square.jpeg?1571007464",
        "attribution": "(c) adrianomaciel, all rights reserved",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/54013958/medium.jpeg?1571007464",
        "id": 54013958,
        "license_code": null,
        "original_dimensions": {
          "width": 2048,
          "height": 1536
        },
        "url": "https://static.inaturalist.org/photos/54013958/square.jpeg?1571007464"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47201,
        124417,
        326777,
        48740,
        52747,
        343248,
        531700,
        752711,
        752716
      ],
      "matched_term": "Pseudopolybia vespiceps vespiceps",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 3,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47201/124417/326777/48740/52747/119344/428969",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 428969,
      "name": "Hypodynerus vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 886207,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/29288906/square.jpg?1545155699",
        "attribution": "(c) cmg_pdx, some rights reserved (CC BY-NC)",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/29288906/medium.jpg?1545155699",
        "id": 29288906,
        "license_code": "cc-by-nc",
        "original_dimensions": {
          "width": 1065,
          "height": 795
        },
        "url": "https://static.inaturalist.org/photos/29288906/square.jpg?1545155699"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47201,
        124417,
        326777,
        48740,
        52747,
        119344,
        428969,
        886207
      ],
      "matched_term": "Hypodynerus vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 2,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47157/51269/51268",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": "http://en.wikipedia.org/wiki/Vespina",
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 20,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 51268,
      "name": "Vespina",
      "rank": "genus",
      "extinct": false,
      "id": 84737,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47157,
        51269,
        51268,
        84737
      ],
      "matched_term": "Vespina",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 2,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47744/61267/372868/51776/51777/319231/570423/605185",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 605185,
      "name": "Moronopelios vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 605184,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/8932829/square.jpg?1499613099",
        "attribution": "(c) kphuong7693, some rights reserved (CC BY-NC)",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/8932829/medium.jpg?1499613099",
        "id": 8932829,
        "license_code": "cc-by-nc",
        "original_dimensions": {
          "width": 1536,
          "height": 2048
        },
        "url": "https://static.inaturalist.org/photos/8932829/square.jpg?1499613099"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47744,
        61267,
        372868,
        51776,
        51777,
        319231,
        570423,
        605185,
        605184
      ],
      "matched_term": "Moronopelios vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 2,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47822/48091/372853/414448/49995/326181/488425/520024/465579",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 465579,
      "name": "Sphecomyia vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 876493,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/33293202/square.jpg?1553351857",
        "attribution": "(c) Andrei, some rights reserved (CC BY-NC)",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/33293202/medium.jpg?1553351857",
        "id": 33293202,
        "license_code": "cc-by-nc",
        "original_dimensions": {
          "width": 1480,
          "height": 1163
        },
        "url": "https://static.inaturalist.org/photos/33293202/square.jpg?1553351857"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47822,
        48091,
        372853,
        414448,
        49995,
        326181,
        488425,
        520024,
        465579,
        876493
      ],
      "matched_term": "Sphecomyia vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 1,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47822/48091/372865/354603/47982/639471/639475/623118",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 623118,
      "name": "Codula vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 983565,
      "default_photo": {
        "square_url": "https://static.inaturalist.org/photos/30581879/square.jpg?1548308953",
        "attribution": "(c) Richard Yank, all rights reserved",
        "flags": [],
        "medium_url": "https://static.inaturalist.org/photos/30581879/medium.jpg?1548308953",
        "id": 30581879,
        "license_code": null,
        "original_dimensions": {
          "width": 2048,
          "height": 1365
        },
        "url": "https://static.inaturalist.org/photos/30581879/square.jpg?1548308953"
      },
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47822,
        48091,
        372865,
        354603,
        47982,
        639471,
        639475,
        623118,
        983565
      ],
      "matched_term": "Codula vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/2/355675/47178/47286/51544/92786",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47178,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 92786,
      "complete_rank": "subspecies",
      "name": "Vespicula cypho",
      "rank": "species",
      "extinct": false,
      "id": 621584,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        2,
        355675,
        47178,
        47286,
        51544,
        92786,
        621584
      ],
      "matched_term": "Vespicula cypho",
      "iconic_taxon_name": "Actinopterygii"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/2/355675/47178/47286/51544/92786",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47178,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 92786,
      "complete_rank": "subspecies",
      "name": "Vespicula trachinoides",
      "rank": "species",
      "extinct": false,
      "id": 621585,
      "default_photo": {
        "square_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/16/FMIB_47485_Prosopodasys_gogorzae.jpeg/75px-FMIB_47485_Prosopodasys_gogorzae.jpeg",
        "attribution": "David Starr Jordan\n, no known copyright restrictions (public domain)",
        "flags": [],
        "medium_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/16/FMIB_47485_Prosopodasys_gogorzae.jpeg/500px-FMIB_47485_Prosopodasys_gogorzae.jpeg",
        "id": 33535972,
        "license_code": "pd",
        "original_dimensions": null,
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/16/FMIB_47485_Prosopodasys_gogorzae.jpeg/75px-FMIB_47485_Prosopodasys_gogorzae.jpeg"
      },
      "ancestor_ids": [
        48460,
        1,
        2,
        355675,
        47178,
        47286,
        51544,
        92786,
        621585
      ],
      "matched_term": "Vespicula trachinoides",
      "iconic_taxon_name": "Actinopterygii"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/2/355675/47178/47286/51544/92786",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47178,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 92786,
      "complete_rank": "subspecies",
      "name": "Vespicula zollingeri",
      "rank": "species",
      "extinct": false,
      "id": 621586,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        2,
        355675,
        47178,
        47286,
        51544,
        92786,
        621586
      ],
      "matched_term": "Vespicula zollingeri",
      "iconic_taxon_name": "Actinopterygii"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 0,
      "ancestry": "48460/1/47120/372739/47158/184884/47201/124417/326777/48740/51967/469073/893840",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 893840,
      "name": "Pygodasis vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 915291,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47201,
        124417,
        326777,
        48740,
        51967,
        469073,
        893840,
        915291
      ],
      "matched_term": "Pygodasis vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/47170/48250/83715/83716/200006/450114",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47170,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 450114,
      "name": "Candida vespimorsuum",
      "rank": "species",
      "extinct": false,
      "id": 554174,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        47170,
        48250,
        83715,
        83716,
        200006,
        450114,
        554174
      ],
      "matched_term": "Candida vespimorsuum",
      "iconic_taxon_name": "Fungi"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 2,
      "ancestry": "48460/1/47120/372739/47158/184884/47201/124417/69750/125448/519360/250566",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 250566,
      "name": "Vespita woolleyi",
      "rank": "species",
      "extinct": false,
      "id": 299443,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47201,
        124417,
        69750,
        125448,
        519360,
        250566,
        299443
      ],
      "matched_term": "Vespita woolleyi",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47157/47607/121850/47606/82089/82101/47988",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 47988,
      "name": "Argyroeides vespina",
      "rank": "species",
      "extinct": false,
      "id": 907874,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47157,
        47607,
        121850,
        47606,
        82089,
        82101,
        47988,
        907874
      ],
      "matched_term": "Argyroeides vespina",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47822/48091/372865/354603/121526/699633",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 20,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 699633,
      "name": "Vespiodes",
      "rank": "genus",
      "extinct": false,
      "id": 646195,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47822,
        48091,
        372865,
        354603,
        121526,
        699633,
        646195
      ],
      "matched_term": "Vespiodes",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/2/355675/47178/47286/51544",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": "http://en.wikipedia.org/wiki/Vespicula",
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47178,
      "rank_level": 20,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": 3,
      "parent_id": 51544,
      "complete_rank": "subspecies",
      "name": "Vespicula",
      "rank": "genus",
      "extinct": false,
      "id": 92786,
      "default_photo": {
        "square_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/16/FMIB_47485_Prosopodasys_gogorzae.jpeg/75px-FMIB_47485_Prosopodasys_gogorzae.jpeg",
        "attribution": "David Starr Jordan\n, no known copyright restrictions (public domain)",
        "flags": [],
        "medium_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/16/FMIB_47485_Prosopodasys_gogorzae.jpeg/500px-FMIB_47485_Prosopodasys_gogorzae.jpeg",
        "id": 33535972,
        "license_code": "pd",
        "original_dimensions": null,
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/16/FMIB_47485_Prosopodasys_gogorzae.jpeg/75px-FMIB_47485_Prosopodasys_gogorzae.jpeg"
      },
      "ancestor_ids": [
        48460,
        1,
        2,
        355675,
        47178,
        47286,
        51544,
        92786
      ],
      "matched_term": "Vespicula",
      "iconic_taxon_name": "Actinopterygii"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 2,
      "ancestry": "48460/1/47120/372739/47158/184884/47208/71130/372870/48311/47951/373525/211904",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 211904,
      "name": "Pseudopsis vespina",
      "rank": "species",
      "extinct": false,
      "id": 267991,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47208,
        71130,
        372870,
        48311,
        47951,
        373525,
        211904,
        267991
      ],
      "matched_term": "Pseudopsis vespina",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/245097/47119/47118/120474/342614/367172/60351/60357",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47119,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 60357,
      "complete_rank": "subspecies",
      "name": "Mimetus vespillo",
      "rank": "species",
      "extinct": false,
      "id": 833068,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        47120,
        245097,
        47119,
        47118,
        120474,
        342614,
        367172,
        60351,
        60357,
        833068
      ],
      "matched_term": "Mimetus vespillo",
      "iconic_taxon_name": "Arachnida"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47201/124417/326777/47222/630955/47221/335715/340736/252728/572378",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 572378,
      "name": "Odyneropsis vespiformis",
      "rank": "species",
      "extinct": false,
      "id": 572367,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47201,
        124417,
        326777,
        47222,
        630955,
        47221,
        335715,
        340736,
        252728,
        572378,
        572367
      ],
      "matched_term": "Odyneropsis vespiformis",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47201/124417/69750/125448/519360",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": null,
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 20,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 519360,
      "name": "Vespita",
      "rank": "genus",
      "extinct": false,
      "id": 250566,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47201,
        124417,
        69750,
        125448,
        519360,
        250566
      ],
      "matched_term": "Vespita",
      "iconic_taxon_name": "Insecta"
    },
    {
      "observations_count": 0,
      "taxon_schemes_count": 1,
      "ancestry": "48460/1/47120/372739/47158/184884/47157/51269/51268/84737",
      "is_active": true,
      "flag_counts": {
        "unresolved": 0,
        "resolved": 0
      },
      "wikipedia_url": "http://en.wikipedia.org/wiki/Vespina_quercivora",
      "current_synonymous_taxon_ids": null,
      "iconic_taxon_id": 47158,
      "rank_level": 10,
      "taxon_changes_count": 0,
      "atlas_id": null,
      "complete_species_count": null,
      "parent_id": 84737,
      "name": "Vespina quercivora",
      "rank": "species",
      "extinct": false,
      "id": 472528,
      "default_photo": null,
      "ancestor_ids": [
        48460,
        1,
        47120,
        372739,
        47158,
        184884,
        47157,
        51269,
        51268,
        84737,
        472528
      ],
      "matched_term": "Vespina quercivora",
      "iconic_taxon_name": "Insecta"
    }
  ]
}

Parameters

q (str) – Name must begin with this value
is_active (bool) – Taxon is active
taxon_id (int) – Only show taxa with this ID, or its descendants
rank (str) – Taxon must have this exact rank
min_rank (str) – Taxon must have this rank or higher; overrides rank
max_rank (str) – Taxon must have this rank or lower; overrides rank
rank_level (int) – 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)
locale (str) – Locale preference for taxon common names
preferred_place_id (int) – Place preference for regional taxon common names
all_names (bool) – Include all taxon names in the response
id_above (int) – Must have an ID above this value
id_below (int) – Must have an ID below this value
only_id (int) – Return only the record IDs
parent_id (int) – Taxon’s parent must have this ID
page (int) – Page number of results to return
per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (str) – Sort order
order_by (str) – Field to sort on
count_only (bool) – Only return a count of results; alias for per_page=0
user_agent (str) – A custom user-agent string to provide to the iNaturalist API

Return type

Dict[str, Any]

Returns

Response dict containing taxon records

pyinaturalist.node_api.get_taxa_autocomplete(**params)[source]¶

Given a query string, return taxa with names starting with the search term

API reference: 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.

Example

Get just the name of the first matching taxon:

>>> response = get_taxa_autocomplete(q='vespi')
>>> print(response['results'][0]['name'])
'Vespidae'

Get basic info for taxa in response:

>>> print(format_taxa(response, align=True))
[52747   ]       Family: Vespidae (Hornets, Paper Wasps, Potter Wasps, and Allies)
[84738   ]    Subfamily: Vespinae (Hornets and Yellowjackets)
[131878  ]      Species: Nicrophorus vespillo (Vespillo Burying Beetle)

If you get unexpected matches, the search likely matched a synonym, either in the form of a common name or an alternative classification. Check the matched_term property for more info. For example:

>>> first_result = get_taxa_autocomplete(q='zygoca')['results'][0]
>>> first_result["name"]
"Schlumbergera truncata"  # This doesn't look like our search term!
>>> first_result["matched_term"]
"Zygocactus truncatus"    # ...Because it matched an older synonym for Schlumbergera

Example Response

{
    'total_results': 3,
    'page': 1,
    'per_page': 10,
    'results': [
        {
            'observations_count': 235680,
            'taxon_schemes_count': 2,
            'ancestry': '48460/1/47120/372739/47158/184884/47201/124417/326777/48740',
            'is_active': True,
            'flag_counts': {'unresolved': 0, 'resolved': 1},
            'wikipedia_url': 'http://en.wikipedia.org/wiki/Vespidae',
            'current_synonymous_taxon_ids': None,
            'iconic_taxon_id': 47158,
            'rank_level': 30,
            'taxon_changes_count': 0,
            'atlas_id': None,
            'complete_species_count': None,
            'parent_id': 48740,
            'name': 'Vespidae',
            'rank': 'family',
            'extinct': False,
            'id': 52747,
            'default_photo': {
                'square_url': 'https://static.inaturalist.org/photos/13765/square.jpg?1545358964',
                'attribution': '(c) CÃ©cile Bassaglia, some rights reserved (CC BY-NC-SA)',
                'flags': [],
                'medium_url': 'https://static.inaturalist.org/photos/13765/medium.jpg?1545358964',
                'id': 13765,
                'license_code': 'cc-by-nc-sa',
                'original_dimensions': {'width': 1024, 'height': 679},
                'url': 'https://static.inaturalist.org/photos/13765/square.jpg?1545358964',
            },
            'ancestor_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47201,
                124417,
                326777,
                48740,
                52747,
            ],
            'matched_term': 'Vespidae',
            'iconic_taxon_name': 'Insecta',
            'preferred_common_name': 'Hornets, Paper Wasps, Potter Wasps, and Allies',
        },
        {
            'observations_count': 74782,
            'taxon_schemes_count': 1,
            'ancestry': '48460/1/47120/372739/47158/184884/47201/124417/326777/48740/52747',
            'is_active': True,
            'flag_counts': {'unresolved': 1, 'resolved': 0},
            'wikipedia_url': 'http://en.wikipedia.org/wiki/Vespinae',
            'current_synonymous_taxon_ids': None,
            'iconic_taxon_id': 47158,
            'rank_level': 27,
            'taxon_changes_count': 0,
            'atlas_id': None,
            'complete_species_count': None,
            'parent_id': 52747,
            'name': 'Vespinae',
            'rank': 'subfamily',
            'extinct': False,
            'id': 84738,
            'default_photo': {
                'square_url': 'https://static.inaturalist.org/photos/11374710/square.jpg?1508777024',
                'attribution': '(c) Arnold Wijker, some rights reserved (CC BY-NC)',
                'flags': [],
                'medium_url': 'https://static.inaturalist.org/photos/11374710/medium.jpg?1508777024',
                'id': 11374710,
                'license_code': 'cc-by-nc',
                'original_dimensions': {'width': 800, 'height': 639},
                'url': 'https://static.inaturalist.org/photos/11374710/square.jpg?1508777024',
            },
            'ancestor_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47201,
                124417,
                326777,
                48740,
                52747,
                84738,
            ],
            'matched_term': 'Vespinae',
            'iconic_taxon_name': 'Insecta',
            'preferred_common_name': 'Hornets and Yellowjackets',
        },
        {
            'observations_count': 610,
            'taxon_schemes_count': 1,
            'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372870/48311/53849/204079/53850',
            'is_active': True,
            'flag_counts': {'unresolved': 0, 'resolved': 0},
            'wikipedia_url': 'http://en.wikipedia.org/wiki/Nicrophorus_vespillo',
            'current_synonymous_taxon_ids': None,
            'iconic_taxon_id': 47158,
            'rank_level': 10,
            'taxon_changes_count': 0,
            'atlas_id': None,
            'complete_species_count': None,
            'parent_id': 53850,
            'name': 'Nicrophorus vespillo',
            'rank': 'species',
            'extinct': False,
            'id': 131878,
            'default_photo': {
                'square_url': 'https://static.inaturalist.org/photos/24573164/square.jpg?1536478624',
                'attribution': '(c) Nikolai Vladimirov, some rights reserved (CC BY-NC)',
                'flags': [],
                'medium_url': 'https://static.inaturalist.org/photos/24573164/medium.jpg?1536478624',
                'id': 24573164,
                'license_code': 'cc-by-nc',
                'original_dimensions': {'width': 2048, 'height': 1365},
                'url': 'https://static.inaturalist.org/photos/24573164/square.jpg?1536478624',
            },
            'ancestor_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47208,
                71130,
                372870,
                48311,
                53849,
                204079,
                53850,
                131878,
            ],
            'matched_term': 'Nicrophorus vespillo',
            'iconic_taxon_name': 'Insecta',
            'preferred_common_name': 'Vespillo Burying Beetle',
        },
    ],
}

Example Response (formatted)

[
    "   52747:       Family Vespidae (Hornets, Paper Wasps, Potter Wasps, and Allies)",
    "   84738:    Subfamily Vespinae (Hornets and Yellowjackets)",
    "  131878:      Species Nicrophorus vespillo (Vespillo Burying Beetle)",
    "  621585:      Species Vespicula trachinoides (Vespicula Waspfish)",
    "  495392:      Species Vespidae st1",
    "   70118:      Species Nicrophorus vespilloides (Lesser Vespillo Burying Beetle)",
    "   92786:        Genus Vespicula",
    "  646195:        Genus Vespiodes",
    "  621584:      Species Vespicula cypho",
    "  621586:      Species Vespicula zollingeri",
]

Parameters

q (str) – Name must begin with this value
is_active (bool) – Taxon is active
taxon_id (int) – Only show taxa with this ID, or its descendants
rank (str) – Taxon must have this exact rank
min_rank (str) – Taxon must have this rank or higher; overrides rank
max_rank (str) – Taxon must have this rank or lower; overrides rank
rank_level (int) – 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)
locale (str) – Locale preference for taxon common names
preferred_place_id (int) – Place preference for regional taxon common names
all_names (bool) – Include all taxon names in the response
user_agent (str) – A custom user-agent string to provide to the iNaturalist API

Return type

Dict[str, Any]

Returns

Response dict containing taxon records

pyinaturalist.node_api.get_taxa_by_id(taxon_id, user_agent=None)[source]¶

Get one or more taxa by ID.

API reference: https://api.inaturalist.org/v1/docs/#!/Taxa/get_taxa_id

Example

>>> response = get_taxa_by_id(343248)
>>> basic_fields = ['preferred_common_name', 'observations_count', 'wikipedia_url', 'wikipedia_summary']
>>> print({f: response['results'][0][f] for f in basic_fields})
{
    'preferred_common_name': 'Paper Wasps',
    'observations_count': 69728,
    'wikipedia_url': 'http://en.wikipedia.org/wiki/Polistinae',
    'wikipedia_summary': 'The Polistinae are eusocial wasps closely related to yellow jackets...',
}

Example Response

{
    'total_results': 1,
    'page': 1,
    'per_page': 30,
    'results': [
        {
            'photos_locked': False,
            'observations_count': 112516,
            'taxon_schemes_count': 1,
            'ancestry': '48460/1/47120/372739/47158/184884/47201/124417/326777/48740/52747',
            'is_active': True,
            'flag_counts': {'unresolved': 0, 'resolved': 0},
            'wikipedia_url': 'http://en.wikipedia.org/wiki/Polistinae',
            'current_synonymous_taxon_ids': None,
            'iconic_taxon_id': 47158,
            'taxon_photos': [
                {
                    'taxon_id': 343248,
                    'photo': {
                        'flags': [],
                        'type': 'LocalPhoto',
                        'url': 'https://static.inaturalist.org/photos/22765568/square.jpeg?1533696452',
                        'square_url': 'https://static.inaturalist.org/photos/22765568/square.jpeg?1533696452',
                        'native_page_url': 'https://www.inaturalist.org/photos/22765568',
                        'native_photo_id': '22765568',
                        'small_url': 'https://static.inaturalist.org/photos/22765568/small.jpeg?1533696452',
                        'original_url': 'https://static.inaturalist.org/photos/22765568/original.jpeg?1533696452',
                        'attribution': '(c) copper, some rights reserved (CC BY-NC)',
                        'medium_url': 'https://static.inaturalist.org/photos/22765568/medium.jpeg?1533696452',
                        'id': 22765568,
                        'license_code': 'cc-by-nc',
                        'original_dimensions': {'width': 2048, 'height': 1639},
                        'large_url': 'https://static.inaturalist.org/photos/22765568/large.jpeg?1533696452',
                    },
                    'taxon': {
                        'photos_locked': False,
                        'taxon_schemes_count': 1,
                        'ancestry': '48460/1/47120/372739/47158/184884/47201/124417/326777/48740/52747',
                        'min_species_ancestry': '48460,1,47120,372739,47158,184884,47201,124417,326777,48740,52747,343248',
                        'wikipedia_url': 'http://en.wikipedia.org/wiki/Polistinae',
                        'current_synonymous_taxon_ids': None,
                        'iconic_taxon_id': 47158,
                        'created_at': '2014-02-19T09:17:40+00:00',
                        'taxon_changes_count': 0,
                        'complete_species_count': None,
                        'rank': 'subfamily',
                        'extinct': False,
                        'id': 343248,
                        'universal_search_rank': 112516,
                        'ancestor_ids': [
                            48460,
                            1,
                            47120,
                            372739,
                            47158,
                            184884,
                            47201,
                            124417,
                            326777,
                            48740,
                            52747,
                            343248,
                        ],
                        'observations_count': 112516,
                        'is_active': True,
                        'flag_counts': {'unresolved': 0, 'resolved': 0},
                        'min_species_taxon_id': 343248,
                        'rank_level': 27,
                        'atlas_id': None,
                        'parent_id': 52747,
                        'name': 'Polistinae',
                        'default_photo': {
                            'square_url': 'https://static.inaturalist.org/photos/22765568/square.jpeg?1533696452',
                            'attribution': '(c) copper, some rights reserved (CC BY-NC)',
                            'flags': [],
                            'medium_url': 'https://static.inaturalist.org/photos/22765568/medium.jpeg?1533696452',
                            'id': 22765568,
                            'license_code': 'cc-by-nc',
                            'original_dimensions': {'width': 2048, 'height': 1639},
                            'url': 'https://static.inaturalist.org/photos/22765568/square.jpeg?1533696452',
                        },
                        'iconic_taxon_name': 'Insecta',
                        'preferred_common_name': 'Paper Wasps',
                    },
                },
            ],
            'rank_level': 27,
            'taxon_changes_count': 0,
            'atlas_id': None,
            'complete_species_count': None,
            'parent_id': 52747,
            'name': 'Polistinae',
            'rank': 'subfamily',
            'extinct': False,
            'id': 343248,
            'default_photo': {
                'square_url': 'https://static.inaturalist.org/photos/22765568/square.jpeg?1533696452',
                'attribution': '(c) copper, some rights reserved (CC BY-NC)',
                'flags': [],
                'medium_url': 'https://static.inaturalist.org/photos/22765568/medium.jpeg?1533696452',
                'id': 22765568,
                'license_code': 'cc-by-nc',
                'original_dimensions': {'width': 2048, 'height': 1639},
                'url': 'https://static.inaturalist.org/photos/22765568/square.jpeg?1533696452',
            },
            'ancestor_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47201,
                124417,
                326777,
                48740,
                52747,
            ],
            'iconic_taxon_name': 'Insecta',
            'preferred_common_name': 'Paper Wasps',
            'ancestors': [
                {
                    'observations_count': 32873107,
                    'taxon_schemes_count': 2,
                    'ancestry': '48460',
                    'is_active': True,
                    'flag_counts': {'unresolved': 0, 'resolved': 9},
                    'wikipedia_url': 'http://en.wikipedia.org/wiki/Animal',
                    'current_synonymous_taxon_ids': None,
                    'iconic_taxon_id': 1,
                    'rank_level': 70,
                    'taxon_changes_count': 4,
                    'atlas_id': None,
                    'complete_species_count': None,
                    'parent_id': 48460,
                    'complete_rank': 'order',
                    'name': 'Animalia',
                    'rank': 'kingdom',
                    'extinct': False,
                    'id': 1,
                    'default_photo': {
                        'square_url': 'https://static.inaturalist.org/photos/80678745/square.jpg?1593020613',
                        'attribution': 'Ningún derecho reservado',
                        'flags': [],
                        'medium_url': 'https://static.inaturalist.org/photos/80678745/medium.jpg?1593020613',
                        'id': 80678745,
                        'license_code': 'cc0',
                        'original_dimensions': {'width': 2000, 'height': 2000},
                        'url': 'https://static.inaturalist.org/photos/80678745/square.jpg?1593020613',
                    },
                    'ancestor_ids': [48460, 1],
                    'iconic_taxon_name': 'Animalia',
                    'preferred_common_name': 'Animals',
                },
            ],
            'children': [
                {
                    'observations_count': 88534,
                    'taxon_schemes_count': 0,
                    'ancestry': '48460/1/47120/372739/47158/184884/47201/124417/326777/48740/52747/343248',
                    'is_active': True,
                    'flag_counts': {'unresolved': 0, 'resolved': 0},
                    'wikipedia_url': 'http://en.wikipedia.org/wiki/Polistes',
                    'current_synonymous_taxon_ids': None,
                    'iconic_taxon_id': 47158,
                    'rank_level': 25,
                    'taxon_changes_count': 0,
                    'atlas_id': None,
                    'complete_species_count': None,
                    'parent_id': 343248,
                    'name': 'Polistini',
                    'rank': 'tribe',
                    'extinct': False,
                    'id': 638567,
                    'default_photo': {
                        'square_url': 'https://static.inaturalist.org/photos/2367678/square.jpg?1441941708',
                        'attribution': '(c) Cheryl Harleston López Espino, some rights reserved (CC BY-NC-ND)',
                        'flags': [],
                        'medium_url': 'https://static.inaturalist.org/photos/2367678/medium.jpg?1441941708',
                        'id': 2367678,
                        'license_code': 'cc-by-nc-nd',
                        'original_dimensions': {'width': 900, 'height': 1200},
                        'url': 'https://static.inaturalist.org/photos/2367678/square.jpg?1441941708',
                    },
                    'ancestor_ids': [
                        48460,
                        1,
                        47120,
                        372739,
                        47158,
                        184884,
                        47201,
                        124417,
                        326777,
                        48740,
                        52747,
                        343248,
                        638567,
                    ],
                    'iconic_taxon_name': 'Insecta',
                },
            ],
            'conservation_statuses': [],
            'listed_taxa_count': 0,
            'listed_taxa': [],
            'wikipedia_summary': 'The <b>Polistinae</b> are eusocial wasps closely related to the more familiar yellow jackets, but placed in their own subfamily, containing four tribes; with some 1100 species total, it is the second-most diverse subfamily within the Vespidae, and while most species are tropical or subtropical, they include some of the most frequently encountered large wasps in temperate regions. They are also known as paper wasps, which is a misleading term since other wasps (including yellow jackets) also...',
        }
    ],
}

Parameters

taxon_id (Union[int, List[int]]) – Get taxa with this ID. Multiple values are allowed.
user_agent (Optional[str]) –

Return type

Dict[str, Any]

Returns

Response dict containing taxon records

pyinaturalist.node_api.get_user_by_id(user_id, user_agent=None)[source]¶

Get a user by ID.

API reference: https://api.inaturalist.org/v1/docs/#!/Users/get_users_id

Parameters

user_id (int) – Get the user with this ID. Only a single ID is allowed per request.
user_agent (Optional[str]) –

Return type

Dict[str, Any]

Example

>>> response = get_user_by_id(123456)
>>> print(format_users(response))
[1234] my_username

Example Response

from datetime import datetime
from dateutil.tz import tzutc

{
    'id': 1,
    'login': 'kueda',
    'spam': False,
    'suspended': False,
    'created_at': datetime(2008, 3, 20, 21, 15, 42, tzinfo=tzutc()),
    'login_autocomplete': 'kueda',
    'login_exact': 'kueda',
    'name': 'Ken-ichi Ueda',
    'name_autocomplete': 'Ken-ichi Ueda',
    'orcid': 'https://orcid.org/0000-0003-0145-6846',
    'icon': 'https://static.inaturalist.org/attachments/users/icons/1/thumb.jpg?1475527316',
    'observations_count': 40947,
    'identifications_count': 95624,
    'journal_posts_count': 86,
    'activity_count': 136657,
    'species_count': 8831,
    'universal_search_rank': 40947,
    'roles': ['admin', 'curator'],
    'site_id': 1,
    'icon_url': 'https://static.inaturalist.org/attachments/users/icons/1/medium.jpg?1475527316',
}

Return type

Dict[str, Any]

Returns

Response dict containing user record

Parameters

user_id (int) –
user_agent (Optional[str]) –

pyinaturalist.node_api.get_users_autocomplete(q, **params)[source]¶

Given a query string, return users with names or logins starting with the search term

API reference: https://api.inaturalist.org/v1/docs/#!/Users/get_users_autocomplete

Note: Pagination is supported; default page size is 6, and max is 100.

Example

>>> response = get_taxa_autocomplete(q='my_userna')
>>> print(format_users(response))
[1234] my_username
[12345] my_username_2

Example Response

from datetime import datetime
from dateutil.tz import tzutc

{
    'total_results': 3,
    'page': 1,
    'per_page': 3,
    'results': [
        {
            'id': 886482,
            'login': 'niconoe',
            'spam': False,
            'suspended': False,
            'created_at': datetime(2018, 4, 23, 17, 11, 14, tzinfo=tzutc()),
            'login_autocomplete': 'niconoe',
            'login_exact': 'niconoe',
            'name': 'Nicolas Noé',
            'name_autocomplete': 'Nicolas Noé',
            'orcid': 'https://orcid.org/0000-0002-9503-4750',
            'icon': 'https://static.inaturalist.org/attachments/users/icons/886482/thumb.jpg?1529671435',
            'observations_count': 928,
            'identifications_count': 118,
            'journal_posts_count': 0,
            'activity_count': 1046,
            'species_count': 396,
            'universal_search_rank': 928,
            'roles': [],
            'site_id': 1,
            'icon_url': 'https://static.inaturalist.org/attachments/users/icons/886482/medium.jpg?1529671435',
        },
        {
            'id': 2909130,
            'login': 'niconoerbo',
            'spam': False,
            'suspended': False,
            'created_at': datetime(2020, 5, 5, 6, 28, 32, tzinfo=tzutc()),
            'login_autocomplete': 'niconoerbo',
            'login_exact': 'niconoerbo',
            'name': None,
            'name_autocomplete': None,
            'orcid': None,
            'icon': None,
            'observations_count': 6,
            'identifications_count': 0,
            'journal_posts_count': 0,
            'activity_count': 6,
            'universal_search_rank': 6,
            'roles': [],
            'site_id': 1,
            'icon_url': None,
        },
        {
            'id': 3358478,
            'login': 'nicono',
            'spam': False,
            'suspended': False,
            'created_at': datetime(2020, 7, 20, 18, 7, 44, tzinfo=tzutc()),
            'login_autocomplete': 'nicono',
            'login_exact': 'nicono',
            'name': None,
            'name_autocomplete': None,
            'orcid': None,
            'icon': None,
            'observations_count': 0,
            'identifications_count': 0,
            'journal_posts_count': 0,
            'activity_count': 0,
            'universal_search_rank': 0,
            'roles': [],
            'site_id': 1,
            'icon_url': None,
        },
    ],
}

Parameters

q (str) – Search query
project_id – Only show users who are members of this project
page (int) – Page number of results to return
per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (str) – Sort order
order_by (str) – Field to sort on
count_only (bool) – Only return a count of results; alias for per_page=0
user_agent (str) – A custom user-agent string to provide to the iNaturalist API
observation_id (int) –

Return type

Dict[str, Any]

Returns

Response dict containing user records

pyinaturalist.node_api.search(q, **params)[source]¶

A unified search endpoint for places, projects, taxa, and/or users

API reference: https://api.inaturalist.org/v1/docs/#!/Search/get_search

Example

>>> response = search(q='odonat')
>>> print(format_search_results(response, align=True))
[Taxon  ] [47792   ] Order: Odonata (Dragonflies and Damselflies)
[Place  ] [113562  ] Odonates of Peninsular India and Sri Lanka
[Project] [9978    ] Ohio Dragonfly Survey  (Ohio Odonata Survey)
[User   ] [113886  ] odonatanb (Gilles Belliveau)

Example Response

import datetime
from dateutil.tz import tzutc

{
    'total_results': 4,
    'page': 1,
    'per_page': 4,
    'results': [
        {
            'score': 9.062307,
            'type': 'Taxon',
            'matches': ['Odonata', 'Odonati', 'Odonates', 'odonates', 'Odonats'],
            'record': {
                'id': 47792,
                'rank': 'order',
                'rank_level': 40,
                'iconic_taxon_id': 47158,
                'ancestor_ids': [48460, 1, 47120, 372739, 47158, 184884, 47792],
                'is_active': True,
                'min_species_taxon_id': 47792,
                'name': 'Odonata',
                'parent_id': 184884,
                'ancestry': '48460/1/47120/372739/47158/184884',
                'min_species_ancestry': '48460,1,47120,372739,47158,184884,47792',
                'extinct': False,
                'created_at': datetime.datetime(2008, 6, 24, 23, 44, 58, tzinfo=tzutc()),
                'default_photo': {
                    'id': 362106,
                    'license_code': 'cc-by-nc-sa',
                    'attribution': '(c) Vijay Anand Ismavel, some rights reserved (CC BY-NC-SA), uploaded by Dr. Vijay Anand Ismavel MS MCh',
                    'url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/362106/square.jpg?1444643485',
                    'original_dimensions': {'height': 1053, 'width': 1579},
                    'flags': [],
                    'square_url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/362106/square.jpg?1444643485',
                    'medium_url': 'https://inaturalist-open-data.s3.amazonaws.com/photos/362106/medium.jpg?1444643485',
                },
                'taxon_changes_count': 0,
                'taxon_schemes_count': 2,
                'observations_count': 1154269,
                'photos_locked': False,
                'universal_search_rank': 1154269,
                'flag_counts': {'resolved': 0, 'unresolved': 0},
                'current_synonymous_taxon_ids': None,
                'taxon_photos': ['TRUNCATED'],
                'atlas_id': None,
                'complete_species_count': 6300,
                'wikipedia_url': 'http://en.wikipedia.org/wiki/Odonata',
                'complete_rank': 'species',
                'matched_term': 'Odonata',
                'iconic_taxon_name': 'Insecta',
                'preferred_common_name': 'Dragonflies and Damselflies',
            },
        },
        {
            'score': 7.116488,
            'type': 'Place',
            'matches': ['Odonates of Peninsular India and Sri Lanka'],
            'record': {
                'id': 113562,
                'uuid': '41b4c009-438e-47df-a0e2-54b3f05a932f',
                'slug': 'odonates-of-peninsular-india-and-sri-lanka',
                'name': 'Odonates of Peninsular India and Sri Lanka',
                'display_name': 'Odonates of Peninsular India and Sri Lanka',
                'display_name_autocomplete': 'Odonates of Peninsular India and Sri Lanka',
                'place_type': None,
                'admin_level': None,
                'bbox_area': 110.9856964778392,
                'ancestor_place_ids': [97395, 113562],
                'user': {
                    'id': 269948,
                    'login': 'hopeland',
                    'spam': False,
                    'suspended': False,
                    'created_at': '2016-07-09T07:28:15.128Z',
                },
                'geometry_geojson': {'type': 'Polygon', 'coordinates': ['TRUNCATED']},
                'bounding_box_geojson': {'type': 'Polygon', 'coordinates': ['TRUNCATED']},
                'location': [10.1616628185, 78.8619335657],
                'point_geojson': {'type': 'Point', 'coordinates': [78.8619335657, 10.1616628185]},
                'without_check_list': None,
                'observations_count': 130762,
                'universal_search_rank': 130762,
                'names': [],
                'matched_term': 'Odonates of Peninsular India and Sri Lanka',
            },
        },
        {
            'score': 6.9390197,
            'type': 'Project',
            'matches': ['Odonata'],
            'record': {
                'id': 9978,
                'title': 'Ohio Dragonfly Survey  (Ohio Odonata Survey)',
                'title_autocomplete': 'Ohio Dragonfly Survey  (Ohio Odonata Survey)',
                'title_exact': 'Ohio Dragonfly Survey  (Ohio Odonata Survey)',
                'hide_title': False,
                'description': 'This project is to update information on the distribution and abundance of Ohio dragonflies and damselflies. It is an update from the first Ohio Odonata Survey which ran from 1991 to 2000.\r\n\r\nThe first survey was entirely based up museum specimens, new collections of specimens, and published articles in peer reviewed journals. Photography has advanced greatly since then, and this site will utilize digital photos to add to scientifically collected specimens.',
                'slug': 'ohio-dragonfly-survey-ohio-odonata-survey',
                'project_type': 'assessment',
                'banner_color': None,
                'ancestor_place_ids': None,
                'place_ids': None,
                'place_id': 31,
                'user_id': 395663,
                'admins': [
                    {'id': 175160, 'user_id': 370069, 'project_id': 9978, 'role': 'manager'}
                ],
                'rule_place_ids': [31],
                'associated_place_ids': [97394, 1, 31],
                'user_ids': ['TRUNCATED'],
                'location': None,
                'geojson': None,
                'icon': 'https://static.inaturalist.org/projects/9978-icon-span2.jpg?1505527521',
                'icon_file_name': 'JewelAppalach9229.jpg',
                'header_image_url': 'https://static.inaturalist.org/projects/9978-cover.jpg?1521571861',
                'header_image_file_name': '12spot_projectCover.jpg',
                'header_image_contain': False,
                'project_observation_fields': [],
                'terms': '*  Entries must be photos of dragonflies or damselflies taken in Ohio\r\n*  Photos must be identifiable to species. Often 2 or 3 shots show key details such as in field guides extremely helpful.\r\n*  Entries must carry scientific level of data\r\n    -- name of photographer\r\n    -- date photo taken\r\n    -- location as precise as possible.  \r\nMust include:  \r\n    1. County (township if possible)\r\n    2. Site name or description to help pin locaton (can be simple\r\n        like "State Route 56 at Mad River" or "backyard in Athens, Ohio"  or "Big Walnut Creek at confluence with Alum Creek" or something else that will enable to site to located.\r\n   -- GPS coordinates\r\n*  Photos will be vetted and accepted/rejected from the project based upon a) complete data;  b)identifiable photo\r\n',
                'search_parameters': [
                    {'field': 'photos', 'value': True, 'value_bool': True},
                    {
                        'field': 'quality_grade',
                        'value': ['research', 'needs_id'],
                        'value_keyword': ['research', 'needs_id'],
                    },
                    {'field': 'taxon_id', 'value': [47792], 'value_number': [47792]},
                    {'field': 'place_id', 'value': [31], 'value_number': [31]},
                ],
                'search_parameter_fields': {
                    'photos': True,
                    'quality_grade': ['research', 'needs_id'],
                    'taxon_id': [47792],
                    'place_id': [31],
                },
                'subproject_ids': [],
                'project_observation_rules': [
                    {'id': 13151, 'operator': 'wild?', 'operand_type': None, 'operand_id': None},
                    {
                        'id': 14672,
                        'operator': 'georeferenced?',
                        'operand_type': None,
                        'operand_id': None,
                    },
                    {
                        'id': 14673,
                        'operator': 'has_a_photo?',
                        'operand_type': None,
                        'operand_id': None,
                    },
                    {
                        'id': 14674,
                        'operator': 'verifiable?',
                        'operand_type': None,
                        'operand_id': None,
                    },
                    {
                        'id': 14675,
                        'operator': 'in_taxon?',
                        'operand_type': 'Taxon',
                        'operand_id': 47792,
                    },
                    {
                        'id': 14676,
                        'operator': 'observed_in_place?',
                        'operand_type': 'Place',
                        'operand_id': 31,
                    },
                ],
                'rule_preferences': [{'field': 'quality_grade', 'value': 'research,needs_id'}],
                'created_at': datetime.datetime(2016, 11, 30, 19, 10, 5, tzinfo=tzutc()),
                'updated_at': datetime.datetime(2021, 4, 16, 15, 6, 43, tzinfo=tzutc()),
                'last_post_at': datetime.datetime(2021, 5, 3, 21, 23, 56, tzinfo=tzutc()),
                'observations_count': 86452,
                'universal_search_rank': 86898,
                'spam': False,
                'flags': [],
                'site_features': [],
                'umbrella_project_ids': [],
                'prefers_user_trust': False,
                'observation_requirements_updated_at': None,
                'matched_term': 'Ohio Dragonfly Survey  (Ohio Odonata Survey)',
                'is_umbrella': False,
            },
        },
        {
            'score': 4.6454225,
            'type': 'User',
            'matches': ['odonatanb'],
            'record': {
                'id': 113886,
                'login': 'odonatanb',
                'spam': False,
                'suspended': False,
                'created_at': datetime.datetime(2015, 7, 3, 23, 12, 14, tzinfo=tzutc()),
                'login_autocomplete': 'odonatanb',
                'login_exact': 'odonatanb',
                'name': 'Gilles Belliveau',
                'name_autocomplete': 'Gilles Belliveau',
                'orcid': None,
                'icon': 'https://static.inaturalist.org/attachments/users/icons/113886/thumb.jpeg?1475548692',
                'observations_count': 440,
                'identifications_count': 877,
                'journal_posts_count': 0,
                'activity_count': 1317,
                'species_count': 136,
                'universal_search_rank': 440,
                'roles': [],
                'site_id': 5,
                'matched_term': 'odonatanb',
                'icon_url': 'https://static.inaturalist.org/attachments/users/icons/113886/medium.jpeg?1475548692',
            },
        },
    ],
}

Parameters

q (str) – Search query
sources (Union[str, List[str]]) – Object types to search
place_id (Union[int, List[int]]) – Results must be associated with this place
locale (str) – Locale preference for taxon common names
preferred_place_id (int) – Place preference for regional taxon common names
page (int) – Page number of results to return
per_page (int) – Number of results to return in a page. The maximum value is generally 200, unless otherwise noted
order (str) – Sort order
order_by (str) – Field to sort on
count_only (bool) – Only return a count of results; alias for per_page=0
user_agent (str) – A custom user-agent string to provide to the iNaturalist API

Return type

Dict[str, Any]

Returns

Response dict containing search results