Back to top

BirdWeather

This is the documentation for V1 of the BirdWeather API.

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

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

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,speciesId,query,locale}

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&speciesId=305&query=magpie&locale=es
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).

speciesId
integer (optional) Example: 305

Limit results to the given species.

query
string (optional) Example: magpie

Limit results to species that match the given query (will be ignored if speciesId is provided).

locale
string (optional) Example: es

Language locale to use for search query.

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://media.birdweather.com/species/305/Chestnut-backedChickadee-standard-0ccc6a9522620eb8d8048026bf8d47a4.jpg",
      "thumbnailUrl": "https://media.birdweather.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://media.birdweather.com/species/161/Golden-crownedSparrow-standard-058175742a0428567bd8c79322b77884.jpg",
      "thumbnailUrl": "https://media.birdweather.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

Detections

These endpoints require authentication with a station auth token.

Post Detection
POST/api/v1/stations/detections

Registers a detection that has previously been analyzed by BirdNET or a compatible soundscape analyzer.

  • timestamp (string, required) - The timestamp of the start of the detection, in ISO8601 format.

  • commonName (string, required) - The species’ common name.

  • scientificName (string, required) - The species’ scientific name.

  • lat (float) - Latitude for the detection (will use the station’s latitude if not specified).

  • lon (float) - Longitude for the detection (will use the station’s longitude if not specified).

  • confidence (float) - Confidence as detected by BirdNET.

  • soundscapeId (integer) - ID of a previously uploaded soundscape.

  • soundscapeStartTime (float) - Start time (in seconds) of the detection within the soundscape audio file.

  • soundscapeEndTime (float) - End time (in seconds) of the detection within the soundscape audio file.

Example URI

POST /api/v1/stations/detections
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "timestamp": "2022-11-21T19:01:46.000-05:00",
  "commonName": "Turkey Vulture",
  "scientificName": "Cathartes aura",
  "lat": 39.3634,
  "lon": -84.2269,
  "confidence": 0.7595082,
  "soundscapeId": 25035244,
  "soundscapeStartTime": 26,
  "soundscapeEndTime": 29
}
Response  201
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://media.birdweather.com/species/3046/TurkeyVulture-standard-ed30d8dbd1a1da1205649e195bccc852.jpg",
      "thumbnail_url": "https://media.birdweather.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": {
      "id": 25035244,
      "url": "https://media.birdweather.com/soundscapes/52705eef883bf9f7e3f19bb36fbee9c2",
      "start_time": 26,
      "end_time": 29,
      "mode": "live"
    }
  }
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "success": false,
  "errors": {
    "timestamp": [
      "can't be blank"
    ],
    "species": [
      "must exist"
    ]
  }
}

List Detections
GET/api/v1/stations/{token}/detections{?limit,cursor,from,to,speciesId,query,locale}

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&speciesId=305&query=magpie&locale=es
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).

speciesId
integer (optional) Example: 305

List only detections for the given species.

query
string (optional) Example: magpie

Limit results to species that match the given query (will be ignored if speciesId is provided).

locale
string (optional) Example: es

Language locale to use for search query.

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://media.birdweather.com/species/3046/TurkeyVulture-standard-ed30d8dbd1a1da1205649e195bccc852.jpg",
      "thumbnail_url": "https://media.birdweather.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://media.birdweather.com/soundscapes/52705eef883bf9f7e3f19bb36fbee9c2",
      "start_time": 26,
      "end_time": 29,
      "mode": "live"
    }
  }
}

Soundscapes

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",
    "mode": "live",
    "url": "https://media.birdweather.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).

speciesId
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",
      "mode": "live",
      "url": "https://media.birdweather.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",
    "mode": "live",
    "url": "https://media.birdweather.com/soundscapes/4de6d017c348f716959751efdf9e897c"
  }
}

Species

Species

Lookup 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://media.birdweather.com/species/1/HouseSparrow-standard-b861184cf45c092cdb45fd689dd676ef.jpg",
    "thumbnailUrl": "https://media.birdweather.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

Lookup Multiple Species
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://media.birdweather.com/species/1/HouseSparrow-standard-b861184cf45c092cdb45fd689dd676ef.jpg",
      "thumbnailUrl": "https://media.birdweather.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 Configuration

Station Configuration

Update Station Config
POST/api/v1/stations/{token}/config

Updates the configuration for the given station.

  • name (string) - The new name for the station.

  • locationPrivacy (boolean) - Toggle location privacy.

  • minConfidence (float) - Set minimum confidence for a valid detection (0.35 … 1.0).

  • minProbability (float) - Set minimum probability for a valid detection (0.0 … 1.0).

  • minScore (float) - Set minimum score for a valid detection (0.0 … 10.0).

  • minHumanConfidence (float) - Set minimum confidence for flagging human detections (0.04 … 0.25) [default: 0.1]. A lower value is more sensitive and will result in more soundscapes being auto-purged.

Example URI

POST /api/v1/stations/token/config
URI Parameters
HideShow
token
string (required) 

Station authentication token

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "name": "New Station Name",
  "locationPrivacy": true,
  "minConfidence": 0.45,
  "minProbability": 0.2,
  "minScore": 4.8,
  "minHumanConfidence": 0.05
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "success": true,
    "station": {
        "id": 12345,
        "name": "BirdNET-Pi - New Station Name",
        "type": "birdnetpi",
        "timezone": null,
        "latestDetectionAt": null,
        "latestValidDetectionAt": null,
        "locationPrivacy": true,
        "minConfidence": 045,
        "minProbability": 0.2,
        "minScore": 4.8,
        "minHumanConfidence": 0.05
    }
}
Response  422
HideShow
Headers
Content-Type: application/json
Body
{
  "success": false
}

Generated by aglio on 06 Dec 2024