pyinaturalist.node_api module

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

Most recent API version tested: 1.3.0

Functions

get_all_observations

[Deprecated] Like get_observations(), but gets all pages of results

get_controlled_terms

List controlled terms and their possible values.

get_geojson_observations

Get all observation results combined into a GeoJSON FeatureCollection.

get_identifications

Search identifications.

get_identifications_by_id

Get one or more identification records by ID.

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_observation_identifiers

Get identifiers of observations matching the search criteria and the count of observations they have identified.

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_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_observations

Search observations.

get_places_autocomplete

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

get_places_by_id

Get one or more places by ID.

get_places_nearby

Given an bounding box, and an optional name query, return standard iNaturalist curator approved and community non-curated places nearby

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_autocomplete

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

get_taxa_by_id

Get one or more taxa by ID.

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

node_api_get

Make an API call to iNaturalist.

pyinaturalist.node_api.get_all_observations(**params)[source]

[Deprecated] Like get_observations(), but gets all pages of results

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

  • 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

List[Dict[str, Any]]

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()
>>> # Show a condensed list of terms and values
>>> for term in response['results']:
>>>     values = [f'    {value["id"]}: {value["label"]}' for value in term['values']]
>>>     print(f'{term["id"]}: {term["label"]}' + '\n'.join(values))
1: Life Stage
    2: Adult
    3: Teneral
    4: Pupa
    5: Nymph
    6: Larva
    7: Egg
    8: Juvenile
    16: Subimago
9: Sex
    10: Female
    11: Male
    20: Cannot Be Determined
12: Plant Phenology
    13: Flowering
    14: Fruiting
    15: Flower Budding
    21: No Evidence of Flowering
17: Alive or Dead
    18: Alive
    19: Dead
    20: Cannot Be Determined

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']])
my_username: 60132 (supporting)
my_username: 47126 (improving)

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

>>> get_observation(16227955)

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)

{
    1: 272,
    2: 253,
    3: 992,
    4: 3925,
    5: 7983,
    6: 7079,
    7: 9150,
    8: 8895,
    9: 8374,
    10: 6060,
    11: 920,
    12: 382,
}

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

>>> get_observation_identifiers(place_id=72645)

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

GET /observations/observers API node is buggy. It’s currently limited to 500 results and using order_by=species_count may produce unusual 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

>>> get_observation_observers(place_id=72645, order_by='species_count')

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

>>> get_observation_species_counts(user_login='my_username', quality_grade='research')

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.response_utils import format_observation_str
>>> for obs in response['results']:
>>>     print(format_observation_str(obs))
'[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({p['id']: p['name'] for p in  response['results']})
{
    11803:  'Irkutsk',
    41853:  'Irkutsk',
    41854:  'Irkutskiy rayon',
    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({p['id']: p['name'] for p in  response['results']})
{
    67591: 'Riversdale Beach',
    89191: 'Conservation Area Riversdale',
}

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 standard iNaturalist curator approved and community non-curated 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)

Show basic info for standard (curated) places in response:

>>> print({p['id']: p['name'] for p in  response['results']['standard']})
{
    97394: 'North America',
    97395: 'Asia',
    97393: 'Oceania',
    97392: 'Africa',
    97391: 'Europe',
    97389: 'South America',
    7161:  'Russia',
    1:     'United States',
    6712:  'Canada',
    10316: 'United States Minor Outlying Islands',
}

Show basic info for community-contributed places in response:

>>> print({p['id']: p['name'] for p in  response['results']['community']})
{
    11770:  'Mehedinti',
    119755: 'Mahurangi College',
    150981: 'Ceap Breatainn',
    136758: 'Willapa Hills (US EPA Level IV Ecoregion)',
    119694: 'Tetlin National Wildlife Refuge',
    70630:  'Murray - Sunset',
    141915: 'Fundy Pollinator Trail',
    72346:  'Sucunduri',
    50505:  'Great Salt Lake',
    72230:  'Rio Novo',
 }

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({p['id']: p['title'] for p in response['results']})
{
    8291:  'PNW Invasive Plant EDDR',
    19200: 'King County (WA) Noxious and Invasive Weeds',
    8527:  'WA Invasives',
    2344:  'Invasive & Huntable Animals',
    6432:  'CBWN 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

>>> get_projects_by_id([8348, 6432])

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({taxon['id']: taxon['name'] for taxon in response['results']})
{52747: 'Vespidae', 84737: 'Vespina', 92786: 'Vespicula', 646195: '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:

>>> from pyinaturalist.response_utils import format_taxon_str
>>> for taxon in response['results']:
>>>     print(format_taxon_str(taxon, align=True))
>>> # See example output below

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)

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

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.node_api_get(endpoint, **kwargs)[source]

Make an API call to iNaturalist.

Parameters
  • endpoint (str) – The name of an endpoint resource, not including the base URL e.g. ‘observations’

  • kwargs – Arguments for api_requests.request()

Return type

Response