Taxa#

Summary#

Classes

Functions

get_life_list_metadata(user_id[, locale])

Get common names and default taxon photos for a user's life list

get_taxa(**params)

Search taxa

get_taxa_autocomplete(**params)

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

get_taxa_by_id(taxon_id[, locale, ...])

Get one or more taxa by ID

get_taxa_map_layers(taxon_id, **params)

Get some additional taxon metadata, including: * GBIF taxon ID and URL * Whether the taxon has range data and/or listed places

Module Contents#

pyinaturalist.v1.taxa.get_life_list_metadata(user_id, locale=None, **params)#

Get common names and default taxon photos for a user’s life list

Notes

  • Undocumented in API reference

  • On iNaturalist.org, this is used for dynamic life lists

Parameters:

  • user_id (Union[int, str]) – iNaturalist user ID or username

  • locale (Optional[str]) – Locale preference for taxon common names

Example

>>> response = get_life_list_metadata(user_id='my_username')
Example Response
{
  "total_results": 10,
  "results": [
    {
      "name": "Life",
      "id": 48460,
      "default_photo": {
        "medium_url": "https://inaturalist-open-data.s3.amazonaws.com/photos/196425367/medium.jpeg"
      }
    },
    {
      "name": "Animalia",
      "id": 1,
      "default_photo": {
        "medium_url": "https://inaturalist-open-data.s3.amazonaws.com/photos/80678745/medium.jpg"
      },
      "preferred_common_name": "Animals"
    },
    {
      "name": "Chordata",
      "id": 2,
      "default_photo": {
        "medium_url": "https://inaturalist-open-data.s3.amazonaws.com/photos/80551845/medium.jpg"
      },
      "preferred_common_name": "Chordates"
    },
    {
      "name": "Aves",
      "id": 3,
      "default_photo": {
        "medium_url": "https://inaturalist-open-data.s3.amazonaws.com/photos/2967053/medium.jpg"
      },
      "preferred_common_name": "Birds"
    },
    {
      "name": "Galliformes",
      "id": 573,
      "default_photo": {
        "medium_url": "https://static.inaturalist.org/photos/101730709/medium.jpeg"
      },
      "preferred_common_name": "Landfowl"
    },
    {
      "name": "Phasianidae",
      "id": 574,
      "default_photo": {
        "medium_url": "https://inaturalist-open-data.s3.amazonaws.com/photos/53053041/medium.jpg"
      },
      "preferred_common_name": "Pheasants, Grouse, and Allies"
    },
    {
      "name": "Bonasa",
      "id": 889,
      "default_photo": {
        "medium_url": "https://inaturalist-open-data.s3.amazonaws.com/photos/2871/medium.jpg"
      }
    },
    {
      "name": "Bonasa umbellus",
      "id": 890,
      "default_photo": {
        "medium_url": "https://inaturalist-open-data.s3.amazonaws.com/photos/171717411/medium.jpeg"
      },
      "preferred_common_name": "Ruffed Grouse"
    },
    {
      "name": "Phasianus",
      "id": 980,
      "default_photo": {
        "medium_url": "https://inaturalist-open-data.s3.amazonaws.com/photos/4735/medium.jpg"
      }
    },
    {
      "name": "Phasianus colchicus",
      "id": 981,
      "default_photo": {
        "medium_url": "https://inaturalist-open-data.s3.amazonaws.com/photos/176733796/medium.jpg"
      },
      "preferred_common_name": "Ring-necked Pheasant"
    }
  ]
}
Return type:

Dict[str, Any]

Returns:

Response dict containing taxon common names and photo URLs

pyinaturalist.v1.taxa.get_taxa(**params)#

Search taxa

Notes

Parameters:

  • q (Optional[str]) – Name must begin with this value

  • is_active (Optional[bool]) – Taxon is active

  • taxon_id (Optional[int]) – Only show taxa with this ID, or its descendants

  • rank (Optional[str]) – Taxon must have this exact rank

  • min_rank (Optional[str]) – Taxon must have this rank or higher; overrides rank

  • max_rank (Optional[str]) – Taxon must have this rank or lower; overrides rank

  • rank_level (Optional[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 (Optional[str]) – Locale preference for taxon common names

  • preferred_place_id (Optional[int]) – Place preference for regional taxon common names

  • all_names (Optional[bool]) – Include all taxon names in the response

  • id_above (Optional[int]) – Must have an ID above this value

  • id_below (Optional[int]) – Must have an ID below this value

  • only_id (Optional[bool]) – Return only the record IDs

  • parent_id (Optional[int]) – Taxon’s parent must have this ID

  • page (Optional[int]) – Page number of results to return

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

  • order (Optional[str]) – Sort order

  • order_by (Optional[str]) – Field to sort on

  • count_only (Optional[bool]) – Only return a count of results; alias for per_page=0

  • reverse (Optional[bool]) – Reverse the order of results; alias for order='descending'

  • dry_run (Optional[bool]) – Just log the request instead of sending a real request

  • session (Optional[Session]) – An existing Session object to use instead of creating a new one

Example

>>> response = get_taxa(q='vespi', rank=['genus', 'family'])
>>> pprint(response)
[52747] Family: Vespidae (Hornets, Paper Wasps, Potter Wasps, and Allies)
[92786] Genus: Vespicula
[646195] Genus: Vespiodes
...
Example Response
{
  "total_results": 30,
  "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    },
    {
      "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",
      "vision": true
    }
  ]
}
Return type:

Dict[str, Any]

Returns:

Response dict containing taxon records

pyinaturalist.v1.taxa.get_taxa_autocomplete(**params)#

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

Notes

  • API reference: GET /taxa/autocomplete

  • There appears to currently be a bug in the API that causes per_page to not have any effect.

Parameters:

  • q (Optional[str]) – Name must begin with this value

  • is_active (Optional[bool]) – Taxon is active

  • taxon_id (Optional[int]) – Only show taxa with this ID, or its descendants

  • rank (Optional[str]) – Taxon must have this exact rank

  • min_rank (Optional[str]) – Taxon must have this rank or higher; overrides rank

  • max_rank (Optional[str]) – Taxon must have this rank or lower; overrides rank

  • rank_level (Optional[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 (Optional[str]) – Locale preference for taxon common names

  • preferred_place_id (Optional[int]) – Place preference for regional taxon common names

  • all_names (Optional[bool]) – Include all taxon names in the response

  • dry_run (Optional[bool]) – Just log the request instead of sending a real request

  • session (Optional[Session]) –

    An existing Session object to use instead of creating a new one

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:

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

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

>>> first_result = get_taxa_autocomplete(q='zygoca')['results'][0]
>>> first_result["name"]
"Schlumbergera truncata"  # This doesn't look like our search term!
>>> first_result["matched_term"]
"Zygocactus truncatus"    # ...Because it matched an older synonym for Schlumbergera
Example Response
{
    'total_results': 3,
    'page': 1,
    'per_page': 10,
    'results': [
        {
            'observations_count': 235680,
            'taxon_schemes_count': 2,
            'ancestry': '48460/1/47120/372739/47158/184884/47201/124417/326777/48740',
            'is_active': True,
            'flag_counts': {'unresolved': 0, 'resolved': 1},
            'wikipedia_url': 'http://en.wikipedia.org/wiki/Vespidae',
            'current_synonymous_taxon_ids': None,
            'iconic_taxon_id': 47158,
            'rank_level': 30,
            'taxon_changes_count': 0,
            'atlas_id': None,
            'complete_species_count': None,
            'parent_id': 48740,
            'name': 'Vespidae',
            'rank': 'family',
            'extinct': False,
            'id': 52747,
            'default_photo': {
                'square_url': 'https://static.inaturalist.org/photos/13765/square.jpg?1545358964',
                'attribution': '(c) Cécile Bassaglia, some rights reserved (CC BY-NC-SA)',
                'flags': [],
                'medium_url': 'https://static.inaturalist.org/photos/13765/medium.jpg?1545358964',
                'id': 13765,
                'license_code': 'cc-by-nc-sa',
                'original_dimensions': {'width': 1024, 'height': 679},
                'url': 'https://static.inaturalist.org/photos/13765/square.jpg?1545358964',
            },
            'ancestor_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47201,
                124417,
                326777,
                48740,
                52747,
            ],
            'matched_term': 'Vespidae',
            'iconic_taxon_name': 'Insecta',
            'preferred_common_name': 'Hornets, Paper Wasps, Potter Wasps, and Allies',
        },
        {
            'observations_count': 74782,
            'taxon_schemes_count': 1,
            'ancestry': '48460/1/47120/372739/47158/184884/47201/124417/326777/48740/52747',
            'is_active': True,
            'flag_counts': {'unresolved': 1, 'resolved': 0},
            'wikipedia_url': 'http://en.wikipedia.org/wiki/Vespinae',
            'current_synonymous_taxon_ids': None,
            'iconic_taxon_id': 47158,
            'rank_level': 27,
            'taxon_changes_count': 0,
            'atlas_id': None,
            'complete_species_count': None,
            'parent_id': 52747,
            'name': 'Vespinae',
            'rank': 'subfamily',
            'extinct': False,
            'id': 84738,
            'default_photo': {
                'square_url': 'https://static.inaturalist.org/photos/11374710/square.jpg?1508777024',
                'attribution': '(c) Arnold Wijker, some rights reserved (CC BY-NC)',
                'flags': [],
                'medium_url': 'https://static.inaturalist.org/photos/11374710/medium.jpg?1508777024',
                'id': 11374710,
                'license_code': 'cc-by-nc',
                'original_dimensions': {'width': 800, 'height': 639},
                'url': 'https://static.inaturalist.org/photos/11374710/square.jpg?1508777024',
            },
            'ancestor_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47201,
                124417,
                326777,
                48740,
                52747,
                84738,
            ],
            'matched_term': 'Vespinae',
            'iconic_taxon_name': 'Insecta',
            'preferred_common_name': 'Hornets and Yellowjackets',
        },
        {
            'observations_count': 610,
            'taxon_schemes_count': 1,
            'ancestry': '48460/1/47120/372739/47158/184884/47208/71130/372870/48311/53849/204079/53850',
            'is_active': True,
            'flag_counts': {'unresolved': 0, 'resolved': 0},
            'wikipedia_url': 'http://en.wikipedia.org/wiki/Nicrophorus_vespillo',
            'current_synonymous_taxon_ids': None,
            'iconic_taxon_id': 47158,
            'rank_level': 10,
            'taxon_changes_count': 0,
            'atlas_id': None,
            'complete_species_count': None,
            'parent_id': 53850,
            'name': 'Nicrophorus vespillo',
            'rank': 'species',
            'extinct': False,
            'id': 131878,
            'default_photo': {
                'square_url': 'https://static.inaturalist.org/photos/24573164/square.jpg?1536478624',
                'attribution': '(c) Nikolai Vladimirov, some rights reserved (CC BY-NC)',
                'flags': [],
                'medium_url': 'https://static.inaturalist.org/photos/24573164/medium.jpg?1536478624',
                'id': 24573164,
                'license_code': 'cc-by-nc',
                'original_dimensions': {'width': 2048, 'height': 1365},
                'url': 'https://static.inaturalist.org/photos/24573164/square.jpg?1536478624',
            },
            'ancestor_ids': [
                48460,
                1,
                47120,
                372739,
                47158,
                184884,
                47208,
                71130,
                372870,
                48311,
                53849,
                204079,
                53850,
                131878,
            ],
            'matched_term': 'Nicrophorus vespillo',
            'iconic_taxon_name': 'Insecta',
            'preferred_common_name': 'Vespillo Burying Beetle',
        },
    ],
}
Example Response (formatted)
[
    '   52747:       Family Vespidae (Hornets, Paper Wasps, Potter Wasps, and Allies)',
    '   84738:    Subfamily Vespinae (Hornets and Yellowjackets)',
    '  131878:      Species Nicrophorus vespillo (Vespillo Burying Beetle)',
    '  621585:      Species Vespicula trachinoides (Vespicula Waspfish)',
    '  495392:      Species Vespidae st1',
    '   70118:      Species Nicrophorus vespilloides (Lesser Vespillo Burying Beetle)',
    '   92786:        Genus Vespicula',
    '  646195:        Genus Vespiodes',
    '  621584:      Species Vespicula cypho',
    '  621586:      Species Vespicula zollingeri',
]
Return type:

Dict[str, Any]

Returns:

Response dict containing taxon records

pyinaturalist.v1.taxa.get_taxa_by_id(taxon_id, locale=None, preferred_place_id=None, all_names=None, **params)#

Get one or more taxa by ID

Notes

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, Iterable[int]]) – Get taxon with this ID. Multiple values are allowed.

  • locale (Optional[str]) – Locale preference for taxon common names

  • preferred_place_id (Optional[int]) – Place preference for regional taxon common names

  • all_names (Optional[bool]) – Include all taxon names in the response

Return type:

Dict[str, Any]

Returns:

Response dict containing taxon records

pyinaturalist.v1.taxa.get_taxa_map_layers(taxon_id, **params)#

Get some additional taxon metadata, including: * GBIF taxon ID and URL * Whether the taxon has range data and/or listed places

Example

>>> response = get_taxa_map_layers(343248)
Example Response
{
  "id": 47588,
  "ranges": false,
  "gbif_id": 2820380,
  "listed_places": true
}
Parameters:

taxon_id (int) – iNaturalist taxon ID. Only one value is allowed.

Return type:

Dict[str, Any]