# iNaturalist Scraper - Nature Observations & Species Data (`lulzasaur/inaturalist-scraper`) Actor Scrape nature observations from iNaturalist. Search species, filter by quality grade and location. Get photos, GPS coordinates, identifications, and observer data from citizen science records. - **URL**: https://apify.com/lulzasaur/inaturalist-scraper.md - **Developed by:** [lulz bot](https://apify.com/lulzasaur) (community) - **Categories:** E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $10.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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 ## iNaturalist Scraper Scrape nature observations from [iNaturalist](https://www.inaturalist.org/), the world's largest citizen science biodiversity platform with 200M+ observations. ### What does iNaturalist Scraper do? This scraper extracts wildlife and nature observation data from iNaturalist's public API. Search for any species, taxon, or organism and get detailed observation records including species identification, GPS coordinates, photos, quality grades, and observer information. Perfect for: - **Researchers** analyzing species distribution and biodiversity data - **Conservation teams** tracking endangered species observations - **Educators** building datasets for ecology courses - **Data scientists** studying wildlife patterns and citizen science trends - **Developers** building nature identification or mapping apps ### Features - Search by species name (common or scientific) - Filter by quality grade (research, needs_id, casual) - Filter by geographic location using iNaturalist place IDs - Filter by date range - Automatic taxon resolution for precise species matching - Optional full detail scraping with identifications and comments - Built-in rate limiting to respect API guidelines - Pagination support for large datasets ### Input | Field | Type | Default | Description | |-------|------|---------|-------------| | `searchQueries` | string[] | `["monarch butterfly"]` | Species or taxa to search. Each query runs separately. | | `maxListings` | integer | `100` | Maximum observations per query (1-10,000) | | `qualityGrade` | enum | `research` | Filter: `research` (verified), `needs_id`, `casual`, or `any` | | `scrapeDetails` | boolean | `false` | Fetch full details with identifications and comments | | `placeId` | integer | - | iNaturalist place ID (e.g. 1=US, 6712=California) | | `dateFrom` | string | - | Start date in YYYY-MM-DD format | | `dateTo` | string | - | End date in YYYY-MM-DD format | | `proxyConfiguration` | object | - | Optional proxy settings | #### Example Input ```json { "searchQueries": ["monarch butterfly", "red-tailed hawk"], "maxListings": 50, "qualityGrade": "research", "scrapeDetails": false, "placeId": 1, "dateFrom": "2024-01-01", "dateTo": "2024-12-31" } ```` ### Output Each observation includes: | Field | Description | |-------|-------------| | `id` | iNaturalist observation ID | | `speciesGuess` | Observer's species guess | | `scientificName` | Scientific (Latin) name | | `commonName` | Common English name | | `taxonRank` | Taxonomic rank (species, genus, family, etc.) | | `taxonId` | iNaturalist taxon ID | | `iconicTaxonName` | Broad category (Aves, Insecta, Plantae, etc.) | | `observedOn` | Date the observation was made | | `timeObservedAt` | Full timestamp if available | | `latitude` | GPS latitude coordinate | | `longitude` | GPS longitude coordinate | | `placeGuess` | Human-readable location description | | `qualityGrade` | Quality: research, needs\_id, or casual | | `numIdentificationAgreements` | Number of community ID agreements | | `numIdentificationDisagreements` | Number of community ID disagreements | | `photos` | Array of photo URLs (medium size) | | `photoCount` | Number of photos | | `observerLogin` | Observer's iNaturalist username | | `observerName` | Observer's display name | | `description` | Observer's notes | | `license` | Creative Commons license code | | `url` | Direct link to the observation | | `searchQuery` | The query that found this observation | | `scrapedAt` | ISO timestamp of when data was scraped | #### With `scrapeDetails: true`, additional fields: | Field | Description | |-------|-------------| | `identifications` | Array of all IDs with taxon, user, and category | | `identificationCount` | Number of identifications | | `comments` | Array of comments with user and text | | `commentCount` | Number of comments | | `annotations` | Observation annotations (life stage, sex, etc.) | | `observationFieldValues` | Custom observation field values | | `faves_count` | Number of favorites | | `captive` | Whether the organism was captive/cultivated | | `positionalAccuracy` | GPS accuracy in meters | #### Example Output ```json { "id": 123456789, "speciesGuess": "Monarch", "scientificName": "Danaus plexippus", "commonName": "Monarch", "taxonRank": "species", "taxonId": 48662, "iconicTaxonName": "Insecta", "observedOn": "2024-09-15", "latitude": 38.5816, "longitude": -121.4944, "placeGuess": "Sacramento, CA, US", "qualityGrade": "research", "numIdentificationAgreements": 3, "numIdentificationDisagreements": 0, "photos": [ "https://inaturalist-open-data.s3.amazonaws.com/photos/123/medium.jpg" ], "photoCount": 1, "observerLogin": "naturalist42", "observerName": "Jane Smith", "url": "https://www.inaturalist.org/observations/123456789", "searchQuery": "monarch butterfly", "scrapedAt": "2025-01-15T10:30:00.000Z" } ``` ### Quality Grades Explained - **Research Grade**: Community-verified observations. At least 2/3 of identifiers agree on species. Most reliable data. - **Needs ID**: Observations awaiting community identification. May be correct but unverified. - **Casual**: Missing evidence (no photo), location, or date. Or marked as captive/cultivated. ### Common Place IDs | Place | ID | |-------|-----| | United States | 1 | | Canada | 6712 | | Mexico | 6793 | | United Kingdom | 6857 | | Australia | 6744 | | California | 14 | | Texas | 18 | | New York | 48 | | Yellowstone NP | 97395 | | Yosemite NP | 97394 | Find more place IDs by searching at [inaturalist.org/places](https://www.inaturalist.org/places). ### Tips - Use **scientific names** for the most precise results (e.g. "Danaus plexippus" instead of "monarch") - **Research grade** observations have the highest data quality and are used in scientific research - The scraper automatically resolves common names to taxon IDs for better accuracy - Set `maxListings` conservatively to stay within rate limits on large searches - Use `placeId` to focus on specific regions and reduce result volume - Enable `scrapeDetails` only when you need identification history -- it doubles API calls ### Cost This scraper uses Pay Per Event pricing. You are charged $0.005 per observation scraped. With `scrapeDetails: true`, the cost is the same per observation but runs slower due to additional API calls. ### Data Source All data comes from [iNaturalist](https://www.inaturalist.org/), a joint initiative of the California Academy of Sciences and the National Geographic Society. Data is contributed by citizen scientists worldwide and is available under various Creative Commons licenses. # Actor input Schema ## `searchQueries` (type: `array`): Species or taxa to search for (e.g. "monarch butterfly", "red-tailed hawk", "Quercus alba"). Each query runs a separate search. ## `maxListings` (type: `integer`): Maximum number of observations to return per search query (1-10000). ## `qualityGrade` (type: `string`): Filter by observation quality. 'research' = community-verified, 'needs\_id' = awaiting identification, 'casual' = incomplete data. ## `scrapeDetails` (type: `boolean`): Fetch full observation details including all identifications, comments, and additional metadata. Slower but more data. ## `placeId` (type: `integer`): iNaturalist place ID to filter by location (e.g. 1 = United States, 6712 = California, 97394 = Yosemite). Find IDs at inaturalist.org/places. ## `dateFrom` (type: `string`): Filter observations from this date (YYYY-MM-DD format, e.g. 2024-01-01). ## `dateTo` (type: `string`): Filter observations up to this date (YYYY-MM-DD format, e.g. 2024-12-31). ## `proxyConfiguration` (type: `object`): Optional proxy configuration for requests. ## Actor input object example ```json { "searchQueries": [ "monarch butterfly" ], "maxListings": 100, "qualityGrade": "research", "scrapeDetails": false } ``` # 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 = { "searchQueries": [ "monarch butterfly" ] }; // Run the Actor and wait for it to finish const run = await client.actor("lulzasaur/inaturalist-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 = { "searchQueries": ["monarch butterfly"] } # Run the Actor and wait for it to finish run = client.actor("lulzasaur/inaturalist-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 '{ "searchQueries": [ "monarch butterfly" ] }' | apify call lulzasaur/inaturalist-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lulzasaur/inaturalist-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "iNaturalist Scraper - Nature Observations & Species Data", "description": "Scrape nature observations from iNaturalist. Search species, filter by quality grade and location. Get photos, GPS coordinates, identifications, and observer data from citizen science records.", "version": "1.0", "x-build-id": "Mc2znRda9XM2NVOCs" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lulzasaur~inaturalist-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lulzasaur-inaturalist-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/lulzasaur~inaturalist-scraper/runs": { "post": { "operationId": "runs-sync-lulzasaur-inaturalist-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/lulzasaur~inaturalist-scraper/run-sync": { "post": { "operationId": "run-sync-lulzasaur-inaturalist-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", "properties": { "searchQueries": { "title": "Search Queries", "type": "array", "description": "Species or taxa to search for (e.g. \"monarch butterfly\", \"red-tailed hawk\", \"Quercus alba\"). Each query runs a separate search.", "default": [ "monarch butterfly" ], "items": { "type": "string" } }, "maxListings": { "title": "Max Observations", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of observations to return per search query (1-10000).", "default": 100 }, "qualityGrade": { "title": "Quality Grade", "enum": [ "research", "needs_id", "casual", "any" ], "type": "string", "description": "Filter by observation quality. 'research' = community-verified, 'needs_id' = awaiting identification, 'casual' = incomplete data.", "default": "research" }, "scrapeDetails": { "title": "Scrape Full Details", "type": "boolean", "description": "Fetch full observation details including all identifications, comments, and additional metadata. Slower but more data.", "default": false }, "placeId": { "title": "Place ID", "minimum": 1, "type": "integer", "description": "iNaturalist place ID to filter by location (e.g. 1 = United States, 6712 = California, 97394 = Yosemite). Find IDs at inaturalist.org/places." }, "dateFrom": { "title": "Date From", "type": "string", "description": "Filter observations from this date (YYYY-MM-DD format, e.g. 2024-01-01)." }, "dateTo": { "title": "Date To", "type": "string", "description": "Filter observations up to this date (YYYY-MM-DD format, e.g. 2024-12-31)." }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Optional proxy configuration for requests." } } }, "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 } } } } } } } } } } ```