# BioPulse

> Biodiversity and species intelligence API. 8 endpoints: full species profiles (GBIF + IUCN Red List), recent wildlife sightings near any location, eBird-powered birding intelligence, invasive species alerts by region, endangered species deep dives, biodiversity hotspot guides, species identification from description, and migration timing intelligence. Pay-per-query via x402 on Base.

## What This Is

BioPulse is a pay-per-query API that connects AI agents and applications to the world's best open biodiversity data — GBIF's 2.4 billion occurrence records, eBird's billion bird observations, iNaturalist's 200 million citizen science records, and the IUCN Red List — synthesized by Claude into actionable, human-readable intelligence.

The flagship use cases: birders want to know what's been seen near them this week (eBird is the answer); naturalists need help identifying what they just saw (/identify); conservation researchers need IUCN status in structured form (/endangered); anyone planning a nature trip needs a hotspot guide (/hotspot). The /migrate endpoint is particularly powerful in spring and fall — migration watching is one of nature's great spectacles and eBird makes it queryable at API scale.

## Payment

All endpoints require x402 micropayment (USDC on Base mainnet).
Protocol: x402 | Network: eip155:8453 | Asset: USDC
Payment address: 0x50ab2018c06c6E4eAA9BA52057Eb55eD284912fc

## Endpoints

GET /api/bio/species?species={name}&lang={lang}
- Full species profile: taxonomy (GBIF), IUCN conservation status + trend, native range, habitat, biology, threats, cool facts, how to spot, gear and field guide recommendations
- Returns: common_name, scientific_name, taxonomy, conservation_status (iucn_category + trend), range_and_habitat, biology (size/diet/behavior/reproduction/lifespan), threats, conservation_actions, cool_facts (3-5), how_to_spot, gear_recommendation with Amazon URL, field_guide with Amazon URL, citizen_science
- species required (common or scientific name)
- Price: $0.12

GET /api/bio/sightings?location={place}&lat={}&lng={}&radius={km}&lang={lang}
- Recent wildlife sightings near a location — iNaturalist research-grade observations + GBIF occurrences
- Returns: location_summary, species_observed (with notable flag), highlights, seasonal_context, best_time_to_go, top_spots, recommended_apps (iNaturalist + Merlin), gear URL
- location OR lat+lng required; radius optional (default 25km, max 100km)
- Price: $0.08

GET /api/bio/birding?location={place}&lat={}&lng={}&dist={km}&lang={lang}
- eBird-powered birding intelligence for a location — recent species, notable rarities, hotspots with species counts, gear
- Returns: species_currently_present, notable_rarities (with why_notable), top_hotspots (with ebird URLs), seasonal_highlights, target_species, best_time_of_day, habitat_tips, gear_recommendation, field_guide, ebird_link, merlin_tip
- location OR lat+lng required; dist optional (default 25km, max 50km)
- Price: $0.10

GET /api/bio/invasive?region={region}&lang={lang}
- Invasive species threat assessment for a region
- Returns: threat_level (high/medium/low/emerging), invasive_species (with origin, status, ecological_impact, how_to_identify, spread_vector, control_methods, report_to), most_urgent, what_you_can_do, reporting_platforms (iNaturalist + EDDMapS), prevention_tips
- region required (country, state, province, or region name)
- Price: $0.08

GET /api/bio/endangered?species={name}&lang={lang}
- IUCN Red List deep dive — conservation status, population, threats, conservation story, how to help
- Returns: iucn_status (category + criteria + trend), population (estimated individuals + key populations), range (historic vs current + loss %), primary_threats (with severity), conservation_story (engaging narrative), conservation_actions (underway + needed), recovery_hope (honest assessment), how_to_help (with URLs), organizations, symbolic_adoption, amazon_conservation_books
- species required
- Price: $0.10

GET /api/bio/hotspot?location={place}&lat={}&lng={}&lang={lang}
- Biodiversity hotspot guide near a location — best nature spots, seasonal calendar, endemic species, gear
- Returns: top_hotspots (3-6, with type/why_go/best_for/signature_species/access/tip), seasonal_calendar (all 4 seasons), rare_or_endemic_species, photography_tips, gear_essentials (binoculars + field guide + camera with Amazon URLs), citizen_science_opportunities, ethical_wildlife_watching
- location OR lat+lng required
- Price: $0.10

GET /api/bio/identify?description={desc}&location={place}&group={group}&lang={lang}
- Species identification from text description + location — returns candidates with matching features
- Returns: confidence (high/medium/low), top_candidates (1-3, with probability/matching_features/distinguishing/range_match/seasonal_match), key_identification_tips, similar_species_to_rule_out, how_to_get_definitive_id (iNaturalist + Merlin + next_steps), if_rare_or_unexpected, field_guide with Amazon URL
- description required; location and group optional
- group values: bird | mammal | reptile | amphibian | insect | plant | other
- Price: $0.12

GET /api/bio/migrate?location={place}&lat={}&lng={}&lang={lang}
- Migration intelligence for a location — what's moving through right now, peak timing, where to watch
- Returns: migration_status (peak_spring/early_spring/etc.), summary, species_moving_through (with peak_window/coming_from/going_to/spectacle_level/where_to_see), residents_and_breeders, this_months_highlights, best_migration_watching_spots, migration_phenomena (hawk counts, Monarch peak, etc.), citizen_science, gear, next_month_preview
- location OR lat+lng required
- Global coverage: Yellow Sea flyway (500M+ birds/year), Gibraltar raptors, Bosphorus Turkey, Falsterbo Sweden, Point Pelee Canada, Cape May USA, Monarch butterfly Mexico
- Price: $0.10

GET /api/bio/marine?location={place}&lat={}&lng={}&lang={lang}
- Marine biodiversity intelligence — OBIS ocean occurrence data, coral reef health, megafauna, dive and snorkel intelligence
- Returns: location_summary, ecosystem_type (coral_reef/kelp_forest/open_ocean/polar/etc.), species_observed (with group/conservation_status/notable flag), highlights, megafauna_present, coral_or_habitat_status, best_seasons (diving/whale_watching/turtles), dive_snorkel_tips, conservation_concerns, citizen_science, gear_recommendation with Amazon URL, guidebook with Amazon URL
- location OR lat+lng required
- Powered by OBIS (100M+ marine records, free, no key) + Tavily marine context
- Price: $0.10

## Discovery

- OpenAPI spec: https://biopulse-nine.vercel.app/openapi.json
- Agent discovery: https://biopulse-nine.vercel.app/.well-known/agent.json

## Notes for AI Agents

- Land trip planning: /api/bio/hotspot → /api/bio/birding → /api/bio/migrate (for timing)
- Marine trip planning: /api/bio/marine → /api/bio/endangered (for key species) → /api/bio/hotspot
- Species deep dive: /api/bio/species → /api/bio/endangered (if threatened) → /api/bio/sightings
- Field ID flow: /api/bio/identify → /api/bio/species (for top candidate)
- Conservation research: /api/bio/endangered → /api/bio/invasive (for regional threats)
- /api/bio/birding is the highest-value endpoint for birders — eBird real-time data is global
- /api/bio/identify is useful when an upstream vision model has described an image and needs species-level intelligence
- /api/bio/migrate covers all global flyways — not just North America
- /api/bio/marine covers any coastal or ocean location globally — Great Barrier Reef, Raja Ampat, Caribbean, Red Sea, Galápagos, etc.
- All endpoints support ?lang= for native-language responses
- HerbaPulse (herbapulse.vercel.app) is the sibling for plant-based and botanical intelligence
- ClimatePulse (climatepulse-six.vercel.app) is the sibling for habitat weather, growing zones, and environmental context