BirdWeather

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

Content-Type: application/json

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

Content-Type: application/json

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

Content-Type: application/json

{
  "success": false,
  "errors": {
    "timestamp": [
      "can't be blank"
    ],
    "species": [
      "must exist"
    ]
  }
}

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

Content-Type: application/json

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

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

Content-Type: application/json

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

Content-Type: application/json

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

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.01 … 0.25) [default: 0.04]. A lower value is more sensitive and will result in more soundscapes being auto-purged.

Example URI

Content-Type: application/json

{
  "name": "New Station Name",
  "locationPrivacy": true,
  "minConfidence": 0.45,
  "minProbability": 0.2,
  "minScore": 4.8,
  "minHumanConfidence": 0.05
}

Content-Type: application/json

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

Content-Type: application/json

{
  "success": false
}