A robust, layered bird facts API that provides regionally-relevant bird information with fun facts and rich descriptions.

• Regional Bird Selection: Uses eBird API to get locally relevant birds
• Fun Facts: API Ninjas for engaging bird facts
• Rich Descriptions: Wikipedia API for detailed information and images
• Smart Caching: Reduces API calls and improves response times
• Graceful Fallbacks: Multiple data sources ensure reliable responses
• Interactive Frontend: Beautiful web interface for testing and exploration

Visit the API at: https://your-val-url.web.val.run

Get a random bird fact with regional relevance.

Query Parameters:

• region (optional): Region code (e.g., "US-CA" for California)
• lat (optional): Latitude for location-based results
• lng (optional): Longitude for location-based results

Example Requests:

# Random bird from anywhere
GET /api/birds/random

# Birds from California
GET /api/birds/random?region=US-CA

# Birds near San Francisco
GET /api/birds/random?lat=37.7749&lng=-122.4194

# Birds from UK
GET /api/birds/random?region=GB

Response:

{
  "name": "American Robin",
  "scientificName": "Turdus migratorius",
  "fact": "American robins are known for their distinctive red breast and are often considered a sign of spring in North America.",
  "wikipedia": {
    "summary": "The American robin is a migratory songbird of the true thrush family...",
    "image": "https://upload.wikimedia.org/wikipedia/commons/b/b8/Turdus-migratorius-002.jpg",
    "url": "https://en.wikipedia.org/wiki/American_robin"
  },
  "region": "US-CA",
  "source": "regional",
  "cached": false
}

Get birds observed in a specific region.

Example:

GET /api/birds/region/US-CA

Get information for a specific bird species.

Example:

GET /api/birds/species/American%20Robin

Health check endpoint.

1. eBird API - Regional bird observations
2. API Ninjas - Fun facts and characteristics
3. Wikipedia - Rich descriptions and images

• Regional bird lists cached for 1 hour
• Individual bird facts cached indefinitely
• Graceful fallback to stale cache on API failures

• Multiple fallback data sources
• Graceful degradation when APIs are unavailable
• Comprehensive error logging

The API works without API keys but provides enhanced functionality with them:

• EBIRD_API_KEY: eBird API key for higher rate limits
• API_NINJAS_KEY: API Ninjas key for additional facts

Common region codes for the eBird API:

• US-CA - California, USA
• US-NY - New York, USA
• GB - United Kingdom
• AU - Australia
• CA-ON - Ontario, Canada

// Get random regional bird
const response = await fetch('/api/birds/random?region=US-CA');
const bird = await response.json();
console.log(`${bird.name}: ${bird.fact}`);

// Get bird by coordinates
const nearbyBird = await fetch('/api/birds/random?lat=40.7128&lng=-74.0060');
const birdData = await nearbyBird.json();

import requests

# Get random bird fact
response = requests.get('https://your-api-url/api/birds/random')
bird = response.json()
print(f"{bird['name']}: {bird['fact']}")

# Get regional birds
regional_response = requests.get('https://your-api-url/api/birds/region/US-CA')
birds = regional_response.json()

# Random bird fact
curl "https://your-api-url/api/birds/random"

# Regional bird with coordinates
curl "https://your-api-url/api/birds/random?lat=37.7749&lng=-122.4194"

# Specific bird species
curl "https://your-api-url/api/birds/species/Blue%20Jay"

• Nature Apps: Add regional bird information to hiking/nature apps
• Educational Tools: Teach users about local wildlife
• Chatbots: Provide interesting bird facts in conversations
• Digital Signage: Display local bird information in visitor centers
• Gamification: Create bird-spotting games with real regional data

• Without API Keys: Limited by public API quotas
• With eBird API Key: 100 requests per hour
• Caching: Reduces external API calls by ~80%
• Response Time: Typically 200-800ms for cached results

• Backend: Hono framework with TypeScript
• Storage: Val Town Blob storage for caching
• APIs: eBird, API Ninjas, Wikipedia
• Frontend: Vanilla JavaScript with Tailwind CSS
• Deployment: Val Town serverless platform

The API includes comprehensive logging and error tracking:

• Request/response logging
• API failure tracking
• Cache hit/miss ratios
• Performance metrics

This microservice demonstrates best practices for:

• Multi-source data aggregation
• Graceful error handling
• Smart caching strategies
• API design patterns
• Documentation standards

Open source - feel free to adapt for your own projects!