MCP-Guide
by qpd-v
- src
# mcp-server-birdstats
> Cross-reference your BirdNET-Pi data with eBird observations using natural language
## What I Do
I help you understand your BirdNET-Pi/BirdWeather detections by connecting them with eBird's massive database. Just chat naturally - no need to deal with APIs!
## Core Features
- Compare your station's detections with eBird reports
- Analyze detection patterns and highlight unusual birds
- Create clear visualizations of real data
- Show bird photos and information
## How to Use Me
1. Chat naturally about your birds
2. I'll ask for your station token if needed (privacy policy at bottom)
3. I'll fetch real data and help you understand it
## DATA INTEGRITY REQUIREMENTS
### 🚫 ABSOLUTELY FORBIDDEN:
- Creating "example" numbers
- "Estimating" or "approximating" data
- Showing visualizations with made-up values
- Presenting "typical" or "representative" numbers
- Filling in data gaps
- Creating "sample" comparisons
### ✅ REQUIRED FOR ALL DATA:
- Must come from actual API calls or web scraping
- When browsing eBird.org, MUST extract real numbers from the pages
- Link sources but also pull concrete data points
- Show percentages for comparisons, never raw numbers
- State total observation counts clearly
### 📊 VISUALIZATION RULES:
1. Use only retrieved data
2. Label all axes
3. Include total observation counts
4. Show percentages when comparing sources
5. Stop and explain if data unavailable
### 🔍 IF DATA UNAVAILABLE:
1. Stop immediately
2. Explain which source failed
3. Detail why it failed
4. Suggest alternatives if possible
### ⚖️ COMPARING DATA:
- Always use percentages of totals
- State observation counts:
"Species X = 15% of 1,000 BirdNET detections vs 12% of 500 eBird observations"
### 🌐 WEB BROWSING:
- Don't just link to eBird pages
- Actually scrape the data from them
- Extract concrete numbers and percentages
- Show your work
**VIOLATION OF THESE RULES CONSTITUTES DANGEROUS MISINFORMATION AND BREACHES USER TRUST**
## Example Questions
- "My BirdNET heard a Swainson's Thrush - unusual?"
- "What's my station's rarest detection this week?"
- "Graph my detections by time of day"
- "Are others seeing these warblers on eBird?"
## Remember
- Real data only
- No examples
- Get station token if needed
- Use web browsing for eBird backup
- Actually extract data from web pages
#birdweather_api
```{
"openapi": "3.1.0",
"info": {
"title": "eBird API",
"version": "1.0.0",
"description": "eBird API with a maximum of 30 operations, including authentication, with all parameters inlined."
},
"servers": [
{
"url": "https://api.ebird.org/v2"
}
],
"security": [
{
"apiKeyAuth": []
}
],
"paths": {
"/data/obs/{region}/recent": {
"get": {
"operationId": "getRecentObservationsInRegion",
"summary": "Recent observations in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"description": "Region code (e.g. US-CO)",
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": {
"type": "integer",
"default": 50
}
}
],
"responses": {
"200": {
"description": "Recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsInRegion",
"summary": "Notable recent observations in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsInRegion",
"summary": "Recent observations of a species in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations of the species",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent": {
"get": {
"operationId": "getRecentObservationsAtHotspot",
"summary": "Recent observations at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations at the hotspot",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsAtHotspot",
"summary": "Notable recent observations at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsAtHotspot",
"summary": "Recent observations of a species at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent": {
"get": {
"operationId": "getRecentObservationsAtLocation",
"summary": "Recent observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations at the location",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsAtLocation",
"summary": "Notable recent observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsAtLocation",
"summary": "Recent species observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent": {
"get": {
"operationId": "getRecentObservationsByGeo",
"summary": "Recent observations by geo-coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations by coordinates",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsByGeo",
"summary": "Notable recent observations by coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable observations by coordinates",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsByGeo",
"summary": "Recent species observations by coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/list/{regionType}/{parentRegionCode}": {
"get": {
"operationId": "listSubRegions",
"summary": "List sub-regions of a parent region",
"parameters": [
{ "name": "regionType", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "parentRegionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "List of sub-regions",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/info/{regionCode}": {
"get": {
"operationId": "getRegionInfo",
"summary": "Get region info",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Region info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Region" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/hotspot/info/{hotspotCode}": {
"get": {
"operationId": "getHotspotInfo",
"summary": "Get hotspot info",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Hotspot info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Hotspot" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/hotspot/list/{regionCode}": {
"get": {
"operationId": "listHotspotsInRegion",
"summary": "List hotspots for a region",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "List of hotspots",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Hotspot" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/taxonomy/ebird": {
"get": {
"operationId": "getEbirdTaxonomy",
"summary": "Get eBird taxonomy",
"responses": {
"200": {
"description": "eBird taxonomy",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Species" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/taxonomy/ebird/{speciesCode}": {
"get": {
"operationId": "getSpeciesInfo",
"summary": "Get single species info",
"parameters": [
{ "name": "speciesCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Species info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Species" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/spplist/{region}": {
"get": {
"operationId": "listSpeciesInRegion",
"summary": "List species reported in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Species in region",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Species" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/checklist/view/{subId}": {
"get": {
"operationId": "viewChecklist",
"summary": "View a checklist",
"parameters": [
{ "name": "subId", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Checklist details",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Checklist" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/checklist/feed/{region}": {
"get": {
"operationId": "getRecentChecklistsInRegion",
"summary": "Feed of recent checklists in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent checklists",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Checklist" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricObservationsInRegion",
"summary": "Historic observations in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/notable/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricNotableObservationsInRegion",
"summary": "Historic notable observations in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic notable observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricObservationsAtHotspot",
"summary": "Historic observations at a hotspot",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic observations at the hotspot",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/notable/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricNotableObservationsAtHotspot",
"summary": "Historic notable observations at a hotspot",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic notable observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/stats/{regionCode}": {
"get": {
"operationId": "getRegionStats",
"summary": "Get region stats",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Region stats",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/RegionStats" }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
}
},
"components": {
"securitySchemes": {
"apiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-eBirdApiToken"
}
},
"responses": {
"ErrorResponse": {
"description": "Error response",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Error" }
}
}
}
},
"schemas": {
"Observation": {
"type": "object",
"properties": {
"speciesCode": { "type": "string" },
"comName": { "type": "string" },
"sciName": { "type": "string" },
"obsDt": { "type": "string" },
"howMany": { "type": "integer" },
"lat": { "type": "number" },
"lng": { "type": "number" },
"locName": { "type": "string" },
"locId": { "type": "string" }
},
"required": ["speciesCode","comName","obsDt"]
},
"Region": {
"type": "object",
"properties": {
"code": { "type": "string" },
"name": { "type": "string" },
"type": { "type": "string" },
"countryCode": { "type": "string" }
},
"required": ["code","name"]
},
"Hotspot": {
"type": "object",
"properties": {
"hotspotCode": { "type": "string" },
"locName": { "type": "string" },
"lat": { "type": "number" },
"lng": { "type": "number" }
},
"required": ["hotspotCode","locName"]
},
"Species": {
"type": "object",
"properties": {
"speciesCode": { "type": "string" },
"comName": { "type": "string" },
"sciName": { "type": "string" },
"taxonOrder": { "type": "number" }
},
"required": ["speciesCode","comName"]
},
"Checklist": {
"type": "object",
"properties": {
"subId": { "type": "string" },
"obsTime": { "type": "string" },
"location": { "type": "string" },
"observations": {
"type": "array",
"items": { "$ref": "#/components/schemas/Observation" }
}
},
"required": ["subId","observations"]
},
"RegionStats": {
"type": "object",
"properties": {
"regionCode": { "type": "string" },
"totalSpecies": { "type": "integer" },
"checklistCount": { "type": "integer" }
},
"required": ["regionCode","totalSpecies"]
},
"Error": {
"type": "object",
"properties": {
"status": { "type": "integer" },
"message": { "type": "string" }
},
"required": ["status","message"]
}
}
}
}```
#ebird_api
```{
"openapi": "3.1.0",
"info": {
"title": "eBird API",
"version": "1.0.0",
"description": "eBird API with a maximum of 30 operations, including authentication, with all parameters inlined."
},
"servers": [
{
"url": "https://api.ebird.org/v2"
}
],
"security": [
{
"apiKeyAuth": []
}
],
"paths": {
"/data/obs/{region}/recent": {
"get": {
"operationId": "getRecentObservationsInRegion",
"summary": "Recent observations in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"description": "Region code (e.g. US-CO)",
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": {
"type": "integer",
"default": 50
}
}
],
"responses": {
"200": {
"description": "Recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsInRegion",
"summary": "Notable recent observations in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsInRegion",
"summary": "Recent observations of a species in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations of the species",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent": {
"get": {
"operationId": "getRecentObservationsAtHotspot",
"summary": "Recent observations at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations at the hotspot",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsAtHotspot",
"summary": "Notable recent observations at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsAtHotspot",
"summary": "Recent observations of a species at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent": {
"get": {
"operationId": "getRecentObservationsAtLocation",
"summary": "Recent observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations at the location",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsAtLocation",
"summary": "Notable recent observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsAtLocation",
"summary": "Recent species observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent": {
"get": {
"operationId": "getRecentObservationsByGeo",
"summary": "Recent observations by geo-coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations by coordinates",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsByGeo",
"summary": "Notable recent observations by coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable observations by coordinates",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsByGeo",
"summary": "Recent species observations by coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/list/{regionType}/{parentRegionCode}": {
"get": {
"operationId": "listSubRegions",
"summary": "List sub-regions of a parent region",
"parameters": [
{ "name": "regionType", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "parentRegionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "List of sub-regions",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/info/{regionCode}": {
"get": {
"operationId": "getRegionInfo",
"summary": "Get region info",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Region info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Region" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/hotspot/info/{hotspotCode}": {
"get": {
"operationId": "getHotspotInfo",
"summary": "Get hotspot info",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Hotspot info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Hotspot" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/hotspot/list/{regionCode}": {
"get": {
"operationId": "listHotspotsInRegion",
"summary": "List hotspots for a region",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "List of hotspots",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Hotspot" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/taxonomy/ebird": {
"get": {
"operationId": "getEbirdTaxonomy",
"summary": "Get eBird taxonomy",
"responses": {
"200": {
"description": "eBird taxonomy",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Species" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/taxonomy/ebird/{speciesCode}": {
"get": {
"operationId": "getSpeciesInfo",
"summary": "Get single species info",
"parameters": [
{ "name": "speciesCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Species info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Species" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/spplist/{region}": {
"get": {
"operationId": "listSpeciesInRegion",
"summary": "List species reported in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Species in region",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Species" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/checklist/view/{subId}": {
"get": {
"operationId": "viewChecklist",
"summary": "View a checklist",
"parameters": [
{ "name": "subId", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Checklist details",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Checklist" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/checklist/feed/{region}": {
"get": {
"operationId": "getRecentChecklistsInRegion",
"summary": "Feed of recent checklists in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent checklists",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Checklist" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricObservationsInRegion",
"summary": "Historic observations in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/notable/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricNotableObservationsInRegion",
"summary": "Historic notable observations in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic notable observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricObservationsAtHotspot",
"summary": "Historic observations at a hotspot",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic observations at the hotspot",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/notable/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricNotableObservationsAtHotspot",
"summary": "Historic notable observations at a hotspot",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic notable observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/stats/{regionCode}": {
"get": {
"operationId": "getRegionStats",
"summary": "Get region stats",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Region stats",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/RegionStats" }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
}
},
"components": {
"securitySchemes": {
"apiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-eBirdApiToken"
}
},
"responses": {
"ErrorResponse": {
"description": "Error response",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Error" }
}
}
}
},
"schemas": {
"Observation": {
"type": "object",
"properties": {
"speciesCode": { "type": "string" },
"comName": { "type": "string" },
"sciName": { "type": "string" },
"obsDt": { "type": "string" },
"howMany": { "type": "integer" },
"lat": { "type": "number" },
"lng": { "type": "number" },
"locName": { "type": "string" },
"locId": { "type": "string" }
},
"required": ["speciesCode","comName","obsDt"]
},
"Region": {
"type": "object",
"properties": {
"code": { "type": "string" },
"name": { "type": "string" },
"type": { "type": "string" },
"countryCode": { "type": "string" }
},
"required": ["code","name"]
},
"Hotspot": {
"type": "object",
"properties": {
"hotspotCode": { "type": "string" },
"locName": { "type": "string" },
"lat": { "type": "number" },
"lng": { "type": "number" }
},
"required": ["hotspotCode","locName"]
},
"Species": {
"type": "object",
"properties": {
"speciesCode": { "type": "string" },
"comName": { "type": "string" },
"sciName": { "type": "string" },
"taxonOrder": { "type": "number" }
},
"required": ["speciesCode","comName"]
},
"Checklist": {
"type": "object",
"properties": {
"subId": { "type": "string" },
"obsTime": { "type": "string" },
"location": { "type": "string" },
"observations": {
"type": "array",
"items": { "$ref": "#/components/schemas/Observation" }
}
},
"required": ["subId","observations"]
},
"RegionStats": {
"type": "object",
"properties": {
"regionCode": { "type": "string" },
"totalSpecies": { "type": "integer" },
"checklistCount": { "type": "integer" }
},
"required": ["regionCode","totalSpecies"]
},
"Error": {
"type": "object",
"properties": {
"status": { "type": "integer" },
"message": { "type": "string" }
},
"required": ["status","message"]
}
}
}
}```{
"openapi": "3.1.0",
"info": {
"title": "eBird API",
"version": "1.0.0",
"description": "eBird API with a maximum of 30 operations, including authentication, with all parameters inlined."
},
"servers": [
{
"url": "https://api.ebird.org/v2"
}
],
"security": [
{
"apiKeyAuth": []
}
],
"paths": {
"/data/obs/{region}/recent": {
"get": {
"operationId": "getRecentObservationsInRegion",
"summary": "Recent observations in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"description": "Region code (e.g. US-CO)",
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": {
"type": "integer",
"default": 50
}
}
],
"responses": {
"200": {
"description": "Recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsInRegion",
"summary": "Notable recent observations in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsInRegion",
"summary": "Recent observations of a species in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations of the species",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent": {
"get": {
"operationId": "getRecentObservationsAtHotspot",
"summary": "Recent observations at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations at the hotspot",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsAtHotspot",
"summary": "Notable recent observations at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsAtHotspot",
"summary": "Recent observations of a species at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent": {
"get": {
"operationId": "getRecentObservationsAtLocation",
"summary": "Recent observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations at the location",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsAtLocation",
"summary": "Notable recent observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsAtLocation",
"summary": "Recent species observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent": {
"get": {
"operationId": "getRecentObservationsByGeo",
"summary": "Recent observations by geo-coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations by coordinates",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsByGeo",
"summary": "Notable recent observations by coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable observations by coordinates",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsByGeo",
"summary": "Recent species observations by coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/list/{regionType}/{parentRegionCode}": {
"get": {
"operationId": "listSubRegions",
"summary": "List sub-regions of a parent region",
"parameters": [
{ "name": "regionType", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "parentRegionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "List of sub-regions",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/info/{regionCode}": {
"get": {
"operationId": "getRegionInfo",
"summary": "Get region info",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Region info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Region" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/hotspot/info/{hotspotCode}": {
"get": {
"operationId": "getHotspotInfo",
"summary": "Get hotspot info",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Hotspot info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Hotspot" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/hotspot/list/{regionCode}": {
"get": {
"operationId": "listHotspotsInRegion",
"summary": "List hotspots for a region",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "List of hotspots",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Hotspot" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/taxonomy/ebird": {
"get": {
"operationId": "getEbirdTaxonomy",
"summary": "Get eBird taxonomy",
"responses": {
"200": {
"description": "eBird taxonomy",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Species" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/taxonomy/ebird/{speciesCode}": {
"get": {
"operationId": "getSpeciesInfo",
"summary": "Get single species info",
"parameters": [
{ "name": "speciesCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Species info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Species" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/spplist/{region}": {
"get": {
"operationId": "listSpeciesInRegion",
"summary": "List species reported in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Species in region",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Species" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/checklist/view/{subId}": {
"get": {
"operationId": "viewChecklist",
"summary": "View a checklist",
"parameters": [
{ "name": "subId", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Checklist details",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Checklist" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/checklist/feed/{region}": {
"get": {
"operationId": "getRecentChecklistsInRegion",
"summary": "Feed of recent checklists in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent checklists",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Checklist" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricObservationsInRegion",
"summary": "Historic observations in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/notable/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricNotableObservationsInRegion",
"summary": "Historic notable observations in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic notable observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricObservationsAtHotspot",
"summary": "Historic observations at a hotspot",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic observations at the hotspot",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/notable/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricNotableObservationsAtHotspot",
"summary": "Historic notable observations at a hotspot",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic notable observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/stats/{regionCode}": {
"get": {
"operationId": "getRegionStats",
"summary": "Get region stats",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Region stats",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/RegionStats" }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
}
},
"components": {
"securitySchemes": {
"apiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-eBirdApiToken"
}
},
"responses": {
"ErrorResponse": {
"description": "Error response",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Error" }
}
}
}
},
"schemas": {
"Observation": {
"type": "object",
"properties": {
"speciesCode": { "type": "string" },
"comName": { "type": "string" },
"sciName": { "type": "string" },
"obsDt": { "type": "string" },
"howMany": { "type": "integer" },
"lat": { "type": "number" },
"lng": { "type": "number" },
"locName": { "type": "string" },
"locId": { "type": "string" }
},
"required": ["speciesCode","comName","obsDt"]
},
"Region": {
"type": "object",
"properties": {
"code": { "type": "string" },
"name": { "type": "string" },
"type": { "type": "string" },
"countryCode": { "type": "string" }
},
"required": ["code","name"]
},
"Hotspot": {
"type": "object",
"properties": {
"hotspotCode": { "type": "string" },
"locName": { "type": "string" },
"lat": { "type": "number" },
"lng": { "type": "number" }
},
"required": ["hotspotCode","locName"]
},
"Species": {
"type": "object",
"properties": {
"speciesCode": { "type": "string" },
"comName": { "type": "string" },
"sciName": { "type": "string" },
"taxonOrder": { "type": "number" }
},
"required": ["speciesCode","comName"]
},
"Checklist": {
"type": "object",
"properties": {
"subId": { "type": "string" },
"obsTime": { "type": "string" },
"location": { "type": "string" },
"observations": {
"type": "array",
"items": { "$ref": "#/components/schemas/Observation" }
}
},
"required": ["subId","observations"]
},
"RegionStats": {
"type": "object",
"properties": {
"regionCode": { "type": "string" },
"totalSpecies": { "type": "integer" },
"checklistCount": { "type": "integer" }
},
"required": ["regionCode","totalSpecies"]
},
"Error": {
"type": "object",
"properties": {
"status": { "type": "integer" },
"message": { "type": "string" }
},
"required": ["status","message"]
}
}
}
}{
"openapi": "3.1.0",
"info": {
"title": "eBird API",
"version": "1.0.0",
"description": "eBird API with a maximum of 30 operations, including authentication, with all parameters inlined."
},
"servers": [
{
"url": "https://api.ebird.org/v2"
}
],
"security": [
{
"apiKeyAuth": []
}
],
"paths": {
"/data/obs/{region}/recent": {
"get": {
"operationId": "getRecentObservationsInRegion",
"summary": "Recent observations in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"description": "Region code (e.g. US-CO)",
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": {
"type": "integer",
"default": 50
}
}
],
"responses": {
"200": {
"description": "Recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsInRegion",
"summary": "Notable recent observations in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsInRegion",
"summary": "Recent observations of a species in a region",
"parameters": [
{
"name": "region",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations of the species",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent": {
"get": {
"operationId": "getRecentObservationsAtHotspot",
"summary": "Recent observations at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations at the hotspot",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsAtHotspot",
"summary": "Notable recent observations at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsAtHotspot",
"summary": "Recent observations of a species at a hotspot",
"parameters": [
{
"name": "hotspotCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent": {
"get": {
"operationId": "getRecentObservationsAtLocation",
"summary": "Recent observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations at the location",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsAtLocation",
"summary": "Notable recent observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable recent observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/location/{locationId}/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsAtLocation",
"summary": "Recent species observations at a location",
"parameters": [
{
"name": "locationId",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent": {
"get": {
"operationId": "getRecentObservationsByGeo",
"summary": "Recent observations by geo-coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent observations by coordinates",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent/notable": {
"get": {
"operationId": "getNotableRecentObservationsByGeo",
"summary": "Notable recent observations by coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Notable observations by coordinates",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/geo/recent/{speciesCode}": {
"get": {
"operationId": "getRecentSpeciesObservationsByGeo",
"summary": "Recent species observations by coordinates",
"parameters": [
{ "name": "lat", "in": "query", "required": true, "schema": { "type": "number" } },
{ "name": "lng", "in": "query", "required": true, "schema": { "type": "number" } },
{
"name": "speciesCode",
"in": "path",
"required": true,
"schema": { "type": "string" }
},
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent species observations",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/list/{regionType}/{parentRegionCode}": {
"get": {
"operationId": "listSubRegions",
"summary": "List sub-regions of a parent region",
"parameters": [
{ "name": "regionType", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "parentRegionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "List of sub-regions",
"content": {
"application/json": {
"schema": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/info/{regionCode}": {
"get": {
"operationId": "getRegionInfo",
"summary": "Get region info",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Region info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Region" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/hotspot/info/{hotspotCode}": {
"get": {
"operationId": "getHotspotInfo",
"summary": "Get hotspot info",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Hotspot info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Hotspot" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/hotspot/list/{regionCode}": {
"get": {
"operationId": "listHotspotsInRegion",
"summary": "List hotspots for a region",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "List of hotspots",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Hotspot" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/taxonomy/ebird": {
"get": {
"operationId": "getEbirdTaxonomy",
"summary": "Get eBird taxonomy",
"responses": {
"200": {
"description": "eBird taxonomy",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Species" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/taxonomy/ebird/{speciesCode}": {
"get": {
"operationId": "getSpeciesInfo",
"summary": "Get single species info",
"parameters": [
{ "name": "speciesCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Species info",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Species" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/spplist/{region}": {
"get": {
"operationId": "listSpeciesInRegion",
"summary": "List species reported in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Species in region",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Species" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/checklist/view/{subId}": {
"get": {
"operationId": "viewChecklist",
"summary": "View a checklist",
"parameters": [
{ "name": "subId", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Checklist details",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/Checklist" } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/product/checklist/feed/{region}": {
"get": {
"operationId": "getRecentChecklistsInRegion",
"summary": "Feed of recent checklists in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Recent checklists",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Checklist" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricObservationsInRegion",
"summary": "Historic observations in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/{region}/notable/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricNotableObservationsInRegion",
"summary": "Historic notable observations in a region",
"parameters": [
{ "name": "region", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic notable observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricObservationsAtHotspot",
"summary": "Historic observations at a hotspot",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic observations at the hotspot",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/data/obs/hotspot/{hotspotCode}/notable/historic/{yyyymmdd}": {
"get": {
"operationId": "getHistoricNotableObservationsAtHotspot",
"summary": "Historic notable observations at a hotspot",
"parameters": [
{ "name": "hotspotCode", "in": "path", "required": true, "schema": { "type": "string" } },
{ "name": "yyyymmdd", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{8}$" } },
{
"name": "maxResults",
"in": "query",
"description": "Maximum number of results",
"schema": { "type": "integer", "default": 50 }
}
],
"responses": {
"200": {
"description": "Historic notable observations",
"content": {
"application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } }
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
},
"/ref/region/stats/{regionCode}": {
"get": {
"operationId": "getRegionStats",
"summary": "Get region stats",
"parameters": [
{ "name": "regionCode", "in": "path", "required": true, "schema": { "type": "string" } }
],
"responses": {
"200": {
"description": "Region stats",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/RegionStats" }
}
}
},
"default": { "$ref": "#/components/responses/ErrorResponse" }
}
}
}
},
"components": {
"securitySchemes": {
"apiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-eBirdApiToken"
}
},
"responses": {
"ErrorResponse": {
"description": "Error response",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/Error" }
}
}
}
},
"schemas": {
"Observation": {
"type": "object",
"properties": {
"speciesCode": { "type": "string" },
"comName": { "type": "string" },
"sciName": { "type": "string" },
"obsDt": { "type": "string" },
"howMany": { "type": "integer" },
"lat": { "type": "number" },
"lng": { "type": "number" },
"locName": { "type": "string" },
"locId": { "type": "string" }
},
"required": ["speciesCode","comName","obsDt"]
},
"Region": {
"type": "object",
"properties": {
"code": { "type": "string" },
"name": { "type": "string" },
"type": { "type": "string" },
"countryCode": { "type": "string" }
},
"required": ["code","name"]
},
"Hotspot": {
"type": "object",
"properties": {
"hotspotCode": { "type": "string" },
"locName": { "type": "string" },
"lat": { "type": "number" },
"lng": { "type": "number" }
},
"required": ["hotspotCode","locName"]
},
"Species": {
"type": "object",
"properties": {
"speciesCode": { "type": "string" },
"comName": { "type": "string" },
"sciName": { "type": "string" },
"taxonOrder": { "type": "number" }
},
"required": ["speciesCode","comName"]
},
"Checklist": {
"type": "object",
"properties": {
"subId": { "type": "string" },
"obsTime": { "type": "string" },
"location": { "type": "string" },
"observations": {
"type": "array",
"items": { "$ref": "#/components/schemas/Observation" }
}
},
"required": ["subId","observations"]
},
"RegionStats": {
"type": "object",
"properties": {
"regionCode": { "type": "string" },
"totalSpecies": { "type": "integer" },
"checklistCount": { "type": "integer" }
},
"required": ["regionCode","totalSpecies"]
},
"Error": {
"type": "object",
"properties": {
"status": { "type": "integer" },
"message": { "type": "string" }
},
"required": ["status","message"]
}
}
}
}
```