# Unsplash Image Scraper (`maximedupre/unsplash-image-scraper`) Actor Scrape Unsplash image search results by keyword. Export image URLs, source ranks, query metadata, and scrape timestamps for design, SEO, and content research. - **URL**: https://apify.com/maximedupre/unsplash-image-scraper.md - **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community) - **Categories:** Developer tools, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $2.65 / 1,000 unsplash images 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 ### 🖼️ Unsplash image scraper for keyword searches Unsplash Image Scraper collects image results from [Unsplash](https://unsplash.com/) search pages. Enter one or more keywords such as `nature`, `coffee shop`, or `minimal workspace`, then export image URLs, source rank, query metadata, and scrape timestamps from a clean Apify dataset. Use this Unsplash image scraper when you need a repeatable way to collect image search results for design research, creative briefs, mood boards, SEO image research, content planning, or internal data workflows. You can run it in Apify Console, schedule repeat runs, call it from the Apify API, and export the dataset as JSON, CSV, Excel, XML, RSS, or HTML. The Actor is built for public Unsplash search results. It does not download binary image files, generate images, enrich photographer contacts, or combine Unsplash with other image sources. ### ✅ What this Actor does - Searches Unsplash by one or more keywords. - Saves one dataset item per discovered image result. - Keeps the original search query and rank on every item. - Returns common image URL variants: raw, full, regular, small, and thumb. - Supports Unsplash search sorting by relevance or latest. - Supports orientation and color filters when Unsplash returns matching search results. - Adds source URL and scrape time fields for traceable exports. - Stops at your per-query and total image limits. Some fields are nullable because Unsplash search HTML does not expose every piece of photo metadata on every result. When a value is not available from the public search result, the Actor keeps the field as `null` or an empty array instead of inventing data. ### 📦 Data you can extract Each output item represents one Unsplash image result. Fields include: - `query` and `queryIndex` - `rank` - `imageId` - `title`, `description`, and `altDescription` when available - `createdAt` and `updatedAt` when available - `width` and `height` when available - `urls.raw`, `urls.full`, `urls.regular`, `urls.small`, and `urls.thumb` - `links.html`, `links.download`, and `links.downloadLocation` when available - `photographer` identity fields when available - `tags` - `engagement.likes` and `engagement.downloads` when available - `color` and `blurHash` when available - `sourceUrl`, `unsplashUrl`, `downloadLocationUrl`, and `scrapedAt` ### 🚀 How to run 1. Add one or more Unsplash search terms. 2. Keep `Image limit per search` at `25` for a quick first run. 3. Optionally choose sort order, orientation, or color. 4. Run the Actor. 5. Open the dataset or export the results through the Apify API. For a small test, use the prefilled `nature` query. For larger research jobs, add several related search terms and use `Total image limit` to cap the whole run. ### ⚙️ Input ```json { "queries": ["nature", "minimal workspace"], "maxItemsPerQuery": 25, "maxTotalItems": 100, "sortBy": "relevance", "orientation": "any", "color": "any" } ```` #### Search terms Enter plain Unsplash search keywords. Short, visual terms usually work best, for example: - `nature` - `coffee shop` - `minimal workspace` - `SaaS dashboard` - `running shoes` Each query is searched separately. Duplicate and empty values are ignored. #### Limits and filters Use `maxItemsPerQuery` to control how many images can be saved for each keyword. Use `maxTotalItems` when you want a hard cap across the full run. `sortBy` can be `relevance` or `latest`. `orientation` can be `any`, `landscape`, `portrait`, or `squarish`. `color` can be `any` or one of the supported Unsplash color filters. ### 📊 Output example ```json { "query": "nature", "queryIndex": 0, "rank": 1, "imageId": "photo-1470071459604-3b5ec3a7fe05", "title": null, "description": null, "altDescription": null, "createdAt": null, "updatedAt": null, "width": null, "height": null, "urls": { "raw": "https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?auto=format", "full": "https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?auto=format&fit=crop&q=85&w=2000", "regular": "https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?auto=format&fit=crop&q=80&w=1080", "small": "https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?auto=format&fit=crop&q=80&w=400", "thumb": "https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?auto=format&fit=crop&q=80&w=200" }, "links": { "html": null, "download": "https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?auto=format&fit=crop&q=85&w=2000", "downloadLocation": null }, "photographer": { "id": null, "username": null, "name": null, "profileUrl": null, "portfolioUrl": null }, "tags": [], "engagement": { "likes": null, "downloads": null }, "color": null, "blurHash": null, "sourceUrl": "https://unsplash.com/s/photos/nature?page=1&order_by=relevant", "unsplashUrl": null, "downloadLocationUrl": null, "scrapedAt": "2026-05-23T00:00:00.000Z" } ``` ### 💳 Pricing This Actor uses pay-per-event pricing. You pay a small Actor-start charge when a run begins and one image charge for each saved Unsplash image item. Use the input limits to control cost before you start a larger run. If no images are saved, no per-image charge is made. ### ⚠️ Limits and caveats - Results depend on what Unsplash returns for the public search page at run time. - Some metadata fields can be `null` because public search results do not always expose them. - The Actor returns image URLs, not downloaded image files. - It does not provide legal advice about how you may use an image. Review Unsplash and image-owner terms for your use case. - It is not an official Unsplash API client. ### ❓ FAQ #### Does this Actor download image files? No. It returns image URLs in several common sizes. Use those URLs in your own workflow if you need to fetch files separately. #### Do I need an Unsplash API key? No. The Actor is designed for public Unsplash search pages and does not ask for an Unsplash API key, cookies, or login details. #### Why are some fields null? Unsplash search pages expose image assets reliably, but not every detail is present in the public search result. The Actor keeps unavailable fields as `null` or `[]` so exports stay honest and schema-stable. #### Can I schedule repeat image searches? Yes. You can schedule the Actor on Apify and compare datasets over time, subject to the same public search result availability. ### 📝 Changelog - 0.1: Initial release. ### 🆘 Support For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~unsplash-image-scraper/issues) and I'll fix or implement it in less than 24h 🫡 ### 🔗 Other actors - [Google Shopping Ads Scraper ↗](https://apify.com/maximedupre/google-shopping-ads-scraper) - Track paid product ads, prices, merchants, and landing pages from Google Search. - [Website Emails Scraper ↗](https://apify.com/maximedupre/website-emails-scraper) - Find public contact emails from the websites you already care about. - [Business Address Scraper ↗](https://apify.com/maximedupre/business-address-scraper) - Extract visible business addresses from company websites. - [Product Hunt Scraper ↗](https://apify.com/maximedupre/product-hunt-scraper) - Collect Product Hunt launches, media, ranks, and startup lead fields. - [YouTube Channel Scraper ↗](https://apify.com/maximedupre/youtube-channel-scraper) - Export public YouTube channel profiles and recent video rows. **Made with ❤️ by Maxime Dupré** # Actor input Schema ## `queries` (type: `array`): Enter one or more Unsplash image searches such as nature, coffee shop, minimal workspace, or SaaS dashboard. Each term is searched separately. ## `maxItemsPerQuery` (type: `integer`): Maximum Unsplash images to save for each search term. Use 25 for a quick first run. ## `maxTotalItems` (type: `integer`): Maximum Unsplash images to save across all search terms. ## `sortBy` (type: `string`): Choose whether Unsplash should return the most relevant images or the latest matching images first. ## `orientation` (type: `string`): Limit images to a specific orientation when Unsplash returns matching search results. ## `color` (type: `string`): Optional Unsplash color filter for brand, mood board, or design research. ## Actor input object example ```json { "queries": [ "nature" ], "maxItemsPerQuery": 25, "maxTotalItems": 100, "sortBy": "relevance", "orientation": "any", "color": "any" } ``` # Actor output Schema ## `results` (type: `string`): Open the dataset with Unsplash image URLs, ranks, query metadata, and scrape timestamps. # 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 = { "queries": [ "nature" ] }; // Run the Actor and wait for it to finish const run = await client.actor("maximedupre/unsplash-image-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 = { "queries": ["nature"] } # Run the Actor and wait for it to finish run = client.actor("maximedupre/unsplash-image-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 '{ "queries": [ "nature" ] }' | apify call maximedupre/unsplash-image-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=maximedupre/unsplash-image-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Unsplash Image Scraper", "description": "Scrape Unsplash image search results by keyword. Export image URLs, source ranks, query metadata, and scrape timestamps for design, SEO, and content research.", "version": "0.1", "x-build-id": "Zw6n7O4vQOZDdBwic" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/maximedupre~unsplash-image-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-maximedupre-unsplash-image-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/maximedupre~unsplash-image-scraper/runs": { "post": { "operationId": "runs-sync-maximedupre-unsplash-image-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/maximedupre~unsplash-image-scraper/run-sync": { "post": { "operationId": "run-sync-maximedupre-unsplash-image-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": [ "queries" ], "properties": { "queries": { "title": "Search terms", "type": "array", "description": "Enter one or more Unsplash image searches such as nature, coffee shop, minimal workspace, or SaaS dashboard. Each term is searched separately.", "items": { "type": "string", "minLength": 1 } }, "maxItemsPerQuery": { "title": "Image limit per search", "minimum": 1, "maximum": 200, "type": "integer", "description": "Maximum Unsplash images to save for each search term. Use 25 for a quick first run.", "default": 25 }, "maxTotalItems": { "title": "Total image limit", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum Unsplash images to save across all search terms.", "default": 100 }, "sortBy": { "title": "Sort images by", "enum": [ "relevance", "latest" ], "type": "string", "description": "Choose whether Unsplash should return the most relevant images or the latest matching images first.", "default": "relevance" }, "orientation": { "title": "Orientation", "enum": [ "any", "landscape", "portrait", "squarish" ], "type": "string", "description": "Limit images to a specific orientation when Unsplash returns matching search results.", "default": "any" }, "color": { "title": "Color", "enum": [ "any", "black_and_white", "black", "white", "yellow", "orange", "red", "purple", "magenta", "green", "teal", "blue" ], "type": "string", "description": "Optional Unsplash color filter for brand, mood board, or design research.", "default": "any" } } }, "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 } } } } } } } } } } ```