# eBird Scraper (`crawlerbros/ebird-scraper`) Actor Scrape eBird (Cornell Lab of Ornithology) - species taxonomy, recent bird observations by region or hotspot, and birding hotspots. Optional free API key unlocks observation data; taxonomy search works without any key. - **URL**: https://apify.com/crawlerbros/ebird-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Agents, Automation, Integrations - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## eBird Scraper Scrape bird observation data from **eBird** (Cornell Lab of Ornithology) — the world's largest citizen science bird observation database with over 1 billion records. Extract species taxonomy, recent bird sightings by region, birding hotspots, and observations at specific hotspot locations. ### What data can you extract? - **Species Taxonomy**: Full Cornell Lab taxonomy database with 17,000+ species — scientific names, common names, family classifications, banding codes. Works without any API key. - **Recent Observations**: Latest bird sightings in any US state, country, or sub-national region (requires free API key). - **Birding Hotspots**: Popular birding locations in any region with GPS coordinates and species counts (requires free API key). - **Hotspot Sightings**: Recent observations at a specific birding hotspot like Central Park or Point Reyes (requires free API key). ### Getting a Free eBird API Key Most modes require a free eBird API key: 1. Create a free account at [ebird.org](https://ebird.org) 2. Visit [ebird.org/api/keygen](https://ebird.org/api/keygen) 3. Request an API key (usually granted instantly) 4. Enter the key in the `apiKey` input field The **Taxonomy** mode works without any API key. ### Input | Field | Type | Required | Description | |-------|------|----------|-------------| | `mode` | Select | Yes | What to fetch: `taxonomy`, `recentObservations`, `hotspots`, `byHotspot` | | `apiKey` | String | No* | Free eBird API key (*required for all modes except taxonomy) | | `speciesQuery` | String | No | Search term for bird name (taxonomy mode) | | `speciesCode` | String | No | Filter taxonomy to specific species code (e.g. `amerob`) | | `category` | Select | No | Taxonomy category filter: species, hybrid, slash, etc. | | `orderFilter` | String | No | Filter taxonomy to a specific taxonomic order (e.g. `Passeriformes`, `Anseriformes`) | | `familyFilter` | String | No | Filter taxonomy to a specific bird family by name or family code (e.g. `Anatidae`, `anatid1`) | | `order` | Select | No | Taxonomy sort order: `taxon` (Cornell Lab taxonomic order, default) or `comName` (alphabetical by common name) | | `regionCode` | String | No | eBird region code: US-NY, GB-ENG, CA-ON, AU-NSW, etc. | | `locationId` | String | No | Hotspot location ID (e.g. `L109516` for Central Park) | | `backDays` | Integer | No | Days to look back for recent observations (1-30, default: 7) | | `includeProvisional` | Boolean | No | Include unreviewed records (default: true) | | `onlyHotspots` | Boolean | No | Only return observations at designated hotspots | | `locale` | String | No | Language locale for common names (en, es, fr, de, etc.) | | `maxItems` | Integer | No | Maximum records to return (1-10000, default: 50) | ### Output #### Taxonomy Record (`recordType: "taxonomy"`) | Field | Type | Description | |-------|------|-------------| | `speciesCode` | String | eBird species code (e.g. `amerob`) | | `commonName` | String | Common English name (e.g. `American Robin`) | | `scientificName` | String | Scientific name (e.g. `Turdus migratorius`) | | `category` | String | Taxonomy category (species, hybrid, slash, etc.) | | `taxonOrder` | Float | Cornell Lab taxonomic order number | | `order` | String | Taxonomic order (e.g. `Passeriformes`) | | `familyCode` | String | eBird family code | | `familyCommonName` | String | Family common name (e.g. `Thrushes and Allies`) | | `familySciName` | String | Family scientific name (e.g. `Turdidae`) | | `bandingCodes` | Array | Official banding codes (e.g. `["AMRO"]`) | | `comNameCodes` | Array | Common name abbreviation codes | | `sciNameCodes` | Array | Scientific name abbreviation codes | | `sourceUrl` | String | eBird species page URL | | `scrapedAt` | String | ISO timestamp when record was scraped | | `recordType` | String | `"taxonomy"` | #### Observation Record (`recordType: "observation"`) | Field | Type | Description | |-------|------|-------------| | `speciesCode` | String | eBird species code | | `commonName` | String | Common name | | `scientificName` | String | Scientific name | | `locationId` | String | eBird location ID (e.g. `L109516`) | | `locationName` | String | Location name | | `countryCode` | String | Country code (e.g. `US`) | | `countryName` | String | Country name (e.g. `United States`) | | `subnational1Code` | String | State/province code (e.g. `US-NY`) | | `subnational1Name` | String | State/province name (e.g. `New York`) | | `subnational2Code` | String | County/district code | | `subnational2Name` | String | County/district name | | `userDisplayName` | String | Observer display name | | `obsId` | String | eBird observation ID | | `exoticCategory` | String | Exotic classification for non-native sightings (e.g. `N`, `P`, `X`) | | `obsDt` | String | Observation date/time | | `howMany` | Integer | Count of individuals observed | | `lat` | Float | Latitude | | `lng` | Float | Longitude | | `obsValid` | Boolean | Whether observation was marked valid | | `obsReviewed` | Boolean | Whether observation was reviewed | | `locationPrivate` | Boolean | Whether location is private | | `subId` | String | eBird checklist submission ID | | `checklistUrl` | String | URL to full checklist | | `regionCode` | String | Region queried (recentObservations mode) | | `hotspotId` | String | Hotspot location ID queried (byHotspot mode) | | `sourceUrl` | String | eBird species page URL | | `scrapedAt` | String | ISO timestamp | | `recordType` | String | `"observation"` | #### Hotspot Record (`recordType: "hotspot"`) | Field | Type | Description | |-------|------|-------------| | `locationId` | String | eBird location ID | | `locationName` | String | Hotspot name | | `countryCode` | String | Country code (e.g. `US`) | | `subnational1Code` | String | State/province code (e.g. `US-NY`) | | `subnational2Code` | String | County/district code | | `lat` | Float | Latitude | | `lng` | Float | Longitude | | `latestObsDt` | String | Date of most recent observation | | `numSpeciesAllTime` | Integer | Total species ever recorded at this hotspot | | `regionCode` | String | Region queried | | `sourceUrl` | String | eBird hotspot page URL | | `scrapedAt` | String | ISO timestamp | | `recordType` | String | `"hotspot"` | ### Example Use Cases - **Birdwatchers**: Find what birds were recently seen in your area before heading out - **Research**: Download taxonomy data for analysis or labeling ML datasets - **Travel planning**: Discover top birding hotspots in regions you plan to visit - **Citizen science**: Monitor bird population trends by region ### Region Code Examples | Code | Region | |------|--------| | `US-NY` | New York State, USA | | `US-CA` | California, USA | | `GB-ENG` | England, UK | | `CA-ON` | Ontario, Canada | | `AU-NSW` | New South Wales, Australia | | `IN` | India | | `MX` | Mexico | | `ZA` | South Africa | ### FAQs **Q: Do I need an API key?** A: The Taxonomy mode works without any key. For Recent Observations, Hotspots, and Observations at Hotspot modes you need a free eBird API key from [ebird.org/api/keygen](https://ebird.org/api/keygen). **Q: How current is the observation data?** A: The `backDays` input controls how many days back to look (1-30 days). Real-time data from eBird's citizen science community. **Q: What region codes does eBird use?** A: eBird uses standard ISO codes: country level (US, GB, IN), state/province (US-NY, GB-ENG), and even county level (US-NY-061). Find your region code at [ebird.org/explore](https://ebird.org/explore). **Q: How many species are in the taxonomy?** A: The full eBird taxonomy includes approximately 17,000+ taxonomic entries covering 11,000+ species. **Q: Is there a rate limit?** A: eBird's free API has reasonable rate limits for normal use. This scraper includes retry logic for temporary errors. # Actor input Schema ## `mode` (type: `string`): What data to fetch from eBird. ## `apiKey` (type: `string`): Free eBird API key from ebird.org/api/keygen. Required for recentObservations, hotspots, and byHotspot modes. Taxonomy mode works without it. ## `speciesQuery` (type: `string`): Free-text search term for species name (common or scientific). Leave blank to browse all species. ## `speciesCode` (type: `string`): eBird species code (e.g. 'amerob' for American Robin, 'mallar3' for Mallard). Filters taxonomy to this specific species. ## `category` (type: `string`): Filter taxonomy by category. ## `orderFilter` (type: `string`): Filter taxonomy to a specific taxonomic order (e.g. 'Passeriformes' for perching birds, 'Anseriformes' for waterfowl, 'Falconiformes' for falcons). Matches exactly, case-insensitive. ## `familyFilter` (type: `string`): Filter taxonomy to a specific bird family by name or eBird family code (e.g. 'Anatidae', 'Accipitridae', or 'anatid1'). Matches common name, scientific name, or family code. ## `regionCode` (type: `string`): eBird region code. Examples: US (United States), US-NY (New York), GB-ENG (England), AU-NSW (New South Wales), CA-ON (Ontario). Used in recentObservations and hotspots modes. ## `locationId` (type: `string`): eBird hotspot location ID (e.g. 'L109516' for Central Park). Used in byHotspot mode. ## `backDays` (type: `integer`): How many days back to fetch recent observations (1-30). ## `includeProvisional` (type: `boolean`): Include records not yet reviewed by a regional reviewer. ## `onlyHotspots` (type: `boolean`): Only return observations at designated hotspots (not personal locations). ## `order` (type: `string`): Sort order for taxonomy results. ## `locale` (type: `string`): Language for common names. Examples: en (English), es (Spanish), fr (French), de (German), pt (Portuguese), zh (Chinese). ## `maxItems` (type: `integer`): Maximum number of records to return. ## Actor input object example ```json { "mode": "taxonomy", "speciesQuery": "robin", "regionCode": "US-NY", "locationId": "L109516", "backDays": 7, "includeProvisional": true, "onlyHotspots": false, "order": "taxon", "locale": "en", "maxItems": 50 } ```` # Actor output Schema ## `records` (type: `string`): Dataset containing all scraped eBird records — taxonomy entries, observations, or hotspots depending on mode. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "taxonomy", "speciesQuery": "robin", "regionCode": "US-NY", "locationId": "L109516", "backDays": 7, "includeProvisional": true, "onlyHotspots": false, "order": "taxon", "locale": "en", "maxItems": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/ebird-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "taxonomy", "speciesQuery": "robin", "regionCode": "US-NY", "locationId": "L109516", "backDays": 7, "includeProvisional": True, "onlyHotspots": False, "order": "taxon", "locale": "en", "maxItems": 50, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/ebird-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "taxonomy", "speciesQuery": "robin", "regionCode": "US-NY", "locationId": "L109516", "backDays": 7, "includeProvisional": true, "onlyHotspots": false, "order": "taxon", "locale": "en", "maxItems": 50 }' | apify call crawlerbros/ebird-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/ebird-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "eBird Scraper", "description": "Scrape eBird (Cornell Lab of Ornithology) - species taxonomy, recent bird observations by region or hotspot, and birding hotspots. Optional free API key unlocks observation data; taxonomy search works without any key.", "version": "1.0", "x-build-id": "acOoDKMCb5qGwbqwq" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~ebird-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-ebird-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~ebird-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-ebird-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~ebird-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-ebird-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "taxonomy", "recentObservations", "hotspots", "byHotspot" ], "type": "string", "description": "What data to fetch from eBird.", "default": "taxonomy" }, "apiKey": { "title": "eBird API Key (optional)", "type": "string", "description": "Free eBird API key from ebird.org/api/keygen. Required for recentObservations, hotspots, and byHotspot modes. Taxonomy mode works without it." }, "speciesQuery": { "title": "Species Search Query (taxonomy mode)", "type": "string", "description": "Free-text search term for species name (common or scientific). Leave blank to browse all species." }, "speciesCode": { "title": "Species Code (taxonomy mode filter)", "type": "string", "description": "eBird species code (e.g. 'amerob' for American Robin, 'mallar3' for Mallard). Filters taxonomy to this specific species." }, "category": { "title": "Taxonomy Category (taxonomy mode)", "enum": [ "species", "issf", "slash", "hybrid", "intergrade", "domestic", "form", "spuh" ], "type": "string", "description": "Filter taxonomy by category." }, "orderFilter": { "title": "Taxonomic Order Filter (taxonomy mode)", "type": "string", "description": "Filter taxonomy to a specific taxonomic order (e.g. 'Passeriformes' for perching birds, 'Anseriformes' for waterfowl, 'Falconiformes' for falcons). Matches exactly, case-insensitive." }, "familyFilter": { "title": "Family Filter (taxonomy mode)", "type": "string", "description": "Filter taxonomy to a specific bird family by name or eBird family code (e.g. 'Anatidae', 'Accipitridae', or 'anatid1'). Matches common name, scientific name, or family code." }, "regionCode": { "title": "Region Code (observations/hotspots modes)", "type": "string", "description": "eBird region code. Examples: US (United States), US-NY (New York), GB-ENG (England), AU-NSW (New South Wales), CA-ON (Ontario). Used in recentObservations and hotspots modes.", "default": "US-NY" }, "locationId": { "title": "Hotspot Location ID (byHotspot mode)", "type": "string", "description": "eBird hotspot location ID (e.g. 'L109516' for Central Park). Used in byHotspot mode." }, "backDays": { "title": "Look-back Days (observations modes)", "minimum": 1, "maximum": 30, "type": "integer", "description": "How many days back to fetch recent observations (1-30).", "default": 7 }, "includeProvisional": { "title": "Include Provisional Records", "type": "boolean", "description": "Include records not yet reviewed by a regional reviewer.", "default": true }, "onlyHotspots": { "title": "Hotspots Only (observations mode)", "type": "boolean", "description": "Only return observations at designated hotspots (not personal locations).", "default": false }, "order": { "title": "Taxonomy Sort Order", "enum": [ "taxon", "comName" ], "type": "string", "description": "Sort order for taxonomy results.", "default": "taxon" }, "locale": { "title": "Language Locale (taxonomy mode)", "type": "string", "description": "Language for common names. Examples: en (English), es (Spanish), fr (French), de (German), pt (Portuguese), zh (Chinese).", "default": "en" }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of records to return.", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```