API (v1) documentation for Bird object • Iowa State University • Avian Archives of Iowa Online

Bird

The Birds API allows people to retrieve info about birds.

DESCRIPTION

Returns all birds, filtered by the 'scientificName' and 'vernacularName' GET filters.

PARAMETERS

Parameter	Type	Required	Description	Values	Default
scientificName	GET	Optional	The scientific name to filter birds by. This filter is ANDed with the 'vernacularName' filter (if applied).	Any text	NULL
vernacularName	GET	Optional	The vernacular name to filter birds by. This filter is ANDed with the 'scientificName' filter (if applied).	Any text	NULL

RESPONSE

Type: application/json

A JSON object that complies with the JSON API standard (www.jsonapi.org).

Status Code	Meaning
200	Successfully queried birds.
401	Invalid API key provided.
405	Invalid request HTTP method.

Example Success Response

{
    "links": {
        "self": "https://avian.lib.iastate.edu/api/v1/birds?scientificName=accipiter&vernacularName=Sharp-shinned"
    },
    "data": [
        {
            "id": 247,
            "type": "bird",
            "attributes": {
                "status": "Reviewed",
                "scientificNameId": 2480612,
                "scientificName": "Accipiter striatus",
                "vernacularName": "Sharp-shinned Hawk - DO NOT USE",
                "kingdom": "Animalia",
                "phylum": "Chordata",
                "class": "Aves",
                "taxonOrder": "Accipitriformes",
                "family": "Accipitridae",
                "genus": "Accipiter",
                "taxonRank": "Species",
                "adminNotes": ""
            }
        },
        {
            "id": 517,
            "type": "bird",
            "attributes": {
                "status": "Not Reviewed",
                "scientificNameId": 9600371,
                "scientificName": "Accipiter striatus",
                "vernacularName": "Sharp-shinned Hawk",
                "kingdom": "Animalia",
                "phylum": "Chordata",
                "class": "Aves",
                "taxonOrder": "Accipitriformes",
                "family": "Accipitridae",
                "genus": "Accipiter",
                "taxonRank": "",
                "adminNotes": "Sharp-shinned Hawk P-0003 Nora Springs, Floyd Co. 19 Apr 1980 Dorothy A. Brunner"
            }
        }
    ]
}

DESCRIPTION

Returns info about the Bird entity associated with the given ID.

PARAMETERS

Parameter	Type	Required	Description	Values	Default
bird-id	URL_SLUG	Required	The ID of the Bird entity to retrieve.	Any positive integer	NULL

RESPONSE

Type: application/json

A JSON object that complies with the JSON API standard (www.jsonapi.org).

Status Code	Meaning
200	Successfully queried specified bird.
401	Invalid API key provided.
404	No bird was found for the provided ID.
405	Invalid request HTTP method.

Example Success Response

{
    "links": {
        "self": "https://avian.lib.iastate.edu/api/v1/birds/8"
    },
    "data": {
        "id": "8",
        "type": "bird",
        "attributes": {
            "status": "Reviewed",
            "scientificNameId": 2476855,
            "scientificName": "Selasphorus rufus",
            "vernacularName": "Rufous Hummingbird",
            "kingdom": "Animalia",
            "phylum": "Chordata",
            "class": "Aves",
            "taxonOrder": "Apodiformes",
            "family": "Trochilidae",
            "genus": "",
            "taxonRank": "Genus",
            "adminNotes": ""
        },
        "relationships": {
            "documents": {
                "data": [
                    {
                        "id": 1196,
                        "type": "document"
                    },
                    {
                        "id": 1197,
                        "type": "document"
                    },
                    {
                        "id": 1199,
                        "type": "document"
                    }
                ]
            }
        }
    }
}