Unsplash Image Search Scraper

Search public Unsplash photos by keyword and export one normalized record per photo for visual research, content planning, and asset catalogs. This Apify Actor accepts plain descriptive search phrases, returns one dataset row per collected photo, and includes fields such as photoUrl, imageUrlRegular, photographer attribution, dimensions, tags, sourceUrl, scrapedAt, and licensing context so downstream workflows can review source-backed image metadata in a consistent format. It is also usable through Apify MCP.

Best fit and connected workflows

Use this Actor when you have search phrases and want structured Unsplash photo metadata instead of browsing the site manually. It fits workflows that start with topic research, creative brief building, editorial planning, or catalog enrichment.

Typical routing patterns:

• Topic research to image discovery: turn themes like "minimal home office" or "mountain lake" into public Unsplash photo records.
• Asset catalog enrichment: collect image page URLs, delivery URLs, and attribution fields for internal references.
• Content planning review: compare tags, color, width, height, and likes across search results before selecting candidates.
• Query-driven sourcing: use orientation, color, and orderBy to shape the Unsplash search feed before results are saved.

Unsplash Image Search Scraper is designed as a focused workflow.

What one result means

Each dataset row represents one unique public Unsplash photo found for a submitted query. The Actor records the query that produced the item, along with a stable Unsplash photo ID and source-linked metadata.

Useful fields in each record include:

• photoUrl: canonical public Unsplash photo page
• imageUrlRegular: regular-size delivery URL when available
• photographerName and photographerProfileUrl: public attribution details when available
• width and height: source dimensions when available
• tags: public Unsplash tags
• sourceUrl and scrapedAt: requested search page and collection time
• license and licenseUrl: source licensing context for review before reuse

Practical scenario

Maya, a content strategist, starts with the phrases warm cafe interior and handmade ceramics. She runs the Actor with those queries and reviews the returned photoUrl, photographerName, width, height, tags, and licenseUrl fields. That gives her a source-attributed shortlist she can share with the design team, then open the original Unsplash pages for final review.

Input fields

Field	Type	Purpose
queries	array of strings	One to ten descriptive search phrases, searched independently on Unsplash. If omitted, the Actor searches for mountains.
maxItemsPerQuery	integer	Maximum validated images to save from each query. Accepted range: 1 to 100. Default: 10.
maxTotalItems	integer	Run-wide cap on saved and billed images across all queries. Accepted range: 1 to 500. Default: 20.
orientation	string	Optional search filter: any, landscape, portrait, or squarish.
color	string	Optional dominant-color filter: any, black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, or blue.
orderBy	string	Sort search results by relevant or latest.

Focused JSON example

{
  "queries": ["minimal home office"],
  "maxItemsPerQuery": 5,
  "maxTotalItems": 5,
  "orientation": "landscape",
  "color": "blue",
  "orderBy": "relevant"
}

Output fields

The default dataset stores one record per collected photo. The schema includes source-linked and attribution fields, plus optional delivery URLs and metadata when available.

Field	Type	Purpose
id	string	Stable Unsplash photo identifier.
title	string or null	Photo description or accessible title when available.
description	string or null	Source photo description when available.
altDescription	string or null	Accessible alt description when available.
photoUrl	string	Canonical public Unsplash photo page.
imageUrlRaw	string or null	Raw delivery URL when available.
imageUrlFull	string or null	Full delivery URL when available.
imageUrlRegular	string or null	Regular delivery URL when available.
imageUrlSmall	string or null	Small delivery URL when available.
imageUrlThumb	string or null	Thumbnail delivery URL when available.
width	integer or null	Original width in pixels when available.
height	integer or null	Original height in pixels when available.
color	string or null	Dominant source color when available.
likes	integer or null	Public like count when available.
createdAt	string or null	Source creation timestamp when available.
updatedAt	string or null	Source update timestamp when available.
photographerName	string or null	Public photographer display name when available.
photographerUsername	string or null	Public photographer username when available.
photographerProfileUrl	string or null	Public photographer profile URL when available.
tags	array of strings	Tags supplied by Unsplash.
query	string	Input phrase that produced the result.
rank	integer	Position in the collected result stream.
sourceUrl	string	Unsplash search page requested by the Actor.
scrapedAt	string	Collection timestamp.
license	string	Source licensing context.
licenseUrl	string	Unsplash license page.

Illustrative JSON record

{
  "id": "7VotVatHM7Q",
  "title": "a lake surrounded by trees with mountains in the background",
  "photoUrl": "https://unsplash.com/photos/a-lake-surrounded-by-trees-with-mountains-in-the-background-7VotVatHM7Q",
  "imageUrlRegular": "https://images.unsplash.com/photo-example",
  "width": 4240,
  "height": 2832,
  "color": "blue",
  "likes": 123,
  "photographerName": "Example Photographer",
  "photographerUsername": "example_user",
  "photographerProfileUrl": "https://unsplash.com/@example_user",
  "tags": ["mountain", "lake", "trees"],
  "query": "mountain lake",
  "rank": 1,
  "sourceUrl": "https://unsplash.com/s/photos/mountain%20lake?orientation=landscape&color=blue",
  "scrapedAt": "2026-01-01T12:00:00.000Z",
  "license": "Unsplash License",
  "licenseUrl": "https://unsplash.com/license"
}

How it works

The Actor searches public Unsplash result pages for each query, applies the selected filters, and saves one normalized record per collected photo to the default dataset. The dataset schema also includes a table view called Images that presents common fields such as photoUrl, imageUrlRegular, photographerName, width, height, likes, and scrapedAt.

The implementation contract indicates a Playwright-based crawler template, a default memory size of 512 MB, and Pay per event charging tied to a one-time Actor Start event plus a per-image event when a complete validated image record is persisted.

Pricing

Unsplash Image Search Scraper uses Pay per event plus Apify platform usage.

• One Actor Start event is charged once after input validation.
• One Unsplash Image Found event is charged for each complete, validated image record saved to the default dataset.
• Apify platform usage is billed separately and appears in Apify usage reporting.
• The live Pricing tab on the Actor page is the place to review the current event-based pricing and usage details before running.

Example: if a run saves eight image records, the event charge includes one start event plus eight image-found events. Platform usage is added separately by Apify.

Use with AI agents (MCP)

This Actor is available as an Apify Actor usable through Apify MCP. It can search public Unsplash photos from agent workflows and return source-attributed image metadata for later reasoning, filtering, or cataloging.

Exact Actor identity: khadinakbar/unsplash-image-scraper

A precise tool description for agents:

• Input: descriptive Unsplash search phrases and optional filters for result shape, dominant color, and ranking order.
• Output: one dataset row per photo with source page, image URLs, photographer attribution, tags, dimensions, and licensing context.

Search Unsplash for landscape photos matching "mountain lake". Return the photo page, regular image URL, photographer details, tags, dimensions when available, and the collection timestamp. Keep the result set within the requested caps and preserve source attribution.

Output interpretation guidance:

• Use photoUrl for the canonical Unsplash page.
• Use imageUrlRegular or another available delivery URL for preview pipelines.
• Use photographerName, photographerUsername, and photographerProfileUrl for attribution workflows.
• Use tags, color, width, and height as structured search metadata.
• Use sourceUrl and scrapedAt for provenance.
• Use license and licenseUrl as the source licensing context before reuse.

Pagination and cost guidance:

• Increase maxItemsPerQuery when you want more validated photos per phrase.
• Use maxTotalItems to set a run-wide ceiling across all queries.
• Lower caps reduce the number of billable image-found events.
• Query terms are searched independently, so multiple phrases can widen coverage while the total cap keeps the run bounded.

API example

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

const run = await client.actor('khadinakbar/unsplash-image-scraper').call({
  queries: ['mountain lake'],
  maxItemsPerQuery: 3,
  maxTotalItems: 3,
  orientation: 'landscape',
  color: 'blue',
  orderBy: 'relevant',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();

console.log(items);

Set APIFY_TOKEN in your environment before running the example. The dataset readback returns the collected image records from the default dataset.

Best results and outcome guidance

Use plain descriptive phrases that reflect how you want to browse Unsplash, such as subject, scene, mood, or setting. Keep the query list focused when you want a tighter result set, and use orientation, color, and orderBy to shape the search feed before collection.

A practical pattern is to start with a small maxItemsPerQuery and a modest maxTotalItems, inspect the returned records, then widen the search terms if the first pass is too narrow. If you need source-attributed records for a catalog, prioritize the fields that point back to Unsplash: photoUrl, sourceUrl, photographerProfileUrl, and licenseUrl.

Continue the workflow

• Then use Video Subtitle & Caption Extractor — 1000+ Sites + Whisper AI to extend Unsplash Image Search Scraper with a neighboring creator and media research source when the brief calls for Video data.
• Then use Twitch Videos Scraper — VOD Metadata to extend Unsplash Image Search Scraper with a neighboring creator and media research source when the brief calls for Twitch data.

Design note

I found that the dataset contract includes both imageUrlRegular and photographerProfileUrl as optional fields, while photoUrl, tags, query, rank, sourceUrl, scrapedAt, license, and licenseUrl are required. That makes it clear which provenance fields are always present versus which delivery and attribution fields are provided when available.

FAQ

Can I search by a photo ID or Unsplash profile URL?

This Actor is structured around descriptive search phrases in queries. It searches public Unsplash result pages and returns normalized photo metadata for the matching photos.

How do I get the most useful fields for a content library?

Use the dataset records and focus on photoUrl, imageUrlRegular, photographerName, photographerUsername, width, height, tags, query, and licenseUrl.

Can I use this as a source for licensing review?

Yes, the output includes license and licenseUrl so your team can review the Unsplash source context before reuse.

What if I want a freshness-oriented search?

Set orderBy to latest to ask Unsplash to rank matching photos by recent uploads instead of relevance.

Does the Actor change image pixels or download files?

It returns metadata and delivery URLs for public Unsplash photos. It is designed for search and catalog workflows, not file downloading or image editing.

Responsible use

Use this Actor only with public or otherwise authorized data and in line with applicable law, Unsplash terms, and your own privacy and intellectual-property obligations. Review the Unsplash License before reusing any image or image URL in another context.