# Unsplash Image Scraper (`shahidirfan/unsplash-image-scraper`) Actor

Scrape high-quality images from Unsplash in bulk. Extract metadata, download entire collections, and automate image research without API limits. Perfect for designers, researchers, and content creators building image libraries at scale.

- **URL**: https://apify.com/shahidirfan/unsplash-image-scraper.md
- **Developed by:** [Shahid Irfan](https://apify.com/shahidirfan) (community)
- **Categories:** Automation, Developer tools, Other
- **Stats:** 22 total users, 5 monthly users, 100.0% runs succeeded, 3 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.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 web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

### What does Unsplash Image Scraper do?

Extract image metadata and download URLs from Unsplash using search keywords, topic feeds, curated collections, or user profile URLs. Collect photo dimensions, color data, descriptions, photographer details, likes, and direct image links from public Unsplash pages. The output is ready for AI training datasets, design asset libraries, marketing research, and stock photo analysis.

### Why use Unsplash Image Scraper?

- **Structured image datasets** - Collect metadata from thousands of photos without manual browsing or copy-paste.
- **Automation-ready output** - Export results to JSON, CSV, Excel, or connect via API to downstream tools.
- **Flexible sourcing** - Pull images from search queries, topic pages, collections, or specific photographer portfolios.
- **Clean data** - Null, empty, and redundant fields are automatically filtered so the dataset is ready to use.

### What data can you extract from Unsplash?

| Field | Description |
|-------|-------------|
| `url` | Direct link to the photo page on Unsplash |
| `image_url` | Regular-sized web-optimized image URL |
| `download_url` | Direct download link for the photo |
| `id` | Unique photo identifier |
| `description` | Photographer-provided or alternate description |
| `width` | Original image width in pixels |
| `height` | Original image height in pixels |
| `color` | Dominant hex color code extracted from the image |
| `likes` | Total likes count on the photo |
| `username` | Photographer's Unsplash username |
| `user_name` | Photographer's full display name |

### How to use Unsplash Image Scraper

1. Open the Actor on Apify Store.
2. Provide a search keyword, an Unsplash URL, or leave the defaults for a sample run.
3. Set the maximum number of images and pages.
4. Run the Actor.
5. Download the dataset or connect it to your workflow via API, webhooks, or integrations.

### Input Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `url` | String | No | - | Unsplash URL (search, topic, collection, or user profile). Overrides the keyword when provided. |
| `keyword` | String | No | `"spring"` | Search term for photos when no URL is given. |
| `results_wanted` | Integer | No | `20` | Maximum number of images to collect. |
| `max_pages` | Integer | No | `5` | Maximum result pages to paginate through. |
| `proxyConfiguration` | Object | No | Apify Proxy (residential) | Proxy settings for reliable extraction at scale. |

### Output Data

| Field | Type | Description |
|-------|------|-------------|
| `id` | String | Unique photo identifier |
| `slug` | String | URL-friendly photo slug |
| `created_at` | String | ISO timestamp of upload |
| `updated_at` | String | ISO timestamp of last update |
| `width` | Integer | Photo width in pixels |
| `height` | Integer | Photo height in pixels |
| `color` | String | Primary hex color of the image |
| `blur_hash` | String | Placeholder blur hash |
| `description` | String | Photo description or alt text |
| `alt_description` | String | Alternate automated description |
| `url` | String | Photo page on Unsplash |
| `image_url` | String | Regular-sized image URL |
| `download_url` | String | Direct download link |
| `likes` | Integer | Total likes received |
| `username` | String | Photographer's Unsplash username |
| `user_name` | String | Photographer's full name |

### Usage Examples

#### Keyword Search

Extract photos using a search term:

```json
{
  "keyword": "nature",
  "results_wanted": 20
}
```

#### Search URL with Higher Volume

Extract 50 images from a specific search page:

```json
{
  "url": "https://unsplash.com/s/photos/spring-flowers",
  "results_wanted": 50,
  "max_pages": 10
}
```

#### Photographer Portfolio

Collect photos from a specific artist or organization:

```json
{
  "url": "https://unsplash.com/@nasa",
  "results_wanted": 30
}
```

#### Curated Collection

Extract images from a themed collection:

```json
{
  "url": "https://unsplash.com/collections/317099/nature",
  "results_wanted": 100
}
```

### Sample Output

```json
{
  "id": "abc123XYZ",
  "slug": "pink-flowers-in-bloom",
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-05-15T08:30:00Z",
  "width": 6000,
  "height": 4000,
  "color": "#f3a5b0",
  "blur_hash": "LhPZ$#~q%MIU?wIUt7WBoffRj[ay",
  "description": "A beautiful close-up of pink cherry blossoms in full bloom during spring.",
  "alt_description": "pink cherry blossoms",
  "url": "https://unsplash.com/photos/pink-flowers-in-bloom",
  "image_url": "https://images.unsplash.com/photo-12345-abcde?w=1080&fit=max",
  "download_url": "https://unsplash.com/photos/abc123XYZ/download",
  "likes": 342,
  "username": "nature_photographer",
  "user_name": "Jane Doe"
}
```

### Tips for Best Results

- Start with a small `results_wanted` count (20-50) for testing, then increase for production runs.
- Enable Apify Proxy with residential groups when collecting large volumes to avoid rate limits.
- Use complete public Unsplash URLs for reliable parsing of search, collection, topic, or profile pages.
- If a field is missing in the output, the source page likely does not publish that information.

### Integrations

- **Google Sheets** - Send scraped image data to spreadsheets.
- **Webhooks** - Trigger downstream workflows after each run.
- **Make or Zapier** - Connect results to no-code automations.
- **API** - Access datasets programmatically from your own systems.

Datasets can be exported in JSON, CSV, Excel, XML, and other formats from the Apify Console.

### Frequently Asked Questions

#### Can I scrape multiple pages of images?

Yes. The Actor paginates automatically. Use `results_wanted` and `max_pages` to control the depth.

#### Does the Actor download the actual image files?

No. It extracts image URLs and download links so you can fetch the files separately. This keeps the dataset lightweight and avoids storage overhead.

#### Can I export the data to CSV or Excel?

Yes. Apify datasets support JSON, CSV, Excel, XML, and other formats for download.

#### What happens if a photo is missing a description?

The Actor falls back to the alternate description. If both are empty, the field is excluded from the output.

#### Is it legal to scrape Unsplash?

Unsplash provides publicly accessible image data. You are responsible for complying with applicable laws, website terms, and copyright rules.

### Related Actors

- [Pixabay Image Scraper](https://apify.com/shahidirfan/pixabay-image-scraper) - Extract high-resolution image URLs, tags, and creator metadata from Pixabay.
- [Pexels Stock Image Scraper](https://apify.com/shahidirfan/pexels-stock-image-scraper) - Bulk download royalty-free images from Pexels with photographer details and metadata.
- [OpenVerse Image Scraper](https://apify.com/shahidirfan/openverse-image-scraper) - Collect Creative Commons and public domain images from OpenVerse with license and attribution data.

### Support

For issues, feature requests, or custom Actor work, use the Issues tab on the Actor page or contact the developer through Apify.

### Legal Notice

This Actor is designed for legitimate data collection from publicly available sources on Unsplash. Users are responsible for using the data responsibly and complying with applicable laws and website terms.

# Actor input Schema

## `url` (type: `string`):

Unsplash URL to scrape (e.g. search, collection, topic, user profile). If provided, it overrides the keyword.

## `keyword` (type: `string`):

Search keyword (e.g., 'spring', 'nature', 'city') to search for photos if no URL is provided.

## `results_wanted` (type: `integer`):

Maximum number of images to extract.

## `max_pages` (type: `integer`):

Maximum number of pages to paginate.

## `proxyConfiguration` (type: `object`):

Use Apify Proxy for reliable scraping.

## Actor input object example

```json
{
  "keyword": "spring",
  "results_wanted": 20,
  "max_pages": 5,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keyword": "spring",
    "results_wanted": 20,
    "max_pages": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("shahidirfan/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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "keyword": "spring",
    "results_wanted": 20,
    "max_pages": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("shahidirfan/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 '{
  "keyword": "spring",
  "results_wanted": 20,
  "max_pages": 5
}' |
apify call shahidirfan/unsplash-image-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=shahidirfan/unsplash-image-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/mdZyQ1p7CzTcl8lUc/builds/PccG1mnm6Rar1H4my/openapi.json