Taxa

Summary

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, **params)

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_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[int]) – 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 (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 (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, **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 taxa with this ID. Multiple values are allowed.

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]