Database query API and database schema

[dacracot]

I want to write an alternative data display for the information gathered by BirdNET-Go. I would like to call an API with my queries and receive either json or xml as a response. Unfortunately I am ignorant of almost all things GO and am having a problem finding the exposed interface, what protocol it uses, and what data is available.

Any pushes in the correct direction would be much appreciated.

[birdnet-go-bot]

Automated message from birdnet-go support assistant.

BirdNET-Go exposes a RESTful API over HTTP that returns JSON data, so you don't need to know Go or query the database directly to build an alternative display.

The API is served on the same port as the web interface (default 8080), with endpoints under the /api/v2 prefix. For reading detection data and analytics, no authentication is required. Here are the main endpoints you'll want to use:

• GET /api/v2/detections - Returns a paginated list of bird detections.
• POST /api/v2/search - Allows you to search detections with specific filters (date ranges, species, confidence).
• GET /api/v2/analytics/species/summary - Returns aggregated statistics for species.
• GET /api/v2/detections/stream - A Server-Sent Events (SSE) endpoint that streams new detections in real-time as they occur.

The JSON data returned for a detection generally matches the database schema, including fields like id, date, time, scientificName, commonName, confidence, and verified status.

You can see the full list of API endpoints and their descriptions in the API v2 README in the source tree. A great way to see the exact JSON payloads is to open your browser's Developer Tools (Network tab) while using the built-in BirdNET-Go dashboard, as the frontend uses this exact same API to fetch everything.

I'm an automated assistant so take this as a starting point. If it doesn't help, reply here and the maintainer will take a look.

[dacracot]

Thanks for the summary AI overlords.

[dacracot]

Is there an end point of the API that takes queries in a format similar to SQL?

[birdnet-go-bot]

Automated message from birdnet-go support assistant.

No, the API doesn't support raw SQL or GraphQL queries. It uses standard REST conventions.

To query for specific data, use the POST /api/v2/search endpoint and pass your filters in the JSON request body (like species names, date ranges, or confidence thresholds). For aggregations, use the /api/v2/analytics/... endpoints rather than trying to group data yourself.

I'm an automated assistant so take this as a starting point. If it doesn't help, reply here and the maintainer will take a look.

[dacracot]

What would be an example of the JSON sent to the analytics endpoint, that would result totals for each species detected for the last hour, aggregated across tenths of the confidence range?

[birdnet-go-bot]

Automated message from birdnet-go support assistant.

The analytics endpoints (/api/v2/analytics/...) are all GET requests, meaning they don't accept a JSON body. Their parameters are passed in the URL query string instead.

For the exact data you're looking for, an hourly window aggregated into 10 confidence bins, the API doesn't have a single pre-aggregated endpoint. The API does have GET /api/v2/analytics/confidence/distribution which bins by tenths of the confidence range, but its date filters only support full calendar days (?start_date=YYYY-MM-DD), not hourly windows.

To get hourly granularity, you will need to do the aggregation client-side. Use POST /api/v2/search to fetch the raw detections for the current day, filter them down to the last hour in your own code, and then group the counts into your confidence buckets.

Here is the JSON you would POST to /api/v2/search to get the raw detections for today:

{
  "dateStart": "2026-07-18",
  "dateEnd": "2026-07-18"
}

I'm an automated assistant so take this as a starting point. If it doesn't help, reply here and the maintainer will take a look.