BirdWeather

This is the documentation for V1 of the BirdWeather API.

Production: https://app.birdweather.com/api/v1

POST parameters can be passed either as a JSON object string (application/json) or as HTML encoded form parameters (application/x-www-form-urlencoded). The examples below will use JSON.

For authenticated requests, the authentication token can be passed either as a JSON or form parameter token, or alternatively using the Authorization or X-Auth-Token header.

Station Stats ¶

These endpoints require authentication with a station auth token.

Fetch Stats
GET`/api/v1/stations/{token}/stats{?period,since}`

Example URI

GET /api/v1/stations/token/stats?period=week&since=2023-06-18

URI Parameters

HideShow

token: string (required)
Station authentication token
period: string (optional) Example: week
The time period to filter detections [day / week / month / all] (default: day).
since: string (optional) Example: 2023-06-18
Timestamp to filter detections from, in ISO8601 format. Overrides period if passed.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "detections": 12345,
  "species": 99
}

Station Species ¶

These endpoints require authentication with a station auth token.

Top Species
GET`/api/v1/stations/{token}/species{?period,since,limit,page,sort,order,species_id}`

Returns a list of species detected by the station, along with their detection counts.

By default it will return the top species by detection count, but can be reordered by species common or scientific name.

Example URI

GET /api/v1/stations/token/species?period=week&since=2023-06-18&limit=10&page=2&sort=common_name&order=desc&species_id=305

URI Parameters

HideShow

token: string (required)
Station authentication token
period: string (optional) Example: week
The time period to filter detections [day / week / month / all] (default: day).
since: string (optional) Example: 2023-06-18
Timestamp to filter detections from, in ISO8601 format. Overrides period if passed.
limit: integer (optional) Example: 10
The maximum number of species to return (max 100, default: 100).
page: integer (optional) Example: 2
The page number of species to return (default: 1).
sort: string (optional) Example: common_name
Alternative field to sort by [common_name / scientific_name / top] (default: top).
order: string (optional) Example: desc
Sort order [asc / desc] (default: asc when sorting by name, otherwise desc).
species_id: integer (optional) Example: 305
Limit results to the given species.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "species": [
    {
      "id": 305,
      "commonName": "Chestnut-backed Chickadee",
      "scientificName": "Poecile rufescens",
      "color": "#f8319e",
      "imageUrl": "https://birdweather.s3.amazonaws.com/species/305/Chestnut-backedChickadee-standard-0ccc6a9522620eb8d8048026bf8d47a4.jpg",
      "thumbnailUrl": "https://birdweather.s3.amazonaws.com/species/305/Chestnut-backedChickadee-thumbnail-1e6f597546372f2097b4dde0383a95e8.jpg",
      "detections": {
        "total": 1112,
        "almostCertain": 1112,
        "veryLikely": 0,
        "uncertain": 0,
        "unlikely": 0
      },
      "latestDetectionAt": "2022-11-17T16:48:10.986-08:00"
    },
    {
      "id": 161,
      "commonName": "Golden-crowned Sparrow",
      "scientificName": "Zonotrichia atricapilla",
      "color": "#c3a1ff",
      "imageUrl": "https://birdweather.s3.amazonaws.com/species/161/Golden-crownedSparrow-standard-058175742a0428567bd8c79322b77884.jpg",
      "thumbnailUrl": "https://birdweather.s3.amazonaws.com/species/161/Golden-crownedSparrow-thumbnail-8c352cc46e8ef5bec26dd849297393d7.jpg",
      "detections": {
        "total": 366,
        "almostCertain": 366,
        "veryLikely": 0,
        "uncertain": 0,
        "unlikely": 0
      },
      "latestDetectionAt": "2022-11-17T16:48:43.833-08:00"
    }
  ]
}

Detections ¶

These endpoints require authentication with a station auth token.

List Detections
GET`/api/v1/stations/{token}/detections{?limit,cursor,from,to,order,species_id}`

Lists all detections associated with this station in timestamp descending order.

Parameters should be provided as query parameters. Pagination is cursor-based using limit/offset params.

Example URI

GET /api/v1/stations/token/detections?limit=10&cursor=12345&from=2023-06-18&to=2023-07-05&order=asc&species_id=305

URI Parameters

HideShow

token: string (required)
Station authentication token
limit: integer (optional) Example: 10
The maximum number of detections to return (max 100, default: 100).
cursor: integer (optional) Example: 12345
The ID of the last detection to begin pagination from.
from: string (optional) Example: 2023-06-18
The timestamp in ISO8601 format to filter detections from (inclusive).
to: string (optional) Example: 2023-07-05
The timestamp in ISO8601 format to filter detections to (inclusive).
order: string (optional) Example: asc
Order to sort timestamps by (default: desc).
species_id: integer (optional) Example: 305
List only detections for the given species.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "success": true,
    "detections": [
        {
            ...
        },
        {
            ...
        }
    ]
}

Detection ¶

These endpoints require authentication with a station auth token.

Detection Info
GET`/api/v1/stations/{token}/detections/{id}`

Retrieves information for the detection with the given ID.

Example URI

GET /api/v1/stations/token/detections/57299468

URI Parameters

HideShow

token: string (required)
Station authentication token
id: integer (required) Example: 57299468
Detection ID

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "detection": {
    "id": 57299468,
    "station_id": 349,
    "timestamp": "2022-11-21T19:01:46.000-05:00",
    "species": {
      "id": 3046,
      "common_name": "Turkey Vulture",
      "scientific_name": "Cathartes aura",
      "color": "#b0ae00",
      "image_url": "https://birdweather.s3.amazonaws.com/species/3046/TurkeyVulture-standard-ed30d8dbd1a1da1205649e195bccc852.jpg",
      "thumbnail_url": "https://birdweather.s3.amazonaws.com/species/3046/TurkeyVulture-thumbnail-3c361f123db0ef92f7b65270c79ceaaa.jpg"
    },
    "lat": 39.3634,
    "lon": -84.2269,
    "confidence": 0.7595082,
    "probability": 0.215,
    "score": 7.30435925453706,
    "certainty": "almost_certain",
    "algorithm": "alpha",
    "metadata": null,
    "soundscape": {
      "url": "https://birdweather.s3.amazonaws.com/soundscapes/52705eef883bf9f7e3f19bb36fbee9c2",
      "start_time": 26,
      "end_time": 29
    }
  }
}

Soundscapes ¶

These endpoints require authentication with a station auth token.

Upload Soundscape
POST`/api/v1/stations/{token}/soundscapes{?timestamp}`

Uploads an audio file which can then be associated with a posted detection.

The audio file should be submitted as the POST body with the timestamp specified as a query parameter in the URL in ISO8601 format.

Example URI

POST /api/v1/stations/token/soundscapes?timestamp=2022-04-27T23:41:37.212-07:00

URI Parameters

HideShow

token: string (required)
Station authentication token
timestamp: string (required) Example: 2022-04-27T23:41:37.212-07:00
The timestamp of the start of the soundscape, in ISO8601 format

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "soundscape": {
    "id": 12345,
    "stationId": 1,
    "duration": 3,
    "filesize": 85444,
    "timestamp": "2022-04-27T23:41:37.212-07:00",
    "url": "https://birdweather.s3.amazonaws.com/soundscapes/4de6d017c348f716959751efdf9e897c"
  }
}

List Soundscapes
GET`/api/v1/stations/{token}/soundscapes`

Lists all soundscapes associated with this station in timestamp descending order.

Parameters should be provided as query parameters. Pagination is cursor-based using limit/offset params.

Example URI

GET /api/v1/stations/token/soundscapes

URI Parameters

HideShow

token: string (required)
Station authentication token
limit: integer (optional) Example: 10
The maximum number of soundscapes to return (max 100, default: 100).
cursor: integer (optional) Example: 12345
The ID of the last soundscape to begin pagination from.
from: string (optional) Example: 2023-06-18
The timestamp in ISO8601 format to filter soundscapes from (inclusive).
to: string (optional) Example: 2023-07-05
The timestamp in ISO8601 format to filter soundscapes to (inclusive).
order: string (optional) Example: asc
Order to sort timestamps by (default: desc).
species_id: integer (optional) Example: 305
List only soundscapes with detections for the given species.
detections: boolean (optional) Example: true
Optionally include soundscape detections in JSON response (default: false).

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "soundscapes": [
    {
      "id": 12345,
      "stationId": 1,
      "duration": 3,
      "filesize": 85444,
      "timestamp": "2022-04-27T23:41:37.212-07:00",
      "url": "https://birdweather.s3.amazonaws.com/soundscapes/4de6d017c348f716959751efdf9e897c"
    }
  ]
}

Soundscape ¶

These endpoints require authentication with a station auth token.

Soundscape Info
GET`/api/v1/stations/{token}/soundscapes/{id}{?detections}`

Retrieves information for the soundscape with the given ID.

Example URI

GET /api/v1/stations/token/soundscapes/12345?detections=true

URI Parameters

HideShow

token: string (required)
Station authentication token
id: integer (required) Example: 12345
Soundscape ID.
detections: boolean (optional) Example: true
Optionally include soundscape detections in JSON response (default: false).

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "soundscape": {
    "id": 12345,
    "stationId": 1,
    "duration": 3,
    "filesize": 85444,
    "timestamp": "2022-04-27T23:41:37.212-07:00",
    "url": "https://birdweather.s3.amazonaws.com/soundscapes/4de6d017c348f716959751efdf9e897c"
  }
}

Species ¶

Extended Species Info
GET`/api/v1/species/{id}`

Example URI

GET /api/v1/species/1

URI Parameters

HideShow

id: integer (required) Example: 1
Species ID.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "species": {
    "id": 1,
    "commonName": "House Sparrow",
    "scientificName": "Passer domesticus",
    "color": "#d16ff8",
    "imageUrl": "https://birdweather.s3.amazonaws.com/species/1/HouseSparrow-standard-b861184cf45c092cdb45fd689dd676ef.jpg",
    "thumbnailUrl": "https://birdweather.s3.amazonaws.com/species/1/HouseSparrow-thumbnail-e9cbc91763a1579de8ef04880678b5e3.jpg",
    "wikipediaUrl": "https://en.wikipedia.org/wiki/House_sparrow",
    "wikipediaSummary": "The house sparrow (Passer domesticus) is a bird of the sparrow family Passeridae, found in most parts of the world. It is a small bird that has a typical length of 16 cm (6.3 in) and a mass of 24–39.5 g (0.85–1.39 oz). Females and young birds are coloured pale brown and grey, and males have brighter black, white, and brown markings. One of about 25 species in the genus Passer, the house sparrow is native to most of Europe, the Mediterranean Basin, and a large part of Asia. Its intentional or accidental introductions to many regions, including parts of Australasia, Africa, and the Americas, make it the most widely distributed wild bird.\nThe house sparrow is strongly associated with human habitation, and can live in urban or rural settings. Though found in widely varied habitats and climates, it typically avoids extensive woodlands, grasslands, and deserts away from human development. It feeds mostly on the seeds of grains and weeds, but it is an opportunistic eater and commonly eats insects and many other foods. Its predators include domestic cats, hawks, and many other predatory birds and mammals.\nBecause of its numbers, ubiquity, and association with human settlements, the house sparrow is culturally prominent. It is extensively, and usually unsuccessfully, persecuted as an agricultural pest. It has also often been kept as a pet, as well as being a food item and a symbol of lust, sexual potency, commonness, and vulgarity. Though it is widespread and abundant, its numbers have declined in some areas. The animal's conservation status is listed as least concern on the IUCN Red List.",
    "alpha": "HOSP",
    "alpha6": "PASDOM",
    "ebirdCode": "houspa",
    "ebirdUrl": "https://ebird.org/species/houspa",
    "imageCredit": "Adamo",
    "imageCreditHtml": "<a rel=\"nofollow\" class=\"external text\" href=\"http://www.piqs.de/user/Adamo/\">Adamo</a>",
    "imageLicense": "CC BY 2.0 de",
    "imageLicenseUrl": "https://creativecommons.org/licenses/by/2.0/de/deed.en"
  }
}

Lookup Multiple Species ¶

Extended Species Info
POST`/api/v1/species/lookup`

species (array) - Array of BirdNET identifiers (Scientific Name_Common Name) to look up.
fields (array) - Array of species fields to include. Leave blank to include all.

Example URI

POST /api/v1/species/lookup

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "species": [
    "Passer domesticus_House Sparrow"
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "species": {
    "Passer domesticus_House Sparrow": {
      "id": 1,
      "commonName": "House Sparrow",
      "scientificName": "Passer domesticus",
      "color": "#d16ff8",
      "imageUrl": "https://birdweather.s3.amazonaws.com/species/1/HouseSparrow-standard-b861184cf45c092cdb45fd689dd676ef.jpg",
      "thumbnailUrl": "https://birdweather.s3.amazonaws.com/species/1/HouseSparrow-thumbnail-e9cbc91763a1579de8ef04880678b5e3.jpg",
      "wikipediaUrl": "https://en.wikipedia.org/wiki/House_sparrow",
      "wikipediaSummary": "The house sparrow (Passer domesticus) is a bird of the sparrow family Passeridae, found in most parts of the world. It is a small bird that has a typical length of 16 cm (6.3 in) and a mass of 24–39.5 g (0.85–1.39 oz). Females and young birds are coloured pale brown and grey, and males have brighter black, white, and brown markings. One of about 25 species in the genus Passer, the house sparrow is native to most of Europe, the Mediterranean Basin, and a large part of Asia. Its intentional or accidental introductions to many regions, including parts of Australasia, Africa, and the Americas, make it the most widely distributed wild bird.\nThe house sparrow is strongly associated with human habitation, and can live in urban or rural settings. Though found in widely varied habitats and climates, it typically avoids extensive woodlands, grasslands, and deserts away from human development. It feeds mostly on the seeds of grains and weeds, but it is an opportunistic eater and commonly eats insects and many other foods. Its predators include domestic cats, hawks, and many other predatory birds and mammals.\nBecause of its numbers, ubiquity, and association with human settlements, the house sparrow is culturally prominent. It is extensively, and usually unsuccessfully, persecuted as an agricultural pest. It has also often been kept as a pet, as well as being a food item and a symbol of lust, sexual potency, commonness, and vulgarity. Though it is widespread and abundant, its numbers have declined in some areas. The animal's conservation status is listed as least concern on the IUCN Red List.",
      "alpha": "HOSP",
      "alpha6": "PASDOM",
      "ebirdCode": "houspa",
      "ebirdUrl": "https://ebird.org/species/houspa",
      "imageCredit": "Adamo",
      "imageCreditHtml": "<a rel=\"nofollow\" class=\"external text\" href=\"http://www.piqs.de/user/Adamo/\">Adamo</a>",
      "imageLicense": "CC BY 2.0 de",
      "imageLicenseUrl": "https://creativecommons.org/licenses/by/2.0/de/deed.en"
    }
  }
}

Station Stats ¶

Station Stats ¶

Fetch StatsGET/api/v1/stations/{token}/stats{?period,since}

Example URI

Headers

Body

Station Species ¶

Station Species ¶

Top SpeciesGET/api/v1/stations/{token}/species{?period,since,limit,page,sort,order,species_id}

Example URI

Headers

Body

Detections ¶

Detections ¶

List DetectionsGET/api/v1/stations/{token}/detections{?limit,cursor,from,to,order,species_id}

Example URI

Headers

Body

Detection ¶

Detection InfoGET/api/v1/stations/{token}/detections/{id}

Example URI

Headers

Body

Soundscapes ¶

Soundscapes ¶

Upload SoundscapePOST/api/v1/stations/{token}/soundscapes{?timestamp}

Example URI

Headers

Body

List SoundscapesGET/api/v1/stations/{token}/soundscapes

Example URI

Headers

Body

Soundscape ¶

Soundscape InfoGET/api/v1/stations/{token}/soundscapes/{id}{?detections}

Example URI

Headers

Body

Species ¶

Species ¶

Extended Species InfoGET/api/v1/species/{id}

Example URI

Headers

Body

Lookup Multiple Species ¶

Extended Species InfoPOST/api/v1/species/lookup

Example URI

Headers

Body

Headers

Body

Fetch Stats
GET`/api/v1/stations/{token}/stats{?period,since}`

Top Species
GET`/api/v1/stations/{token}/species{?period,since,limit,page,sort,order,species_id}`

List Detections
GET`/api/v1/stations/{token}/detections{?limit,cursor,from,to,order,species_id}`

Detection Info
GET`/api/v1/stations/{token}/detections/{id}`

Upload Soundscape
POST`/api/v1/stations/{token}/soundscapes{?timestamp}`

List Soundscapes
GET`/api/v1/stations/{token}/soundscapes`

Soundscape Info
GET`/api/v1/stations/{token}/soundscapes/{id}{?detections}`

Extended Species Info
GET`/api/v1/species/{id}`

Extended Species Info
POST`/api/v1/species/lookup`