# iNaturalist Observations Scraper (`automation-lab/inaturalist-observations-scraper`) Actor Export public iNaturalist observations by taxon, place, project, date, bounding box, or radius for research, GIS, and reports. - **URL**: https://apify.com/automation-lab/inaturalist-observations-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 Observations Scraper Export public biodiversity observations from iNaturalist into a clean Apify dataset. Use this actor to collect species occurrence records, coordinates, observation URLs, taxonomy, observer metadata, licenses, and photo URLs from the public iNaturalist observations API. It is built for recurring research, consulting, conservation, GIS, and reporting workflows. ### What does iNaturalist Observations Scraper do? The actor queries `api.inaturalist.org/v1/observations` and saves matching observations as structured rows. You can filter by taxon, place, project, observer, quality grade, date range, bounding box, or radius. The output is ready for CSV, JSON, Excel, BI tools, GIS tools, and automated pipelines. Each row represents one public iNaturalist observation. ### Who is it for? Environmental consultants use it to export species occurrence evidence for reports. Biodiversity researchers use it to build repeatable study datasets. Conservation NGOs use it to monitor activity in project areas. GIS analysts use it to pull latitude and longitude fields without custom API code. Data teams use it when they need scheduled exports from iNaturalist. Citizen-science coordinators use it to review observations in campaigns and projects. ### Why use this actor? You do not need to write pagination code. You do not need to normalize nested iNaturalist JSON. You get stable Apify datasets, API access, scheduling, webhooks, and integrations. You can run the same export repeatedly and compare changes over time. You can download results in CSV, JSON, XML, RSS, or Excel from Apify. ### Common workflows Monitor observations in a habitat restoration area. Export all recent records for a target species. Download project observations for a grant report. Build a GIS layer for research-grade observations. Track new observations from a known iNaturalist user. Collect licensed photo URLs and observation links for review. ### Input overview The actor accepts simple filters that map to the official observations API. Set only the fields you need. Leave optional filters empty for broader exports. Keep `maxItems` low for quick tests. Increase `maxItems` for scheduled production runs. ### Main filters `searchQuery` performs a text search. `taxonId` filters by a numeric iNaturalist taxon ID. `placeId` filters by a numeric iNaturalist place ID. `projectId` filters by an iNaturalist project ID or slug. `userId` filters by an iNaturalist observer username. `qualityGrade` can be `research`, `needs_id`, `casual`, or `any`. ### Date filters Use `dateFrom` for the earliest observed date. Use `dateTo` for the latest observed date. Dates should use `YYYY-MM-DD` format. These filters are useful for monthly or quarterly monitoring exports. ### Location filters Use `placeId` for standard iNaturalist places. Use `nelat`, `nelng`, `swlat`, and `swlng` for a bounding box. Use `lat`, `lng`, and `radiusKm` for a radius search. Bounding-box fields must be supplied together. Radius fields must be supplied together. ### Output data The actor saves one row per observation. Important fields include observation ID, URL, observed date, quality grade, species guess, scientific name, common name, coordinates, observer login, license code, photo count, photo URLs, project IDs, and scrape timestamp. The dataset includes GIS-friendly latitude and longitude fields. The dataset includes source URLs so users can verify records on iNaturalist. ### Output table | Field | Description | | --- | --- | | `observationId` | iNaturalist observation ID | | `url` | Public observation URL | | `observedOn` | Date observed | | `qualityGrade` | iNaturalist quality grade | | `speciesGuess` | Display species guess | | `taxonName` | Scientific name | | `taxonPreferredCommonName` | Preferred common name | | `latitude` | Public latitude when available | | `longitude` | Public longitude when available | | `observerLogin` | Observer username | | `licenseCode` | Observation license | | `photoUrls` | Optional large photo URLs | ### Example input: species export ```json { "taxonId": 48662, "placeId": 1, "qualityGrade": "research", "dateFrom": "2024-01-01", "maxItems": 100, "includePhotos": true } ```` This exports research-grade monarch butterfly observations in the United States. ### Example input: GIS area monitoring ```json { "searchQuery": "oak", "qualityGrade": "research", "nelat": 38.1, "nelng": -121.7, "swlat": 37.2, "swlng": -122.6, "dateFrom": "2024-01-01", "maxItems": 250, "includePhotos": false } ``` This exports research-grade oak observations within a bounding box. ### How much does it cost to scrape iNaturalist observations? This actor uses pay-per-event pricing. There is a small start charge for each run. There is a per-observation charge for each saved dataset row. Current BRONZE pricing is $0.005 per run plus $0.000021994 per saved observation, with lower per-observation prices on higher Apify tiers. The exact live price is shown on the Apify actor page before you run it. Use a small `maxItems` value for testing. Use larger values for recurring production exports. ### How to run the actor Open the actor on Apify. Choose your filters. Set `maxItems`. Start the run. Open the Dataset tab when the run finishes. Download CSV, JSON, Excel, or connect the dataset to your pipeline. ### Tips for better results Use numeric iNaturalist IDs when possible. Use `qualityGrade: research` when you need verified records. Use `qualityGrade: any` when you need broader coverage. Use date windows for scheduled monitoring. Use `includePhotos: false` when you only need GIS fields. Use bounding boxes carefully so they match your survey area. ### Integrations Send completed datasets to Google Sheets with Apify integrations. Trigger webhooks after each scheduled monitoring run. Load CSV exports into ArcGIS, QGIS, or BI tools. Use the Apify API to run exports from Python, Node.js, or workflow tools. Archive monthly snapshots for trend analysis. ### API usage with Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/inaturalist-observations-scraper').call({ taxonId: 48662, placeId: 1, qualityGrade: 'research', maxItems: 100 }); console.log(run.defaultDatasetId); ``` ### API usage with Python ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('automation-lab/inaturalist-observations-scraper').call(run_input={ 'taxonId': 48662, 'placeId': 1, 'qualityGrade': 'research', 'maxItems': 100, }) print(run['defaultDatasetId']) ``` ### API usage with cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/automation-lab~inaturalist-observations-scraper/runs?token=YOUR_APIFY_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"taxonId":48662,"placeId":1,"qualityGrade":"research","maxItems":100}' ``` ### MCP usage Use Apify MCP to call this actor from AI tools. Claude Code example: ```bash claude mcp add apify https://mcp.apify.com/?tools=automation-lab/inaturalist-observations-scraper ``` Claude Desktop can use the same MCP URL in its MCP server configuration. ```json { "mcpServers": { "apify": { "url": "https://mcp.apify.com/?tools=automation-lab/inaturalist-observations-scraper" } } } ``` Example prompt: "Run the iNaturalist Observations Scraper for research-grade monarch observations in the United States and summarize the top states from the dataset." ### Data freshness The actor reads live public iNaturalist API results during each run. Freshness depends on iNaturalist API indexing and availability. For monitoring, schedule daily, weekly, or monthly runs on Apify. ### Limitations The actor exports public API data only. Private or obscured coordinates may be unavailable or generalized. Very broad searches can return many more records than your `maxItems` limit. The actor does not identify species; it exports iNaturalist's existing fields. API availability and rate limits are controlled by iNaturalist. ### Legality and responsible use This actor uses public iNaturalist API data. Respect iNaturalist terms, licenses, and community guidelines. Check observation license fields before reusing media or records. Comply with privacy, conservation, and endangered-species handling requirements in your jurisdiction. Do not use public biodiversity data to harm species, habitats, or private individuals. ### Troubleshooting If you get no results, broaden filters or set `qualityGrade` to `any`. If bounding-box validation fails, provide all four bounding-box fields. If radius validation fails, provide `lat`, `lng`, and `radiusKm` together. If a project search is empty, verify the project ID or slug on iNaturalist. If photo arrays are not needed, turn off `includePhotos` to reduce output size. ### FAQ #### Does this actor need an iNaturalist account? No. It uses public observations API endpoints. #### Can I export research-grade observations only? Yes. Set `qualityGrade` to `research`. #### Can I export by species? Yes. Use the iNaturalist `taxonId` for the species or broader taxon. #### Can I use the output in GIS tools? Yes. Export CSV or JSON and use the `latitude` and `longitude` columns. #### Are photo URLs included? Yes, when `includePhotos` is enabled. ### Related scrapers Explore related Automation Lab actors for public data, maps, locations, and research workflows: - https://apify.com/automation-lab/google-maps-search-scraper - https://apify.com/automation-lab/website-contact-finder - https://apify.com/automation-lab/rss-feed-scraper ### Support If a run fails, open the run log first. Check the exact input used for the run. Try a smaller `maxItems` value. Share the run URL when reporting an issue. ### Changelog See `.actor/CHANGELOG.md` for release notes. # Actor input Schema ## `maxItems` (type: `integer`): Maximum number of public iNaturalist observations to save to the dataset. ## `searchQuery` (type: `string`): Optional full-text search query passed as q to the iNaturalist observations API, for example a species/common name or place phrase. ## `taxonId` (type: `integer`): Optional iNaturalist taxon\_id. Example: 48662 for monarch butterfly. ## `placeId` (type: `integer`): Optional iNaturalist place\_id. Example: 1 for United States. ## `projectId` (type: `string`): Optional iNaturalist project ID or slug to restrict observations to a project. ## `userId` (type: `string`): Optional iNaturalist username to export observations from one observer. ## `qualityGrade` (type: `string`): Filter by iNaturalist quality grade. Choose any to leave quality\_grade unset. ## `dateFrom` (type: `string`): Earliest observed date in YYYY-MM-DD format. ## `dateTo` (type: `string`): Latest observed date in YYYY-MM-DD format. ## `nelat` (type: `number`): Optional bounding-box northeast latitude. Use together with nelng, swlat, and swlng. ## `nelng` (type: `number`): Optional bounding-box northeast longitude. ## `swlat` (type: `number`): Optional bounding-box southwest latitude. ## `swlng` (type: `number`): Optional bounding-box southwest longitude. ## `lat` (type: `number`): Optional radius-search center latitude. Use together with lng and radiusKm. ## `lng` (type: `number`): Optional radius-search center longitude. Use together with lat and radiusKm. ## `radiusKm` (type: `number`): Optional radius in kilometers around lat/lng. ## `includePhotos` (type: `boolean`): When enabled, output includes an array of normalized large photo URLs for each observation. ## `sort` (type: `string`): Sort field accepted by the iNaturalist observations API. ## `order` (type: `string`): Sort newest/highest first or oldest/lowest first. ## Actor input object example ```json { "maxItems": 20, "searchQuery": "monarch butterfly", "taxonId": 48662, "placeId": 1, "qualityGrade": "research", "dateFrom": "2024-01-01", "includePhotos": true, "sort": "observed_on", "order": "desc" } ``` # Actor output Schema ## `overview` (type: `string`): No description # 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 = { "maxItems": 20, "searchQuery": "monarch butterfly", "taxonId": 48662, "placeId": 1, "qualityGrade": "research", "dateFrom": "2024-01-01", "includePhotos": true, "sort": "observed_on", "order": "desc" }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/inaturalist-observations-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 = { "maxItems": 20, "searchQuery": "monarch butterfly", "taxonId": 48662, "placeId": 1, "qualityGrade": "research", "dateFrom": "2024-01-01", "includePhotos": True, "sort": "observed_on", "order": "desc", } # Run the Actor and wait for it to finish run = client.actor("automation-lab/inaturalist-observations-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 '{ "maxItems": 20, "searchQuery": "monarch butterfly", "taxonId": 48662, "placeId": 1, "qualityGrade": "research", "dateFrom": "2024-01-01", "includePhotos": true, "sort": "observed_on", "order": "desc" }' | apify call automation-lab/inaturalist-observations-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/inaturalist-observations-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "iNaturalist Observations Scraper", "description": "Export public iNaturalist observations by taxon, place, project, date, bounding box, or radius for research, GIS, and reports.", "version": "0.1", "x-build-id": "nD9PViGR6fiumk5nU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~inaturalist-observations-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-inaturalist-observations-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/automation-lab~inaturalist-observations-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-inaturalist-observations-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/automation-lab~inaturalist-observations-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-inaturalist-observations-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": { "maxItems": { "title": "Maximum observations", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of public iNaturalist observations to save to the dataset.", "default": 20 }, "searchQuery": { "title": "Search text", "type": "string", "description": "Optional full-text search query passed as q to the iNaturalist observations API, for example a species/common name or place phrase." }, "taxonId": { "title": "Taxon ID", "minimum": 1, "type": "integer", "description": "Optional iNaturalist taxon_id. Example: 48662 for monarch butterfly." }, "placeId": { "title": "Place ID", "minimum": 1, "type": "integer", "description": "Optional iNaturalist place_id. Example: 1 for United States." }, "projectId": { "title": "Project ID or slug", "type": "string", "description": "Optional iNaturalist project ID or slug to restrict observations to a project." }, "userId": { "title": "Observer username", "type": "string", "description": "Optional iNaturalist username to export observations from one observer." }, "qualityGrade": { "title": "Quality grade", "enum": [ "any", "research", "needs_id", "casual" ], "type": "string", "description": "Filter by iNaturalist quality grade. Choose any to leave quality_grade unset.", "default": "research" }, "dateFrom": { "title": "Observed from", "type": "string", "description": "Earliest observed date in YYYY-MM-DD format." }, "dateTo": { "title": "Observed until", "type": "string", "description": "Latest observed date in YYYY-MM-DD format." }, "nelat": { "title": "Bounding box northeast latitude", "type": "number", "description": "Optional bounding-box northeast latitude. Use together with nelng, swlat, and swlng." }, "nelng": { "title": "Bounding box northeast longitude", "type": "number", "description": "Optional bounding-box northeast longitude." }, "swlat": { "title": "Bounding box southwest latitude", "type": "number", "description": "Optional bounding-box southwest latitude." }, "swlng": { "title": "Bounding box southwest longitude", "type": "number", "description": "Optional bounding-box southwest longitude." }, "lat": { "title": "Radius center latitude", "type": "number", "description": "Optional radius-search center latitude. Use together with lng and radiusKm." }, "lng": { "title": "Radius center longitude", "type": "number", "description": "Optional radius-search center longitude. Use together with lat and radiusKm." }, "radiusKm": { "title": "Radius in kilometers", "minimum": 0.1, "maximum": 1000, "type": "number", "description": "Optional radius in kilometers around lat/lng." }, "includePhotos": { "title": "Include photo URLs", "type": "boolean", "description": "When enabled, output includes an array of normalized large photo URLs for each observation.", "default": true }, "sort": { "title": "Sort by", "enum": [ "observed_on", "created_at", "species_guess", "votes", "id" ], "type": "string", "description": "Sort field accepted by the iNaturalist observations API.", "default": "observed_on" }, "order": { "title": "Sort direction", "enum": [ "desc", "asc" ], "type": "string", "description": "Sort newest/highest first or oldest/lowest first.", "default": "desc" } } }, "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 } } } } } } } } } } ```