# Unsplash Image Scraper (`parsebird/unsplash-image-scraper`) Actor
Scrape Unsplash images by keyword with orientation, color, and sort filters. Extract image URLs, photographer info, tags, and metadata. No API key needed. Export as JSON, CSV, Excel.
- **URL**: https://apify.com/parsebird/unsplash-image-scraper.md
- **Developed by:** [ParseBird](https://apify.com/parsebird) (community)
- **Categories:** Social media, Videos, Automation
- **Features:** Limited permissions
- **Stats:** 102 total users, 33 monthly users, 79.9% runs succeeded, 2 bookmarks
- **User rating**: No ratings yet
## Pricing
from $2.00 / 1,000 image scrapeds
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/actors/running/actors-in-store.md#pay-per-event
## What's an Apify Actor?
An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.
Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.
## 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.
Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.
For examples already wired to this Actor's own input schema, see the [API](#api) section below.
Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).
# README
### Unsplash Image Scraper
Extract high-quality image data from [Unsplash](https://unsplash.com/) — the internet's largest source of freely-usable photos, with over 5 million images contributed by a global community of photographers.
Search multiple keywords at once — get structured image data with URLs in 5 resolutions, photographer attribution, tags, and engagement metrics ready for download or integration.
##### Copy to your AI assistant
Copy this block into ChatGPT, Claude, Cursor, or any LLM to start using this actor.
```
parsebird/unsplash-image-scraper on Apify. Call: ApifyClient("TOKEN").actor("parsebird/unsplash-image-scraper").call(run_input={...}), then client.dataset(run["defaultDatasetId"]).list_items().items for results. Key inputs: queries (array of strings, e.g. ["nature", "coffee shop"]), maxItemsPerQuery (integer, default 20), maxTotalItems (integer, default 100). Output fields: imageId, title, description, altDescription, urls (raw/full/regular/small/thumb), photographer (name/username/profileUrl), tags, engagement (likes), color, blurHash, sourceUrl, unsplashUrl. Full actor spec: fetch via GET https://api.apify.com/v2/acts/parsebird~unsplash-image-scraper (Bearer TOKEN). Get token: https://console.apify.com/account/integrations
```
### What is Unsplash Image Scraper?
**Unsplash Image Scraper** extracts structured image data from [Unsplash](https://unsplash.com/) search results. It collects image URLs in multiple resolutions, photographer attribution, descriptions, tags, dimensions, and engagement metrics — all without requiring an Unsplash API key.
Use it as an **Unsplash API alternative** to get image data in JSON, CSV, or Excel. No coding required — enter your search terms, set your filters, click Start, and download the results. Or integrate via the [Apify API](https://docs.apify.com/api/v2) to automate image data collection for your workflows.
### What can Unsplash Image Scraper do?
- 🔍 **Search by keyword** — enter one or more search terms like "nature", "coffee shop", "minimal workspace", or "SaaS dashboard"
- 🖼️ **Five image resolutions** — get URLs for raw, full (2000px), regular (1080px), small (400px), and thumbnail (200px) versions
- 👤 **Photographer data** — collect name, username, profile URL, and portfolio link for attribution
- 🏷️ **Tags and metadata** — extract image tags, dimensions, alt descriptions, and blur hashes
- 🔄 **Schedule recurring runs** — monitor new uploads and build image datasets over time with [Apify scheduling](https://docs.apify.com/platform/schedules)
- 🔗 **API access and integrations** — connect to Google Sheets, Zapier, Make, webhooks, or any workflow via the [Apify API](https://docs.apify.com/api/v2)
### What data can you extract from Unsplash?
| Field | Description |
|-------|-------------|
| `imageId` | Unique Unsplash photo identifier |
| `title` / `description` | Photo title and description set by the photographer |
| `altDescription` | Machine-generated alt text for the image |
| `urls.raw` | Original unprocessed image URL |
| `urls.full` | High-quality JPEG (2000px width) |
| `urls.regular` | Standard JPEG (1080px width) |
| `urls.small` | Small JPEG (400px width) |
| `urls.thumb` | Thumbnail JPEG (200px width) |
| `photographer.name` | Photographer's display name |
| `photographer.username` | Unsplash username |
| `photographer.profileUrl` | Link to the photographer's Unsplash profile |
| `photographer.portfolioUrl` | External portfolio link |
| `tags` | Array of image tags |
| `engagement.likes` | Number of likes on Unsplash |
| `color` | Dominant hex color of the image |
| `blurHash` | BlurHash placeholder string |
| `width` / `height` | Image dimensions in pixels |
| `createdAt` / `updatedAt` | Upload and last update timestamps |
| `unsplashUrl` | Direct link to the photo on Unsplash |
### How to scrape Unsplash images
1. Go to the [Unsplash Image Scraper](https://apify.com/parsebird/unsplash-image-scraper) page on Apify Store
2. Click **Try for free** to open the Actor console
3. Enter one or more **search queries** (e.g. nature, coffee shop, minimal workspace)
4. Set **Max Images per Query** to control how many images to collect per search term (default: 20)
5. Click **Start** and wait for the run to finish
6. Download your data in **JSON, CSV, Excel**, or connect via the **Apify API**
#### Python API example
```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("parsebird/unsplash-image-scraper").call(run_input={
"queries": ["nature", "coffee shop"],
"maxItemsPerQuery": 20,
"maxTotalItems": 50,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(f"{item['imageId']} — {item['photographer']['name']} — {item['urls']['regular']}")
```
#### JavaScript API example
```javascript
import { ApifyClient } from "apify-client";
const client = new ApifyClient({ token: "YOUR_API_TOKEN" });
const run = await client.actor("parsebird/unsplash-image-scraper").call({
queries: ["nature", "coffee shop"],
maxItemsPerQuery: 20,
maxTotalItems: 50,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.log(`${item.imageId} — ${item.photographer.name} — ${item.urls.regular}`);
});
```
### Input parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `queries` | array | **Yes** | — | Search terms (e.g. `["nature", "coffee shop"]`). Each term runs as a separate search. |
| `maxItemsPerQuery` | integer | No | `20` | Maximum images to collect per search term |
| `maxTotalItems` | integer | No | `100` | Maximum images to collect across all search terms |
| `proxyConfiguration` | object | No | Apify Proxy | Proxy settings for the scraper |
### Output example
```json
{
"query": "nature",
"queryIndex": 0,
"rank": 1,
"imageId": "cssvEZacHvQ",
"title": null,
"description": null,
"altDescription": "gray concrete bridge and waterfalls during daytime",
"createdAt": null,
"updatedAt": null,
"width": null,
"height": null,
"urls": {
"raw": "https://images.unsplash.com/photo-1433086966358-54859d0ed716?auto=format",
"full": "https://images.unsplash.com/photo-1433086966358-54859d0ed716?auto=format&fit=crop&q=85&w=2000",
"regular": "https://images.unsplash.com/photo-1433086966358-54859d0ed716?auto=format&fit=crop&q=80&w=1080",
"small": "https://images.unsplash.com/photo-1433086966358-54859d0ed716?auto=format&fit=crop&q=80&w=400",
"thumb": "https://images.unsplash.com/photo-1433086966358-54859d0ed716?auto=format&fit=crop&q=80&w=200"
},
"links": {
"html": "https://unsplash.com/photos/gray-concrete-bridge-and-waterfalls-during-daytime-cssvEZacHvQ",
"download": "https://images.unsplash.com/photo-1433086966358-54859d0ed716?auto=format&fit=crop&q=85&w=2000",
"downloadLocation": null
},
"photographer": {
"id": null,
"username": "blakeverdoorn",
"name": null,
"profileUrl": "https://unsplash.com/@blakeverdoorn",
"portfolioUrl": null
},
"tags": [],
"engagement": {
"likes": null,
"downloads": null
},
"color": null,
"blurHash": null,
"sourceUrl": "https://unsplash.com/s/photos/nature",
"unsplashUrl": "https://unsplash.com/photos/gray-concrete-bridge-and-waterfalls-during-daytime-cssvEZacHvQ",
"downloadLocationUrl": null,
"scrapedAt": "2026-05-23T02:24:44.000Z"
}
```
Download results in JSON, HTML, CSV, or Excel.
### Use cases
- 🎨 **Design and branding** — Build mood boards, source hero images, and find on-brand visuals by color and orientation
- 📝 **Content creation** — Find high-quality stock photos for blog posts, social media, newsletters, and presentations
- 🤖 **AI and machine learning** — Collect labeled image datasets for training computer vision models, classifiers, or generative AI
- 📊 **Market research** — Analyze visual trends, popular photography styles, and content patterns across categories
- 🖥️ **Web development** — Source placeholder images, populate design prototypes, and generate image galleries programmatically
- 🔄 **Automated pipelines** — Schedule recurring runs to collect fresh images and feed them into content management systems or design tools
### How much does it cost to scrape Unsplash?
| Event | Price per event | Price per 1,000 |
|-------|----------------|-----------------|
| `image-scraped` | $0.002 | **$2.00** |
One event is charged each time an image is successfully scraped and saved to the dataset. You only pay for images actually returned.
**Cost examples:**
| Images | Cost |
|--------|------|
| 20 (default run) | $0.04 |
| 100 | $0.20 |
| 1,000 | $2.00 |
| 10,000 | $20.00 |
Apify offers a **free trial** with $5 of platform credits — enough to scrape ~2,500 Unsplash images at no cost.
### How it works
1. Accepts your search queries and limit settings
2. For each query, requests Unsplash's own search results data directly (no browser needed)
3. Passes Unsplash's automated bot check once per run, then reuses that session for every query and page
4. Maps each photo to a clean output schema with URLs, photographer info, and metadata
5. Paginates through results until the per-query or total limit is reached
6. Pushes all results to the Apify dataset for download or API access
### FAQ
**What search terms can I use?**
Any keyword or phrase that works on [unsplash.com](https://unsplash.com/) — single words like "mountain" or "coffee", multi-word phrases like "minimal workspace" or "SaaS dashboard", and category terms like "architecture" or "food photography".
**Can I search for multiple topics in one run?**
Yes. Add multiple search terms to the `queries` array. Each term is searched separately, and you can control both the per-query limit and the total limit across all queries.
**Why are some fields null in the output?**
Unsplash's public search results do not always expose every metadata field. Fields like `title`, `description`, `downloads`, and `downloadLocation` may be `null` depending on what the photographer provided and what Unsplash returns for that search. The image URLs, photographer info, and core metadata are reliably present.
**Does this scraper download the actual image files?**
No. The scraper returns image URLs in five resolutions (raw, full, regular, small, thumb). You can download the images yourself using the URLs provided, or use them directly in your application.
**Is this an official Unsplash API client?**
No. This Actor scrapes publicly available data from Unsplash's search functionality. It is not affiliated with or endorsed by Unsplash Inc. For official API access, see the [Unsplash API documentation](https://unsplash.com/documentation).
**Can I schedule recurring scrapes?**
Yes. Use [Apify scheduling](https://docs.apify.com/platform/schedules) to run daily, weekly, or at any custom interval. Combine with [webhooks](https://docs.apify.com/platform/integrations/webhooks) or [integrations](https://docs.apify.com/platform/integrations) to automate your image data pipeline.
**Can I access the data via API?**
Yes. Every run produces a dataset accessible via the [Apify API](https://docs.apify.com/api/v2). Integrate with Python, JavaScript, Google Sheets, Zapier, Make, or any HTTP-capable tool.
**What are the result limits?**
Results depend on what Unsplash returns for the public search at run time. The number of available images varies by search term and filter combination. Very specific or niche queries may return fewer results.
### Is it legal to scrape Unsplash?
This Actor extracts publicly available data from [Unsplash](https://unsplash.com/). Scraping public data is generally considered legal based on recent court rulings, including the US Ninth Circuit's decision in *hiQ Labs v. LinkedIn*. However, this Actor does not provide legal advice about how you may use the images or data. Users are responsible for reviewing the [Unsplash License](https://unsplash.com/license) and individual image-owner terms for their specific use case. Do not use extracted data for purposes incompatible with applicable terms of service. For more information, read Apify's blog post on [web scraping legality](https://blog.apify.com/is-web-scraping-legal/).
### Other ParseBird scrapers
| Actor | Description |
|-------|-------------|
| [Unsplash Image Scraper](https://apify.com/parsebird/unsplash-image-scraper) | Search and extract Unsplash image data |
| [Dribbble Designers Scraper](https://apify.com/parsebird/dribbble-designers-scraper) | Extract designer profiles from Dribbble |
| [Framer Templates Scraper](https://apify.com/parsebird/framer-templates-scraper) | Scrape Framer template listings |
| [YouTube Thumbnail Downloader](https://apify.com/parsebird/youtube-thumbnail-downloader) | Download YouTube video thumbnails |
| [HTTP Request Actor](https://apify.com/parsebird/http-request-actor) | Send custom HTTP requests from the cloud |
Browse all ParseBird actors on the [Apify Store](https://apify.com/parsebird).
# Changelog
This Actor's version history is a separate document: https://apify.com/parsebird/unsplash-image-scraper/changelog.md
# Actor input Schema
## `queries` (type: `array`):
Add one or more search terms such as nature, coffee shop, minimal workspace, or SaaS dashboard. Each term runs as a separate Unsplash search.
## `maxItemsPerQuery` (type: `integer`):
Maximum number of images to collect for each search term. Keep this low (e.g. 20) for a quick first run.
## `maxTotalItems` (type: `integer`):
Maximum number of images to collect across all search terms combined.
## `proxyConfiguration` (type: `object`):
Proxy settings for the scraper. Datacenter proxies work well for Unsplash. Switch to residential if you encounter blocks.
## Actor input object example
```json
{
"queries": [
"nature",
"coffee shop"
],
"maxItemsPerQuery": 5,
"maxTotalItems": 5,
"proxyConfiguration": {
"useApifyProxy": true
}
}
```
# Actor output Schema
## `dataset` (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 = {
"queries": [
"nature",
"coffee shop"
],
"maxItemsPerQuery": 5,
"maxTotalItems": 5,
"proxyConfiguration": {
"useApifyProxy": true
}
};
// Run the Actor and wait for it to finish
const run = await client.actor("parsebird/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",
"coffee shop",
],
"maxItemsPerQuery": 5,
"maxTotalItems": 5,
"proxyConfiguration": { "useApifyProxy": True },
}
# Run the Actor and wait for it to finish
run = client.actor("parsebird/unsplash-image-scraper").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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",
"coffee shop"
],
"maxItemsPerQuery": 5,
"maxTotalItems": 5,
"proxyConfiguration": {
"useApifyProxy": true
}
}' |
apify call parsebird/unsplash-image-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com/?tools=fetch-actor-details,parsebird/unsplash-image-scraper"
}
}
}
```
The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).
## OpenAPI specification
Download the OpenAPI definition: https://api.apify.com/v2/actors/gvlv6e7DZValDulwR/builds/PTaKQb01cQ0yw2ZbG/openapi.json