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.

Authentication ¶

Users are authenticated via an email and password. The response contains an authToken that can be passed in subsequent requests.

Note that the response also contains a list of stations, each with their own authToken. These are not the same, although the user authToken can be used in place of the station authToken when submitting to the user’s default user station.

Log in
POST`/api/v1/authenticate`

email (string) - The user’s email address
password (string) - The user’s password

Example URI

POST /api/v1/authenticate

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "email": "test@user.com",
  "password": "password"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "user": {
    "email": "test@example.com",
    "firstName": "Test",
    "lastName": "User",
    "displayName": "Example",
    "authToken": "CETV8pWmLJ72S1uvpuJvmDi6",
    "stations": [
      {
        "name": "Example",
        "type": "user",
        "authToken": "jDFKKCQ4kysBQA2mvBe1eDgz",
        "latestDetectionAt": null
      }
    ]
  }
}

Response 401

HideShow

Headers

Content-Type: application/json

Body

{
  "success": false,
  "message": "Invalid credentials"
}

User Creation ¶

Create User
POST`/api/v1/user`

Registers a new user account. A confirmation email will be sent to the email address provided.

email (string) - The user’s email address
password (string) - The user’s password
firstName (string, optional) - The user’s first name
lastName (string, optional) - The user’s last name
displayName (string) - Publicly visible name for the user
authToken (string, optional) - Auth token of a guest station to upgrade to a full account

Example URI

POST /api/v1/user

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "email": "test@user.com",
  "password": "password",
  "firstName": "Test",
  "lastName": "User",
  "displayName": "Example"
}

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "user": {
    "email": "test@example.com",
    "firstName": "Test",
    "lastName": "User",
    "displayName": "Example",
    "authToken": "CETV8pWmLJ72S1uvpuJvmDi6",
    "stations": [
      {
        "name": "Example",
        "type": "user",
        "authToken": "jDFKKCQ4kysBQA2mvBe1eDgz",
        "latestDetectionAt": null
      }
    ]
  }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "success": false,
  "errors": {
    "email": [
      "can't be blank"
    ]
  }
}

Guest Station Creation ¶

Create Guest Station
POST`/api/v1/guest`

Registers a guest station that can receive anonymous detections. A guest station can be later upgraded to a full account via the ‘Create User’ endpoint above.

Example URI

POST /api/v1/guest

Request

HideShow

Headers

Content-Type: application/json

Body

No body required

Response 201

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "station": {
    "name": "Guest",
    "type": "guest",
    "authToken": "jDFKKCQ4kysBQA2mvBe1eDgz",
    "latestDetectionAt": null
  }
}

User Info ¶

This endpoint requires authentication with a user auth token.

Get User Info
GET`/api/v1/user`

Example URI

GET /api/v1/user

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "user": {
    "email": "test@example.com",
    "firstName": "Test",
    "lastName": "User",
    "displayName": "Example",
    "authToken": "CETV8pWmLJ72S1uvpuJvmDi6",
    "stations": [
      {
        "name": "Example",
        "type": "user",
        "authToken": "jDFKKCQ4kysBQA2mvBe1eDgz",
        "latestDetectionAt": null
      }
    ]
  }
}

Update User
PATCH`/api/v1/user`

Example URI

PATCH /api/v1/user

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "password": "newpassword",
  "firstName": "Changed",
  "lastName": "Name"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "user": {
    "email": "test@example.com",
    "firstName": "Changed",
    "lastName": "Name",
    "displayName": "Example",
    "authToken": "CETV8pWmLJ72S1uvpuJvmDi6",
    "stations": [
      {
        "name": "Example",
        "type": "user",
        "authToken": "jDFKKCQ4kysBQA2mvBe1eDgz",
        "latestDetectionAt": null
      }
    ]
  }
}

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "success": false,
  "errors": {
    "email": [
      "can't be blank"
    ]
  }
}

Delete User
DELETE`/api/v1/user`

Example URI

DELETE /api/v1/user

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true
}

Station Stats ¶

These endpoints require authentication with a station auth token.

Fetch Stats
GET`/api/v1/stations/:token/stats`

period (string, optional) - The time period to filter detections [day / week / month / all] (default: day).

Example URI

GET /api/v1/stations/:token/stats

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`

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.

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

Example URI

GET /api/v1/stations/:token/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`

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.

limit (integer, optional) - The maximum number of detections to return (max 100, default: 100).
cursor (integer, optional) - The ID of the last detection to begin pagination from.
from (string, optional) - The timestamp in ISO8601 format to filter detections from (inclusive).
to (string, optional) - The timestamp in ISO8601 format to filter detections to (inclusive).
order (string, optional) - Order to sort timestamps by (default: desc).
species_id (integer, optional) - List only detections for the given species.

Example URI

GET /api/v1/stations/:token/detections

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/: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`

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.

timestamp (string) - The timestamp of the start of the soundscape, in ISO8601 format

Example URI

POST /api/v1/stations/:token/soundscapes

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.

limit (integer, optional) - The maximum number of soundscapes to return (max 100, default: 100).
cursor (integer, optional) - The ID of the last soundscape to begin pagination from.
from (string, optional) - The timestamp in ISO8601 format to filter soundscapes from (inclusive).
to (string, optional) - The timestamp in ISO8601 format to filter soundscapes to (inclusive).
order (string, optional) - Order to sort timestamps by (default: desc).
species_id (integer, optional) - List only soundscapes with detections for the given species.
detections (boolean, optional) - Optionally include soundscape detections in JSON response (default: false).

Example URI

GET /api/v1/stations/:token/soundscapes

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"
    }
  ]
}

Purge Soundscapes
DELETE`/api/v1/stations/:token/soundscapes`

Purges (deletes audio and database rows) all soundscapes matching the given criteria. If no criteria is given, all soundscapes for the station will be deleted.

Use with caution!

from (string, optional) - The timestamp in ISO8601 format to filter soundscapes from (inclusive).
to (string, optional) - The timestamp in ISO8601 format to filter soundscapes to (inclusive).

Example URI

DELETE /api/v1/stations/:token/soundscapes

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "from": "2022-04-27T23:41:37.212-07:00",
  "to": "2022-09-08T22:30:23.061-07:00"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "count": 123
}

Soundscape ¶

These endpoints require authentication with a station auth token.

Soundscape Info
GET`/api/v1/stations/:token/soundscapes/:id`

Retrieves information for the soundscape with the given ID.

detections (boolean, optional) - Optionally include soundscape detections in JSON response (default: false).

Example URI

GET /api/v1/stations/:token/soundscapes/:id

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"
  }
}

Purge Soundscape
DELETE`/api/v1/stations/:token/soundscapes/:id`

Purges (deletes audio and database row) the soundscape with the given ID.

Example URI

DELETE /api/v1/stations/:token/soundscapes/:id

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true
}

Species ¶

Extended Species Info
GET`/api/v1/species/:id`

Example URI

GET /api/v1/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"
    }
  }
}

Configuration ¶

View Configuration Parameters
GET`/api/v1/configuration`

Example URI

GET /api/v1/configuration

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "success": true,
  "configuration": {
    "confidenceGte": 0.35,
    "rejectedSpeciesList": [
      "Human non-vocal_Human non-vocal",
      "Human vocal_Human vocal",
      "Human whistle_Human whistle",
      "Engine_Engine",
      "Gun_Gun"
    ],
    "scoreGte": 3.6,
    "thresholdAlmostCertain": 4,
    "thresholdUncertain": 2,
    "thresholdVeryLikely": 3
  }
}

Authentication ¶

Authentication ¶

Log inPOST/api/v1/authenticate

Example URI

Headers

Body

Headers

Body

Headers

Body

User Creation ¶

User Creation ¶

Create UserPOST/api/v1/user

Example URI

Headers

Body

Headers

Body

Headers

Body

Guest Station Creation ¶

Create Guest StationPOST/api/v1/guest

Example URI

Headers

Body

Headers

Body

User Info ¶

User Info ¶

Get User InfoGET/api/v1/user

Example URI

Headers

Body

Update UserPATCH/api/v1/user

Example URI

Headers

Body

Headers

Body

Headers

Body

Delete UserDELETE/api/v1/user

Example URI

Headers

Body

Station Stats ¶

Station Stats ¶

Fetch StatsGET/api/v1/stations/:token/stats

Example URI

Headers

Body

Station Species ¶

Station Species ¶

Top SpeciesGET/api/v1/stations/:token/species

Example URI

Headers

Body

Detections ¶

Detections ¶

List DetectionsGET/api/v1/stations/:token/detections

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

Example URI

Headers

Body

List SoundscapesGET/api/v1/stations/:token/soundscapes

Example URI

Headers

Body

Purge SoundscapesDELETE/api/v1/stations/:token/soundscapes

Example URI

Log in
POST`/api/v1/authenticate`

Create User
POST`/api/v1/user`

Create Guest Station
POST`/api/v1/guest`

Get User Info
GET`/api/v1/user`

Update User
PATCH`/api/v1/user`

Delete User
DELETE`/api/v1/user`

Fetch Stats
GET`/api/v1/stations/:token/stats`

Top Species
GET`/api/v1/stations/:token/species`

List Detections
GET`/api/v1/stations/:token/detections`

Detection Info
GET`/api/v1/stations/:token/detections/:id`

Upload Soundscape
POST`/api/v1/stations/:token/soundscapes`

List Soundscapes
GET`/api/v1/stations/:token/soundscapes`

Purge Soundscapes
DELETE`/api/v1/stations/:token/soundscapes`

Soundscape Info
GET`/api/v1/stations/:token/soundscapes/:id`

Purge Soundscape
DELETE`/api/v1/stations/:token/soundscapes/:id`

Extended Species Info
GET`/api/v1/species/:id`

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

View Configuration Parameters
GET`/api/v1/configuration`