Created
April 25, 2025 18:31
-
-
Save ATechAdventurer/4662addbd3f71ba5990befbc09f6fdc5 to your computer and use it in GitHub Desktop.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| { | |
| "openapi": "3.0.0", | |
| "info": { | |
| "title": "BirdWeather API", | |
| "version": "1.0.0", | |
| "description": "This is the OpenAPI specification for V1 of the BirdWeather API.", | |
| "contact": { | |
| "email": "support@birdweather.com" | |
| } | |
| }, | |
| "servers": [ | |
| { | |
| "url": "https://app.birdweather.com/api/v1" | |
| } | |
| ], | |
| "paths": { | |
| "/stations/{token}/stats": { | |
| "get": { | |
| "operationId": "getStationStats", | |
| "summary": "Fetch Stats", | |
| "description": "Retrieve statistics for a specific station.", | |
| "parameters": [ | |
| { "$ref": "#/components/parameters/TokenParam" }, | |
| { "$ref": "#/components/parameters/PeriodParam" }, | |
| { "$ref": "#/components/parameters/SinceParam" } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "A JSON object containing detection statistics.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "detections": { | |
| "type": "integer" | |
| }, | |
| "species": { | |
| "type": "integer" | |
| } | |
| } | |
| }, | |
| "example": { | |
| "success": true, | |
| "detections": 12345, | |
| "species": 99 | |
| } | |
| } | |
| } | |
| }, | |
| "403": { | |
| "$ref": "#/components/responses/Forbidden" | |
| } | |
| } | |
| } | |
| }, | |
| "/stations/{token}/species": { | |
| "get": { | |
| "operationId": "listStationSpecies", | |
| "summary": "Top Species", | |
| "description": "Returns a list of species detected by the station, along with their detection counts.", | |
| "parameters": [ | |
| { "$ref": "#/components/parameters/TokenParam" }, | |
| { "$ref": "#/components/parameters/PeriodParam" }, | |
| { "$ref": "#/components/parameters/SinceParam" }, | |
| { "$ref": "#/components/parameters/LimitParam" }, | |
| { "$ref": "#/components/parameters/PageParam" }, | |
| { "$ref": "#/components/parameters/SortParam" }, | |
| { "$ref": "#/components/parameters/OrderParam" }, | |
| { "$ref": "#/components/parameters/SpeciesIdQueryParam" }, | |
| { "$ref": "#/components/parameters/QueryParam" }, | |
| { "$ref": "#/components/parameters/LocaleParam" } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "A JSON object containing a list of species detected by the station.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "species": { | |
| "type": "array", | |
| "items": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer" | |
| }, | |
| "commonName": { | |
| "type": "string" | |
| }, | |
| "scientificName": { | |
| "type": "string" | |
| }, | |
| "color": { | |
| "type": "string" | |
| }, | |
| "imageUrl": { | |
| "type": "string", | |
| "format": "uri" | |
| }, | |
| "thumbnailUrl": { | |
| "type": "string", | |
| "format": "uri" | |
| }, | |
| "detections": { | |
| "type": "object", | |
| "properties": { | |
| "total": { | |
| "type": "integer" | |
| }, | |
| "almostCertain": { | |
| "type": "integer" | |
| }, | |
| "veryLikely": { | |
| "type": "integer" | |
| }, | |
| "uncertain": { | |
| "type": "integer" | |
| }, | |
| "unlikely": { | |
| "type": "integer" | |
| } | |
| } | |
| }, | |
| "latestDetectionAt": { | |
| "type": "string", | |
| "format": "date-time" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "required": [ | |
| "success", | |
| "species" | |
| ] | |
| }, | |
| "example": { | |
| "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:10.986-08:00" | |
| } | |
| ] | |
| } | |
| } | |
| } | |
| }, | |
| "403": { | |
| "$ref": "#/components/responses/Forbidden" | |
| } | |
| } | |
| } | |
| }, | |
| "/stations/{token}/detections": { | |
| "get": { | |
| "operationId": "listStationDetections", | |
| "summary": "List Detections", | |
| "description": "Lists all detections associated with this station in timestamp descending order.", | |
| "parameters": [ | |
| { "$ref": "#/components/parameters/TokenParam" }, | |
| { "$ref": "#/components/parameters/LimitParam" }, | |
| { "$ref": "#/components/parameters/CursorParam" }, | |
| { "$ref": "#/components/parameters/FromParam" }, | |
| { "$ref": "#/components/parameters/ToParam" }, | |
| { "$ref": "#/components/parameters/OrderParam" }, | |
| { "$ref": "#/components/parameters/SpeciesIdQueryParam" }, | |
| { "$ref": "#/components/parameters/QueryParam" }, | |
| { "$ref": "#/components/parameters/LocaleParam" } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "A list of detections for the station.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "detections": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/components/schemas/Detection" | |
| } | |
| } | |
| }, | |
| "required": [ | |
| "success", | |
| "detections" | |
| ] | |
| } | |
| } | |
| } | |
| }, | |
| "403": { | |
| "$ref": "#/components/responses/Forbidden" | |
| } | |
| } | |
| } | |
| }, | |
| "/stations/detections": { | |
| "post": { | |
| "operationId": "registerDetection", | |
| "summary": "Register Detection", | |
| "description": "Registers a detection that has previously been analyzed by BirdNET or a compatible soundscape analyzer.", | |
| "requestBody": { | |
| "required": true, | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "timestamp": { | |
| "type": "string", | |
| "format": "date-time", | |
| "description": "The timestamp of the start of the detection, in ISO8601 format." | |
| }, | |
| "commonName": { | |
| "type": "string", | |
| "description": "The species' common name." | |
| }, | |
| "scientificName": { | |
| "type": "string", | |
| "description": "The species' scientific name." | |
| }, | |
| "lat": { | |
| "type": "number", | |
| "format": "float", | |
| "description": "Latitude for the detection (will use the station's latitude if not specified)." | |
| }, | |
| "lon": { | |
| "type": "number", | |
| "format": "float", | |
| "description": "Longitude for the detection (will use the station's longitude if not specified)." | |
| }, | |
| "confidence": { | |
| "type": "number", | |
| "format": "float", | |
| "description": "Confidence as detected by BirdNET." | |
| }, | |
| "soundscapeId": { | |
| "type": "integer", | |
| "description": "ID of a previously uploaded soundscape." | |
| }, | |
| "soundscapeStartTime": { | |
| "type": "number", | |
| "format": "float", | |
| "description": "Start time (in seconds) of the detection within the soundscape audio file." | |
| }, | |
| "soundscapeEndTime": { | |
| "type": "number", | |
| "format": "float", | |
| "description": "End time (in seconds) of the detection within the soundscape audio file." | |
| } | |
| }, | |
| "required": [ | |
| "timestamp", | |
| "commonName", | |
| "scientificName" | |
| ], | |
| "example": { | |
| "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 | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "responses": { | |
| "201": { | |
| "description": "Detection successfully registered.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "detection": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer" | |
| }, | |
| "station_id": { | |
| "type": "integer" | |
| }, | |
| "timestamp": { | |
| "type": "string", | |
| "format": "date-time" | |
| }, | |
| "species": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer" | |
| }, | |
| "common_name": { | |
| "type": "string" | |
| }, | |
| "scientific_name": { | |
| "type": "string" | |
| }, | |
| "color": { | |
| "type": "string" | |
| }, | |
| "image_url": { | |
| "type": "string", | |
| "format": "uri" | |
| }, | |
| "thumbnail_url": { | |
| "type": "string", | |
| "format": "uri" | |
| } | |
| } | |
| }, | |
| "lat": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "lon": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "confidence": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "probability": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "score": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "certainty": { | |
| "type": "string" | |
| }, | |
| "algorithm": { | |
| "type": "string" | |
| }, | |
| "metadata": { | |
| "type": "object", | |
| "nullable": true | |
| }, | |
| "soundscape": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer" | |
| }, | |
| "url": { | |
| "type": "string", | |
| "format": "uri" | |
| }, | |
| "start_time": { | |
| "type": "integer" | |
| }, | |
| "end_time": { | |
| "type": "integer" | |
| }, | |
| "mode": { | |
| "type": "string" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "required": ["success", "detection"] | |
| }, | |
| "example": { | |
| "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" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "422": { | |
| "description": "Unprocessable Entity. Indicates validation errors.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "errors": { | |
| "type": "object", | |
| "additionalProperties": { | |
| "type": "array", | |
| "items": { | |
| "type": "string" | |
| } | |
| } | |
| } | |
| }, | |
| "required": ["success", "errors"] | |
| }, | |
| "example": { | |
| "success": false, | |
| "errors": { | |
| "timestamp": [ | |
| "can't be blank" | |
| ], | |
| "species": [ | |
| "must exist" | |
| ] | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "403": { | |
| "$ref": "#/components/responses/Forbidden" | |
| } | |
| } | |
| } | |
| }, | |
| "/stations/{token}/detections/{id}": { | |
| "get": { | |
| "operationId": "getStationDetectionById", | |
| "summary": "Get Detection by ID", | |
| "description": "Retrieves information for the detection with the given ID.", | |
| "parameters": [ | |
| { "$ref": "#/components/parameters/TokenParam" }, | |
| { "$ref": "#/components/parameters/DetectionIdParam" } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Detailed information about the detection.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "detection": { | |
| "$ref": "#/components/schemas/Detection" | |
| } | |
| }, | |
| "required": [ | |
| "success", | |
| "detection" | |
| ] | |
| } | |
| } | |
| } | |
| }, | |
| "403": { | |
| "$ref": "#/components/responses/Forbidden" | |
| }, | |
| "404": { | |
| "description": "Detection not found.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ErrorResponse" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/stations/{token}/soundscapes": { | |
| "post": { | |
| "operationId": "uploadSoundscape", | |
| "summary": "Upload Soundscape", | |
| "description": "Uploads an audio file which can then be associated with a posted detection.", | |
| "parameters": [ | |
| { "$ref": "#/components/parameters/TokenParam" }, | |
| { "$ref": "#/components/parameters/TimestampQueryParam" } | |
| ], | |
| "requestBody": { | |
| "description": "Audio file to upload.", | |
| "required": true, | |
| "content": { | |
| "audio/*": { | |
| "schema": { | |
| "type": "string", | |
| "format": "binary" | |
| } | |
| } | |
| } | |
| }, | |
| "responses": { | |
| "201": { | |
| "description": "Soundscape successfully uploaded.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "soundscape": { | |
| "$ref": "#/components/schemas/Soundscape" | |
| } | |
| }, | |
| "required": ["success", "soundscape"] | |
| } | |
| } | |
| } | |
| }, | |
| "400": { | |
| "description": "Bad request (e.g., missing timestamp or invalid audio data).", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ErrorResponse" | |
| } | |
| } | |
| } | |
| }, | |
| "403": { | |
| "$ref": "#/components/responses/Forbidden" | |
| } | |
| } | |
| }, | |
| "get": { | |
| "operationId": "listStationSoundscapes", | |
| "summary": "List Soundscapes", | |
| "description": "Lists all soundscapes associated with this station in timestamp descending order.", | |
| "parameters": [ | |
| { "$ref": "#/components/parameters/TokenParam" }, | |
| { "$ref": "#/components/parameters/LimitParam" }, | |
| { "$ref": "#/components/parameters/CursorParam" }, | |
| { "$ref": "#/components/parameters/FromParam" }, | |
| { "$ref": "#/components/parameters/ToParam" }, | |
| { "$ref": "#/components/parameters/SpeciesIdQueryParam" }, | |
| { "$ref": "#/components/parameters/DetectionsParam" } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "A list of soundscapes for the station.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "soundscapes": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/components/schemas/Soundscape" | |
| } | |
| } | |
| }, | |
| "required": ["success", "soundscapes"] | |
| } | |
| } | |
| } | |
| }, | |
| "403": { | |
| "$ref": "#/components/responses/Forbidden" | |
| } | |
| } | |
| } | |
| }, | |
| "/stations/{token}/soundscapes/{id}": { | |
| "get": { | |
| "operationId": "getStationSoundscapeById", | |
| "summary": "Get Soundscape Info", | |
| "description": "Retrieves information for the soundscape with the given ID.", | |
| "parameters": [ | |
| { "$ref": "#/components/parameters/TokenParam" }, | |
| { "$ref": "#/components/parameters/SoundscapeIdParam" }, | |
| { "$ref": "#/components/parameters/DetectionsParam" } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Detailed information about the soundscape.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "soundscape": { | |
| "$ref": "#/components/schemas/Soundscape" | |
| } | |
| }, | |
| "required": ["success", "soundscape"] | |
| } | |
| } | |
| } | |
| }, | |
| "403": { | |
| "$ref": "#/components/responses/Forbidden" | |
| }, | |
| "404": { | |
| "$ref": "#/components/responses/NotFound" | |
| } | |
| } | |
| } | |
| }, | |
| "/species/{id}": { | |
| "get": { | |
| "operationId": "getSpeciesById", | |
| "summary": "Lookup Species Info", | |
| "description": "Retrieves detailed information for a single species by its ID.", | |
| "parameters": [ | |
| { "$ref": "#/components/parameters/SpeciesIdPathParam" } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Detailed information about the species.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "species": { | |
| "$ref": "#/components/schemas/Species" | |
| } | |
| }, | |
| "required": ["success", "species"] | |
| } | |
| } | |
| } | |
| }, | |
| "404": { | |
| "$ref": "#/components/responses/NotFound" | |
| } | |
| } | |
| } | |
| }, | |
| "/species/lookup": { | |
| "post": { | |
| "operationId": "lookupSpecies", | |
| "summary": "Lookup Multiple Species", | |
| "description": "Retrieves detailed information for multiple species based on identifiers.", | |
| "requestBody": { | |
| "required": true, | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "species": { | |
| "type": "array", | |
| "items": { | |
| "type": "string", | |
| "description": "BirdNET identifier (Scientific Name_Common Name)" | |
| }, | |
| "description": "Array of BirdNET identifiers to look up." | |
| }, | |
| "fields": { | |
| "type": "array", | |
| "items": { | |
| "type": "string", | |
| "description": "Field name from the Species schema" | |
| }, | |
| "description": "Optional array of species fields to include. Leave blank to include all.", | |
| "nullable": true | |
| } | |
| }, | |
| "required": ["species"], | |
| "example": { | |
| "species": [ | |
| "Passer domesticus_House Sparrow" | |
| ] | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "responses": { | |
| "200": { | |
| "description": "Detailed information for the requested species.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "species": { | |
| "type": "object", | |
| "additionalProperties": { | |
| "$ref": "#/components/schemas/Species" | |
| }, | |
| "description": "Object mapping requested identifiers to species details." | |
| } | |
| }, | |
| "required": ["success", "species"] | |
| } | |
| } | |
| } | |
| }, | |
| "400": { | |
| "description": "Bad request (e.g., invalid input format).", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ErrorResponse" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/stations/{token}/config": { | |
| "post": { | |
| "operationId": "updateStationConfig", | |
| "summary": "Update Station Config", | |
| "description": "Updates the configuration for the given station.", | |
| "parameters": [ | |
| { "$ref": "#/components/parameters/TokenParam" } | |
| ], | |
| "requestBody": { | |
| "description": "Station configuration fields to update.", | |
| "required": true, | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/StationConfig" | |
| } | |
| } | |
| } | |
| }, | |
| "responses": { | |
| "200": { | |
| "description": "Station configuration updated successfully.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "station": { | |
| "$ref": "#/components/schemas/Station" | |
| } | |
| }, | |
| "required": ["success", "station"] | |
| } | |
| } | |
| } | |
| }, | |
| "403": { | |
| "$ref": "#/components/responses/Forbidden" | |
| }, | |
| "422": { | |
| "description": "Unprocessable Entity (e.g., validation errors on config fields).", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ErrorResponse" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "apiKeyAuth": [] | |
| } | |
| ], | |
| "components": { | |
| "schemas": { | |
| "token": { | |
| "type": "string", | |
| "description": "Station authentication token.", | |
| "example": "1234567890" | |
| }, | |
| "detectionId": { | |
| "type": "integer", | |
| "description": "Detection ID.", | |
| "example": 57299468 | |
| }, | |
| "cursor": { | |
| "type": "integer", | |
| "description": "The ID of the last item to begin pagination from.", | |
| "example": 12345 | |
| }, | |
| "from": { | |
| "type": "string", | |
| "format": "date", | |
| "description": "The timestamp in ISO8601 format to filter detections from (inclusive).", | |
| "example": "2023-06-18", | |
| "pattern": "^\\d{4}-\\d{2}-\\d{2}$" | |
| }, | |
| "to": { | |
| "type": "string", | |
| "format": "date", | |
| "description": "The timestamp in ISO8601 format to filter detections to (inclusive).", | |
| "example": "2023-07-05", | |
| "pattern": "^\\d{4}-\\d{2}-\\d{2}$" | |
| }, | |
| "period": { | |
| "description": "The time period to filter detections.", | |
| "type": "string", | |
| "enum": [ | |
| "day", | |
| "week", | |
| "month", | |
| "all" | |
| ], | |
| "default": "day" | |
| }, | |
| "since": { | |
| "type": "string", | |
| "format": "date", | |
| "example": "2023-10-01", | |
| "pattern": "^\\d{4}-\\d{2}-\\d{2}$", | |
| "description": "Timestamp to filter detections from, in ISO8601 format. Overrides period if passed." | |
| }, | |
| "limit": { | |
| "type": "integer", | |
| "description": "The maximum number of species to return.", | |
| "default": 100, | |
| "maximum": 100, | |
| "example": 10 | |
| }, | |
| "page": { | |
| "type": "integer", | |
| "description": "The page number of species to return.", | |
| "default": 1, | |
| "example": 2 | |
| }, | |
| "sort": { | |
| "type": "string", | |
| "enum": [ | |
| "common_name", | |
| "scientific_name", | |
| "top" | |
| ], | |
| "default": "top", | |
| "example": "common_name" | |
| }, | |
| "order": { | |
| "type": "string", | |
| "enum": [ | |
| "asc", | |
| "desc" | |
| ], | |
| "description": "Sort order. Default is asc when sorting by name, otherwise desc.", | |
| "default": "asc", | |
| "example": "desc" | |
| }, | |
| "speciesId": { | |
| "type": "integer", | |
| "description": "Limit results to the given species.", | |
| "example": 305 | |
| }, | |
| "query": { | |
| "type": "string", | |
| "description": "Limit results to species that match the given query (ignored if speciesId is provided).", | |
| "example": "magpie" | |
| }, | |
| "locale": { | |
| "type": "string", | |
| "description": "Language locale to use for search query.", | |
| "example": "es" | |
| }, | |
| "success": { | |
| "type": "boolean", | |
| "example": true | |
| }, | |
| "message": { | |
| "type": "string" | |
| }, | |
| "Detection": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer" | |
| }, | |
| "station_id": { | |
| "type": "integer" | |
| }, | |
| "timestamp": { | |
| "type": "string", | |
| "format": "date-time" | |
| }, | |
| "species": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer" | |
| }, | |
| "common_name": { | |
| "type": "string" | |
| }, | |
| "scientific_name": { | |
| "type": "string" | |
| }, | |
| "color": { | |
| "type": "string" | |
| }, | |
| "image_url": { | |
| "type": "string", | |
| "format": "uri" | |
| }, | |
| "thumbnail_url": { | |
| "type": "string", | |
| "format": "uri" | |
| } | |
| } | |
| }, | |
| "lat": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "lon": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "confidence": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "probability": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "score": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "certainty": { | |
| "type": "string" | |
| }, | |
| "algorithm": { | |
| "type": "string" | |
| }, | |
| "metadata": { | |
| "type": "object", | |
| "nullable": true | |
| }, | |
| "soundscape": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer" | |
| }, | |
| "url": { | |
| "type": "string", | |
| "format": "uri" | |
| }, | |
| "start_time": { | |
| "type": "integer" | |
| }, | |
| "end_time": { | |
| "type": "integer" | |
| }, | |
| "mode": { | |
| "type": "string" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "ErrorResponse": { | |
| "type": "object", | |
| "properties": { | |
| "success": { | |
| "$ref": "#/components/schemas/success" | |
| }, | |
| "message": { | |
| "$ref": "#/components/schemas/message" | |
| } | |
| }, | |
| "example": { | |
| "success": false, | |
| "message": "Access denied" | |
| } | |
| }, | |
| "soundscapeId": { | |
| "type": "integer", | |
| "description": "Soundscape ID.", | |
| "example": 12345 | |
| }, | |
| "timestamp": { | |
| "type": "string", | |
| "format": "date-time", | |
| "description": "Timestamp in ISO8601 format.", | |
| "example": "2022-04-27T23:41:37.212-07:00" | |
| }, | |
| "detectionsParam": { | |
| "type": "boolean", | |
| "description": "Flag to include detections in the response.", | |
| "default": false, | |
| "example": true | |
| }, | |
| "Soundscape": { | |
| "type": "object", | |
| "properties": { | |
| "id": { | |
| "type": "integer" | |
| }, | |
| "stationId": { | |
| "type": "integer" | |
| }, | |
| "duration": { | |
| "type": "number", | |
| "format": "float" | |
| }, | |
| "filesize": { | |
| "type": "integer" | |
| }, | |
| "timestamp": { | |
| "type": "string", | |
| "format": "date-time" | |
| }, | |
| "mode": { | |
| "type": "string" | |
| }, | |
| "url": { | |
| "type": "string", | |
| "format": "uri" | |
| }, | |
| "detections": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/components/schemas/Detection" | |
| }, | |
| "nullable": true | |
| } | |
| }, | |
| "example": { | |
| "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": { | |
| "type": "object", | |
| "properties": { | |
| "id": { "type": "integer" }, | |
| "commonName": { "type": "string" }, | |
| "scientificName": { "type": "string" }, | |
| "color": { "type": "string" }, | |
| "imageUrl": { "type": "string", "format": "uri" }, | |
| "thumbnailUrl": { "type": "string", "format": "uri" }, | |
| "wikipediaUrl": { "type": "string", "format": "uri", "nullable": true }, | |
| "wikipediaSummary": { "type": "string", "nullable": true }, | |
| "alpha": { "type": "string", "nullable": true }, | |
| "alpha6": { "type": "string", "nullable": true }, | |
| "ebirdCode": { "type": "string", "nullable": true }, | |
| "ebirdUrl": { "type": "string", "format": "uri", "nullable": true }, | |
| "imageCredit": { "type": "string", "nullable": true }, | |
| "imageCreditHtml": { "type": "string", "nullable": true }, | |
| "imageLicense": { "type": "string", "nullable": true }, | |
| "imageLicenseUrl": { "type": "string", "format": "uri", "nullable": true } | |
| }, | |
| "example": { | |
| "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...", | |
| "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" | |
| } | |
| }, | |
| "StationConfig": { | |
| "type": "object", | |
| "properties": { | |
| "name": { | |
| "type": "string", | |
| "description": "The new name for the station." | |
| }, | |
| "locationPrivacy": { | |
| "type": "boolean", | |
| "description": "Toggle location privacy." | |
| }, | |
| "minConfidence": { | |
| "type": "number", | |
| "format": "float", | |
| "description": "Minimum confidence for a valid detection (0.35 to 1.0).", | |
| "minimum": 0.35, | |
| "maximum": 1.0 | |
| }, | |
| "minProbability": { | |
| "type": "number", | |
| "format": "float", | |
| "description": "Minimum probability for a valid detection (0.0 to 1.0).", | |
| "minimum": 0.0, | |
| "maximum": 1.0 | |
| }, | |
| "minScore": { | |
| "type": "number", | |
| "format": "float", | |
| "description": "Minimum score for a valid detection (0.0 to 10.0).", | |
| "minimum": 0.0, | |
| "maximum": 10.0 | |
| }, | |
| "minHumanConfidence": { | |
| "type": "number", | |
| "format": "float", | |
| "description": "Minimum confidence for flagging human detections (0.01 to 0.25).", | |
| "minimum": 0.01, | |
| "maximum": 0.25, | |
| "default": 0.04 | |
| } | |
| }, | |
| "example": { | |
| "name": "New Station Name", | |
| "locationPrivacy": true, | |
| "minConfidence": 0.45, | |
| "minProbability": 0.2, | |
| "minScore": 4.8, | |
| "minHumanConfidence": 0.05 | |
| } | |
| }, | |
| "Station": { | |
| "type": "object", | |
| "properties": { | |
| "id": { "type": "integer" }, | |
| "name": { "type": "string" }, | |
| "type": { "type": "string" }, | |
| "timezone": { "type": "string", "nullable": true }, | |
| "latestDetectionAt": { "type": "string", "format": "date-time", "nullable": true }, | |
| "latestValidDetectionAt": { "type": "string", "format": "date-time", "nullable": true }, | |
| "locationPrivacy": { "type": "boolean" }, | |
| "minConfidence": { "type": "number", "format": "float" }, | |
| "minProbability": { "type": "number", "format": "float" }, | |
| "minScore": { "type": "number", "format": "float" }, | |
| "minHumanConfidence": { "type": "number", "format": "float" } | |
| }, | |
| "example": { | |
| "id": 12345, | |
| "name": "BirdNET-Pi - New Station Name", | |
| "type": "birdnetpi", | |
| "timezone": null, | |
| "latestDetectionAt": null, | |
| "latestValidDetectionAt": null, | |
| "locationPrivacy": true, | |
| "minConfidence": 0.45, | |
| "minProbability": 0.2, | |
| "minScore": 4.8, | |
| "minHumanConfidence": 0.05 | |
| } | |
| } | |
| }, | |
| "parameters": { | |
| "TokenParam": { | |
| "name": "token", | |
| "in": "path", | |
| "required": true, | |
| "schema": { "$ref": "#/components/schemas/token" }, | |
| "description": "Station authentication token." | |
| }, | |
| "DetectionIdParam": { | |
| "name": "id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { "$ref": "#/components/schemas/detectionId" }, | |
| "description": "Detection ID." | |
| }, | |
| "SoundscapeIdParam": { | |
| "name": "id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { "$ref": "#/components/schemas/soundscapeId" }, | |
| "description": "Soundscape ID." | |
| }, | |
| "SpeciesIdPathParam": { | |
| "name": "id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { "$ref": "#/components/schemas/speciesId" }, | |
| "description": "Species ID." | |
| }, | |
| "SpeciesIdQueryParam": { | |
| "name": "speciesId", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/speciesId" }, | |
| "description": "Limit results to the given species." | |
| }, | |
| "PeriodParam": { | |
| "name": "period", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/period" }, | |
| "description": "The time period to filter results." | |
| }, | |
| "SinceParam": { | |
| "name": "since", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/since" }, | |
| "description": "Timestamp to filter results from, in ISO8601 format. Overrides period if passed." | |
| }, | |
| "LimitParam": { | |
| "name": "limit", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/limit" }, | |
| "description": "The maximum number of items to return (max 100, default: 100)." | |
| }, | |
| "PageParam": { | |
| "name": "page", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/page" }, | |
| "description": "The page number of items to return." | |
| }, | |
| "SortParam": { | |
| "name": "sort", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/sort" }, | |
| "description": "Field to sort by." | |
| }, | |
| "OrderParam": { | |
| "name": "order", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/order" }, | |
| "description": "Sort order (asc/desc)." | |
| }, | |
| "QueryParam": { | |
| "name": "query", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/query" }, | |
| "description": "Limit results to items that match the given query." | |
| }, | |
| "LocaleParam": { | |
| "name": "locale", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/locale" }, | |
| "description": "Language locale to use for search query." | |
| }, | |
| "CursorParam": { | |
| "name": "cursor", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/cursor" }, | |
| "description": "The ID of the last item to begin pagination from." | |
| }, | |
| "FromParam": { | |
| "name": "from", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/from" }, | |
| "description": "The timestamp in ISO8601 format to filter results from (inclusive)." | |
| }, | |
| "ToParam": { | |
| "name": "to", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/to" }, | |
| "description": "The timestamp in ISO8601 format to filter results to (inclusive)." | |
| }, | |
| "TimestampQueryParam": { | |
| "name": "timestamp", | |
| "in": "query", | |
| "required": true, | |
| "schema": { "$ref": "#/components/schemas/timestamp" }, | |
| "description": "The timestamp of the start of the soundscape, in ISO8601 format." | |
| }, | |
| "DetectionsParam": { | |
| "name": "detections", | |
| "in": "query", | |
| "required": false, | |
| "schema": { "$ref": "#/components/schemas/detectionsParam" }, | |
| "description": "Optionally include detections in the response." | |
| } | |
| }, | |
| "responses": { | |
| "Forbidden": { | |
| "description": "Access denied due to invalid credentials.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ErrorResponse" | |
| } | |
| } | |
| } | |
| }, | |
| "NotFound": { | |
| "description": "The requested resource was not found.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ErrorResponse" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "securitySchemes": { | |
| "apiKeyAuth": { | |
| "type": "apiKey", | |
| "in": "header", | |
| "name": "Authorization" | |
| } | |
| } | |
| } | |
| } |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment