Unsplash Photo Scraper

Scrape Unsplash — the web's largest curated library of free-to-use professional photography. Search by keyword, browse an official curated topic, a numeric collection, or a photographer's full portfolio. Get photographer credit, license, direct image URLs, dimensions, and orientation for every photo. No API key, no login, no cookies required.

What this actor does

• Four modes: search, byTopic, byCollection, byUser
• Reliable filters: orientation (landscape / portrait / squarish), dominant color (search mode), free-only (excludes Unsplash+ locked photos)
• Photographer credit: name, username, and profile URL on every photo
• Optional deep enrichment: license, shoot location, and publish date via an extra per-photo fetch
• Empty fields are omitted — every field present in a record is a real value, never null or an empty placeholder

Output per photo

• id — Unsplash's 11-character photo ID
• slug — the descriptive URL slug (e.g. a-lush-green-forest-filled-with-lots-of-trees-fWBZ9r4vO9M)
• title, description — the photo's alt-text description
• imageUrl — full-resolution image URL
• thumbnailUrl — small preview image URL
• width, height — native pixel dimensions
• orientation — landscape / portrait / squarish, computed from the real dimensions
• isPremium — true if the photo is Unsplash+ (paid, not freely downloadable)
• photographerUsername, photographerName, photographerProfileUrl
• license — link to the photo's license terms
• downloadUrl — direct download link (free photos only)
• locationName — shoot location, if tagged (only with fetchPhotoDetails: true)
• datePublished — ISO publish date (only with fetchPhotoDetails: true)
• isFamilyFriendly — Unsplash's own safe-content flag (only with fetchPhotoDetails: true)
• tags — related keyword tags shown on the photo's page (only with fetchPhotoDetails: true)
• sourceUrl — the photo's page on unsplash.com
• recordType: "photo", scrapedAt

Input

Field	Type	Default	Description
mode	string	search	search / byTopic / byCollection / byUser
searchQuery	string	nature	Free-text query (mode=search)
topicSlug	string	–	One of Unsplash's official curated topics (mode=byTopic)
collectionId	string	–	Numeric Unsplash collection ID (mode=byCollection)
username	string	–	Photographer username, with or without @ (mode=byUser)
orientation	string	any	any / landscape / portrait / squarish — works in every mode
color	string	any	Dominant color filter — only applies in search mode
freeOnly	boolean	false	Exclude Unsplash+ (paid) photos
fetchPhotoDetails	boolean	false	Visit each photo's page for license, location, and publish date (slower)
maxItems	int	20	Hard cap on emitted records (1–1000)

Example: search with filters

{
  "mode": "search",
  "searchQuery": "mountains",
  "orientation": "landscape",
  "color": "blue",
  "freeOnly": true,
  "maxItems": 40
}

Example: browse a curated topic

{
  "mode": "byTopic",
  "topicSlug": "wallpapers",
  "orientation": "portrait",
  "maxItems": 30
}

Example: a photographer's portfolio with full details

{
  "mode": "byUser",
  "username": "v2osk",
  "fetchPhotoDetails": true,
  "maxItems": 25
}

Example: a specific collection

{
  "mode": "byCollection",
  "collectionId": "1065396",
  "maxItems": 50
}

Use cases

• Design & content teams — source royalty-free photography for blog posts, presentations, and marketing assets
• Website builders / no-code tools — populate placeholder galleries with real, licensed imagery
• Mood-boarding & creative research — pull a curated topic or a favorite photographer's full portfolio in one run
• Dataset builders — compile labeled image sets (description, orientation, dominant subject) for ML pipelines
• Digital asset management — track a specific collection's contents and photographer credits over time

Data Source / Limitations

This actor scrapes Unsplash's public search and browse pages — it does not use Unsplash's official registered API (which requires an API key and a rate-limited developer application). Because of that:

• Unauthenticated (no-login) search results are capped at roughly 60 photos per query before Unsplash's "Load more" control disappears. byTopic, byCollection, and byUser are not capped the same way and can return several hundred photos when that many genuinely exist. The actor paginates until either maxItems is satisfied or the source is genuinely exhausted, and stops cleanly either way (no error, no hang).
• When a filter (orientation, color, freeOnly) is active, the actor keeps paginating past the raw maxItems candidate count as needed to find enough matching photos — it does not stop early just because enough unfiltered candidates were seen.
• Like counts, view counts, and download counts are not shown on unsplash.com's public pages (Unsplash removed them from public view) and are therefore not in the output.
• Unsplash+ (paid, licensed-only) photos appear in results with isPremium: true and lack a downloadUrl; use freeOnly: true to exclude them entirely.
• fetchPhotoDetails adds one extra page load per photo, so runs are noticeably slower with it enabled — only turn it on when you need location/license/tags/publish-date data.

FAQ

Is this affiliated with Unsplash? No. This is an independent, third-party actor that reads Unsplash's public web pages. It is not endorsed by or affiliated with Unsplash.

Do I need an Unsplash account, API key, or cookies? No. Every mode works without logging in, without an API key, and without supplying cookies.

What's the difference between byTopic and byCollection? Topics are Unsplash's own official, curated categories (like "Nature" or "Wallpapers") with a fixed, small set of slugs. Collections are numbered galleries that anyone (including Unsplash's editorial team) can create — you supply the numeric ID from the collection's URL.

Why do some photos have no photographerProfileUrl or downloadUrl? Every field is omitted rather than sent as empty — if a photographer's profile link isn't available for a given card, or a photo is Unsplash+ (which doesn't offer a free direct download), those fields simply won't appear on that record.

Can I get more than ~60 results for a single search query? search mode is capped at roughly 60 photos per query for anonymous visitors — that's an Unsplash platform limit, not an actor limit. byTopic, byCollection, and byUser don't share that cap and can return several hundred photos (a whole collection or portfolio) in one run. For more than ~60 search results, run multiple queries (synonyms, related keywords).

How fresh is the data? Every run scrapes unsplash.com live — there's no caching layer. Photo counts, ordering, and photographer details reflect what's on the site at run time.

Does this work for orientation filtering even in byTopic/byCollection/byUser modes? Yes. Unlike the color filter (which only works through Unsplash's own search), orientation is computed directly from each photo's real pixel dimensions, so it works reliably in every mode.