# Unsplash Scraper | All-In-One (`fatihtahta/unsplash-scraper`) Actor Extract Unsplash photos, illustrations, collections, and creator profiles at scale with rich image metadata, download links, engagement metrics, and photographer data. Built for enterprise-grade visual intelligence, content sourcing, asset research, and automated data pipelines. - **URL**: https://apify.com/fatihtahta/unsplash-scraper.md - **Developed by:** [Fatih Tahta](https://apify.com/fatihtahta) (community) - **Categories:** AI, Developer tools, Automation - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $0.70 / 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. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 Scraper | Stock Image Data Pipeline **Slug:** `fatihtahta/unsplash-scraper` ### Overview Unsplash Scraper collects structured photo records from Unsplash search results, direct Unsplash URLs, public collections, and photographer profiles, including core identifiers, titles, image URLs, dimensions, engagement metrics, photographer details, and source context. [Unsplash](https://unsplash.com) is a widely used public platform for discovering photography, illustrations, creators, and curated visual collections, making its public data valuable for content research, creative operations, market analysis, and enrichment workflows. The actor converts repeatable discovery inputs into normalized JSON records that can be used consistently across analytics, automation, and downstream data systems. It is designed for dependable recurring data acquisition while keeping outputs predictable enough for scheduled reporting, monitoring, and pipeline ingestion. Results reflect the public data available at run time, without making assumptions about completeness beyond what the target pages expose. ### Why Use This Actor - **Market research / analytics:** build structured extraction workflows around visual supply, topic coverage, creator activity, engagement signals, and content availability. - **Product & content teams:** discover image candidates, public creator profiles, and collection context for editorial planning, content operations, and asset research. - **Developers / data engineering pipelines:** feed normalized Unsplash records into downstream systems, enrichment pipelines, catalogs, search indexes, and operational reporting. - **Lead gen / enrichment:** collect public photographer profile attributes, portfolio links, usernames, locations, and visual specialization signals for enrichment workflows. - **Monitoring / competitive tracking:** schedule repeatable collection to observe new content, category movement, search result changes, and public profile updates over time. ### Common Use Cases - **Visual market intelligence:** monitor public image supply, topic coverage, creator activity, likes, and content availability across search terms. - **Content sourcing workflows:** build repeatable shortlists of public photo records for creative review, editorial planning, or internal asset evaluation. - **Creator discovery:** collect public photographer profiles and photo attribution details for research, outreach preparation, or enrichment. - **Catalog and directory building:** populate internal databases with structured public records for photos, collections, and creator-linked assets. - **Data enrichment:** add current public image metadata, creator details, and source URLs to existing CRM, BI, or analytics datasets. - **Recurring reporting:** schedule periodic runs for dashboards, alerts, trend analysis, and topic-level monitoring. - **Collection monitoring:** track public Unsplash collections or direct URLs over time to identify new or changed records. ### Quick Start 1. Choose a scrape target: add direct Unsplash URLs in `start_url`, enter keyword searches in `queries`, or use both when you need combined coverage. 2. Select the search `category` for keyword searches: `photos`, `illustrations`, `collections`, or `users`. 3. For keyword photo or illustration searches, optionally refine results with `sort_by`, `orientation`, `license`, and illustration `style`. 4. Set a small `limit`, such as `25` or `50`, for the first validation run. 5. Run the actor in Apify Console and inspect the first dataset records to confirm the output shape matches your use case. 6. Increase the limit, add more targets, or schedule the actor once the output is verified. ### Input Parameters Provide at least one scrape target using `start_url`, `queries`, or both; optional filters refine keyword-based discovery. | Parameter | Type | Description | Default | | --- | --- | --- | --- | | `start_url` | array of strings | Full Unsplash URLs to collect from directly. Use for search result pages, public collections, photographer profiles, or other public Unsplash URLs. | – | | `queries` | array of strings | Search terms for keyword-based discovery, such as `nature`, `office workspace`, or `black background`. | – | | `category` | string | Search category used for keyword searches. Allowed values: `photos`, `illustrations`, `collections`, `users`. This does not change direct URL targets. | `photos` | | `sort_by` | string | Sort order for keyword photo and illustration searches. Allowed values: `relevance`, `newest`, `curated`. | `relevance` | | `orientation` | string | Optional image layout filter for keyword photo and illustration searches. Allowed values: `landscape`, `portrait`, `square`. | – | | `license` | string | Optional license grouping for keyword photo and illustration searches. Allowed values: `unsplash_plus`, `free`. | – | | `style` | array of strings | Optional illustration style filters for keyword searches in the `illustrations` category. Allowed values: `3d`, `hand_drawn`, `line_art`, `flat`. | – | | `limit` | integer | Maximum number of photo records to save per URL or search term. Minimum: `1`. Leave empty to collect available records until the target is exhausted or the run stops. | – | ### Choosing Inputs Use `start_url` when you already know the exact Unsplash page you want to collect from, such as a public collection, profile, or search results URL. Use `queries` when you want broader discovery across topics, visual themes, people, collections, or content categories. The `category` field controls how keyword searches are interpreted: use `photos` for image records, `illustrations` for illustrated assets, `collections` for curated groups, and `users` for photographer profile discovery. Narrower filters such as `orientation`, `license`, and `style` produce more targeted datasets, while broader inputs improve discovery and coverage. Use `sort_by: "newest"` for freshness-oriented monitoring, `relevance` for general discovery, and `curated` when editorially selected results are preferred. Start with a small `limit` to validate output quality, then increase it once the saved records match your workflow. ### Example Inputs #### Search-driven photo discovery ```json { "queries": ["nature", "forest trail"], "category": "photos", "sort_by": "relevance", "orientation": "landscape", "license": "free", "limit": 50 } ```` #### Direct collection URL run ```json { "start_url": ["https://unsplash.com/collections/1319040/nature"], "limit": 100 } ``` #### Targeted illustration search ```json { "queries": ["remote work", "team collaboration"], "category": "illustrations", "sort_by": "newest", "orientation": "square", "style": ["flat", "line_art"], "limit": 40 } ``` ### Output #### Output destination The actor writes results to an Apify dataset as JSON records. The dataset is designed for direct consumption by analytics tools, ETL pipelines, and downstream APIs with minimal post-processing. When multiple entity types or record shapes exist, the README documents each shape separately based on the provided Example Output. The examples below document the observed `photo`, `illustration`, `collection`, and `profile` record shapes. #### Record envelope and stable identifiers Each record is organized as a JSON object with top-level identity fields, nested detail objects, and `source_context`. The recommended idempotency key is `id` for all documented record types; if your storage layer requires a URL-based key, use `url` as a secondary stable identifier. For deduplication and upserts, store one record per `type` + `id` pair and update mutable fields such as metrics, timestamps, media URLs, and source context on repeated runs. Stable identifiers make records easier to merge, deduplicate, and sync across repeated runs. The `source_context.source_url` field identifies the source context used for collection, while `source_context.seed_id`, `source_context.seed_type`, and `source_context.seed_value` help connect each record back to the input that produced it. #### Examples ##### Example: photo (`type = "photo"`) ```json { "type": "photo", "id": "pH0t0Exmpl1", "slug": "misty-forest-trail-at-sunrise-pH0t0Exmpl1", "url": "https://unsplash.com/photos/misty-forest-trail-at-sunrise-pH0t0Exmpl1", "title": "misty forest trail at sunrise", "alt_description": "misty forest trail at sunrise", "created_at": "2023-01-12T15:26:03Z", "updated_at": "2026-05-18T21:13:54Z", "metrics": { "likes": 428 }, "media": { "images": { "raw": "https://images.unsplash.com/photo-example-forest-trail-raw?ixlib=rb-4.1.0", "full": "https://images.unsplash.com/photo-example-forest-trail-full?crop=entropy&cs=srgb&fm=jpg&ixlib=rb-4.1.0&q=85", "regular": "https://images.unsplash.com/photo-example-forest-trail-regular?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixlib=rb-4.1.0&q=80&w=1080", "small": "https://images.unsplash.com/photo-example-forest-trail-small?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixlib=rb-4.1.0&q=80&w=400", "thumbnail": "https://images.unsplash.com/photo-example-forest-trail-thumb?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixlib=rb-4.1.0&q=80&w=200" }, "dimensions": { "width": 4000, "height": 6000 }, "color": "#EFEFEF", "blur_hash": "L35}~Mx@D=xpVhtQ%dWB8*t7xWM}" }, "downloads": { "download_url": "https://unsplash.com/photos/pH0t0Exmpl1/download?ixid=example", "download_location": "https://api.unsplash.com/photos/pH0t0Exmpl1/download?ixid=example" }, "photographer": { "id": "usrNature01", "username": "maya_rivers", "name": "Maya Rivers", "url": "https://unsplash.com/@maya_rivers", "location": "Portland, Oregon", "bio": "Landscape photographer focused on forests, quiet trails, and natural light.", "portfolio_url": "https://example.com/maya-rivers", "instagram_username": "maya.rivers", "profile_image_url": "https://images.unsplash.com/profile-example-maya-rivers?ixlib=rb-4.1.0&crop=faces&fit=crop&w=128&h=128" }, "flags": { "premium": true, "plus": true }, "attributes": { "asset_type": "photo" }, "source_context": { "source_url": "https://unsplash.com/s/photos/nature", "seed_id": "seed_nature_001", "seed_type": "query", "seed_value": "nature", "category": "photos", "page_index": 1 } } ``` ##### Example: illustration (`type = "illustration"`) ```json { "type": "illustration", "id": "iLlustrEx01", "slug": "remote-designer-working-at-a-laptop-iLlustrEx01", "url": "https://unsplash.com/illustrations/remote-designer-working-at-a-laptop-iLlustrEx01", "title": "remote designer working at a laptop", "alt_description": "remote designer working at a laptop", "created_at": "2024-03-15T15:24:30Z", "updated_at": "2026-05-11T19:20:52Z", "metrics": { "likes": 36 }, "media": { "images": { "raw": "https://plus.unsplash.com/premium_vector-example-remote-work-raw?ixlib=rb-4.1.0", "full": "https://plus.unsplash.com/premium_vector-example-remote-work-full?crop=entropy&cs=srgb&fm=jpg&ixlib=rb-4.1.0&q=85", "regular": "https://plus.unsplash.com/premium_vector-example-remote-work-regular?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixlib=rb-4.1.0&q=80&w=1080", "small": "https://plus.unsplash.com/premium_vector-example-remote-work-small?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixlib=rb-4.1.0&q=80&w=400", "thumbnail": "https://plus.unsplash.com/premium_vector-example-remote-work-thumb?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixlib=rb-4.1.0&q=80&w=200" }, "dimensions": { "width": 225, "height": 150 }, "color": "#d9c0c0", "blur_hash": "LPL4BCt79Zt8.To2Diay9FaeIUV[" }, "downloads": { "download_url": "https://unsplash.com/photos/iLlustrEx01/download?ixid=example", "download_location": "https://api.unsplash.com/photos/iLlustrEx01/download?ixid=example" }, "photographer": { "id": "usrDesign02", "username": "studio_lina", "name": "Lina Studio", "url": "https://unsplash.com/@studio_lina", "instagram_username": "studio.lina", "profile_image_url": "https://images.unsplash.com/profile-example-lina-studio?ixlib=rb-4.1.0&crop=faces&fit=crop&w=128&h=128" }, "flags": { "premium": true, "plus": true }, "attributes": { "asset_type": "illustration" }, "source_context": { "source_url": "https://unsplash.com/s/illustrations/remote-work", "seed_id": "seed_remote_001", "seed_type": "query", "seed_value": "remote work", "category": "illustrations", "page_index": 1 } } ``` ##### Example: collection (`type = "collection"`) ```json { "type": "collection", "id": "colNature001", "url": "https://unsplash.com/collections/colNature001/evergreen-landscapes", "title": "Evergreen Landscapes", "published_at": "2017-10-24T15:57:12Z", "last_collected_at": "2026-05-17T21:35:18Z", "updated_at": "2026-05-17T21:35:18Z", "metrics": { "total_photos": 1842, "total_plus": 0 }, "flags": { "featured": false, "private": false }, "cover_photo": { "id": "coverEx001", "url": "https://unsplash.com/photos/mountain-valley-cover-coverEx001", "images": { "regular": "https://images.unsplash.com/photo-example-mountain-cover-regular?ixlib=rb-4.1.0&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max", "small": "https://images.unsplash.com/photo-example-mountain-cover-small?ixlib=rb-4.1.0&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=400&fit=max", "thumbnail": "https://images.unsplash.com/photo-example-mountain-cover-thumb?ixlib=rb-4.1.0&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=200&fit=max" } }, "preview_photo_ids": [ "coverEx001", "prevNature02", "prevNature03", "prevNature04" ], "owner": { "id": "usrCurator03", "username": "northlight_curator", "name": "Northlight Curator", "url": "https://unsplash.com/@northlight_curator", "location": "Vancouver, Canada", "bio": "Curated landscape collections for editorial planning and visual research.", "instagram_username": "northlight.curator", "profile_image_url": "https://images.unsplash.com/profile-example-northlight?ixlib=rb-4.1.0&crop=faces&fit=crop&w=128&h=128" }, "attributes": { "share_key": "example-share-key-001" }, "source_context": { "source_url": "https://unsplash.com/s/collections/nature", "seed_id": "seed_nature_001", "seed_type": "query", "seed_value": "nature", "category": "collections", "page_index": 1 } } ``` ##### Example: profile (`type = "profile"`) ```json { "type": "profile", "id": "profExample01", "url": "https://unsplash.com/@alex_morgan_photo", "username": "alex_morgan_photo", "name": "Alex Morgan", "first_name": "Alex", "last_name": "Morgan", "location": "Landscape | Travel | Editorial | Outdoor Lifestyle", "updated_at": "2026-05-09T14:47:30Z", "metrics": { "total_collections": 0, "total_likes": 126, "total_photos": 84, "total_free_photos": 84, "total_promoted_photos": 0, "total_illustrations": 0, "total_free_illustrations": 0, "total_promoted_illustrations": 0 }, "flags": { "accepted_tos": true, "for_hire": false }, "media": { "profile_image_url": "https://images.unsplash.com/profile-example-alex-morgan?ixlib=rb-4.1.0&crop=faces&fit=crop&w=128&h=128" }, "sample_photo_ids": [ "samplePhoto01", "samplePhoto02", "samplePhoto03" ], "source_context": { "source_url": "https://unsplash.com/s/users/landscape", "seed_id": "seed_landscape_001", "seed_type": "query", "seed_value": "landscape", "category": "users", "page_index": 1 } } ``` ### Field Reference #### `photo` and `illustration` records **type** *(string, required)*: Record type. Values shown: `photo`, `illustration`. **id** *(string, required)*: Stable asset identifier and recommended idempotency key. **slug** *(string, optional)*: Human-readable asset slug when available. **url** *(string, required)*: Public Unsplash asset URL. **title** *(string, optional)*: Asset title or title-like public text. **alt\_description** *(string, optional)*: Public alternative description. **created\_at** *(string, optional)*: Creation timestamp in ISO 8601 format when available. **updated\_at** *(string, optional)*: Last update timestamp in ISO 8601 format when available. **metrics.likes** *(integer, optional)*: Public like count. **media.images.raw** *(string, optional)*: Raw image URL when available. **media.images.full** *(string, optional)*: Full-size image URL when available. **media.images.regular** *(string, optional)*: Regular-size image URL when available. **media.images.small** *(string, optional)*: Small image URL when available. **media.images.thumbnail** *(string, optional)*: Thumbnail image URL when available. **media.dimensions.width** *(integer, optional)*: Image width in pixels. **media.dimensions.height** *(integer, optional)*: Image height in pixels. **media.color** *(string, optional)*: Dominant color value when available. **media.blur\_hash** *(string, optional)*: Blur hash placeholder value when available. **downloads.download\_url** *(string, optional)*: Public download URL when available. **downloads.download\_location** *(string, optional)*: Download location reference when available. **photographer.id** *(string, optional)*: Stable photographer identifier. **photographer.username** *(string, optional)*: Unsplash username. **photographer.name** *(string, optional)*: Public photographer display name. **photographer.url** *(string, optional)*: Public Unsplash photographer profile URL. **photographer.location** *(string, optional)*: Public photographer location text. **photographer.bio** *(string, optional)*: Public photographer bio. **photographer.portfolio\_url** *(string, optional)*: Public portfolio URL provided by the photographer. **photographer.instagram\_username** *(string, optional)*: Public Instagram username when available. **photographer.profile\_image\_url** *(string, optional)*: Public profile image URL. **flags.premium** *(boolean, optional)*: Indicates whether the record is marked as premium content. **flags.plus** *(boolean, optional)*: Indicates whether the record is marked as Unsplash Plus content. **attributes.asset\_type** *(string, optional)*: Asset classification, such as `photo` or `illustration`. **source\_context.source\_url** *(string, optional)*: Source URL or source context associated with the record. **source\_context.seed\_id** *(string, optional)*: Identifier for the input seed that produced the record. **source\_context.seed\_type** *(string, optional)*: Input seed type, such as `query` or direct URL. **source\_context.seed\_value** *(string, optional)*: Original input value associated with the record. **source\_context.category** *(string, optional)*: Search category associated with the record. **source\_context.page\_index** *(integer, optional)*: Result page index associated with the record when available. #### `collection` record **type** *(string, required)*: Record type. For this shape, the value is `collection`. **id** *(string, required)*: Stable collection identifier and recommended idempotency key. **url** *(string, required)*: Public Unsplash collection URL. **title** *(string, optional)*: Public collection title. **published\_at** *(string, optional)*: Collection publication timestamp in ISO 8601 format. **last\_collected\_at** *(string, optional)*: Timestamp for latest collection activity when available. **updated\_at** *(string, optional)*: Last update timestamp in ISO 8601 format. **metrics.total\_photos** *(integer, optional)*: Public photo count for the collection. **metrics.total\_plus** *(integer, optional)*: Public Unsplash Plus count for the collection. **flags.featured** *(boolean, optional)*: Indicates whether the collection is marked as featured. **flags.private** *(boolean, optional)*: Indicates whether the collection is marked private in the returned public data. **cover\_photo.id** *(string, optional)*: Stable identifier for the collection cover photo. **cover\_photo.url** *(string, optional)*: Public URL for the cover photo. **cover\_photo.images.regular** *(string, optional)*: Regular-size cover image URL. **cover\_photo.images.small** *(string, optional)*: Small cover image URL. **cover\_photo.images.thumbnail** *(string, optional)*: Thumbnail cover image URL. **preview\_photo\_ids** *(array of strings, optional)*: Preview photo identifiers associated with the collection. **owner.id** *(string, optional)*: Stable owner identifier. **owner.username** *(string, optional)*: Public owner username. **owner.name** *(string, optional)*: Public owner display name. **owner.url** *(string, optional)*: Public owner profile URL. **owner.location** *(string, optional)*: Public owner location text. **owner.bio** *(string, optional)*: Public owner bio. **owner.instagram\_username** *(string, optional)*: Public Instagram username when available. **owner.profile\_image\_url** *(string, optional)*: Public owner profile image URL. **attributes.share\_key** *(string, optional)*: Collection share key when available in the public data. **source\_context.source\_url** *(string, optional)*: Source URL or source context associated with the record. **source\_context.seed\_id** *(string, optional)*: Identifier for the input seed that produced the record. **source\_context.seed\_type** *(string, optional)*: Input seed type, such as `query` or direct URL. **source\_context.seed\_value** *(string, optional)*: Original input value associated with the record. **source\_context.category** *(string, optional)*: Search category associated with the record. **source\_context.page\_index** *(integer, optional)*: Result page index associated with the record when available. #### `profile` record **type** *(string, required)*: Record type. For this shape, the value is `profile`. **id** *(string, required)*: Stable profile identifier and recommended idempotency key. **url** *(string, required)*: Public Unsplash profile URL. **username** *(string, optional)*: Public Unsplash username. **name** *(string, optional)*: Public profile display name. **first\_name** *(string, optional)*: Public first name when available. **last\_name** *(string, optional)*: Public last name when available. **location** *(string, optional)*: Public profile location or location-like profile text. **updated\_at** *(string, optional)*: Last update timestamp in ISO 8601 format. **metrics.total\_collections** *(integer, optional)*: Public collection count. **metrics.total\_likes** *(integer, optional)*: Public like count. **metrics.total\_photos** *(integer, optional)*: Public photo count. **metrics.total\_free\_photos** *(integer, optional)*: Public free-photo count. **metrics.total\_promoted\_photos** *(integer, optional)*: Public promoted-photo count. **metrics.total\_illustrations** *(integer, optional)*: Public illustration count. **metrics.total\_free\_illustrations** *(integer, optional)*: Public free-illustration count. **metrics.total\_promoted\_illustrations** *(integer, optional)*: Public promoted-illustration count. **flags.accepted\_tos** *(boolean, optional)*: Public account flag returned for the profile. **flags.for\_hire** *(boolean, optional)*: Indicates whether the profile is marked as available for hire. **media.profile\_image\_url** *(string, optional)*: Public profile image URL. **sample\_photo\_ids** *(array of strings, optional)*: Sample photo identifiers associated with the profile. **source\_context.source\_url** *(string, optional)*: Source URL or source context associated with the record. **source\_context.seed\_id** *(string, optional)*: Identifier for the input seed that produced the record. **source\_context.seed\_type** *(string, optional)*: Input seed type, such as `query` or direct URL. **source\_context.seed\_value** *(string, optional)*: Original input value associated with the record. **source\_context.category** *(string, optional)*: Search category associated with the record. **source\_context.page\_index** *(integer, optional)*: Result page index associated with the record when available. ### Data Quality, Guarantees, And Handling - **Structured records:** results are normalized into predictable JSON objects for downstream use. - **Best-effort extraction:** fields may vary by region, session, availability, and public interface changes. - **Optional fields:** null-check optional fields in downstream code, especially profile details, media variants, timestamps, and engagement metrics. - **Deduplication:** use `id` as the strongest stable key for photo records, with `url` as a secondary reference when needed. - **Freshness:** results reflect the publicly available data at run time. - **Repeated runs:** use the recommended idempotency key when syncing data into warehouses, CRMs, or search indexes. ### Tips For Best Results - Start with a small `limit` to validate the output shape before scaling up. - Use one topic, category, collection, or profile segment per run when you need cleaner segmentation. - Use `start_url` for known collections or profiles, and `queries` for discovery workflows. - Leave optional filters empty when the goal is broad discovery. - Add `orientation`, `license`, and `style` filters gradually to understand how each field changes coverage. - Use `sort_by: "newest"` for monitoring recently added keyword results. - Store results by `id` when comparing records across repeated runs. ### How to Run on Apify 1. Open the Actor in Apify Console. 2. Configure the available input fields for the target scope. 3. Set the maximum number of outputs to collect with `limit`. 4. Click **Start** and wait for the run to finish. 5. Open the dataset and inspect the first records. 6. Download results in JSON, CSV, Excel, or other supported formats. ### Scheduling & Automation #### Scheduling **Automated Data Collection** Schedule runs to keep Unsplash search, collection, and profile datasets fresh for recurring analysis. Use scheduled inputs for stable topics, monitored collections, or repeatable creator discovery workflows. - Navigate to **Schedules** in Apify Console - Create a new schedule, such as daily, weekly, or custom cron - Configure input parameters - Enable notifications for run completion - Add webhooks for automated processing #### Integration Options - **ETL pipelines:** ingest normalized photo records, media metadata, and source context into downstream data workflows. - **BI dashboards:** monitor topic coverage, creator activity, public engagement metrics, and content volume over time. - **Search indexes:** power internal discovery tools with titles, descriptions, photographer fields, and image metadata. - **Content operations systems:** route candidate photo records into editorial review, asset selection, or catalog workflows. - **Webhooks:** trigger validation, notification, or ingestion workflows after each completed run. - **Google Sheets or Airtable:** review small curated datasets, shortlist visual assets, or coordinate lightweight research tasks. ### Export Formats And Downstream Use Apify datasets can be exported or consumed by downstream systems for reporting, enrichment, and automation. Choose the format that matches how your team reviews or processes structured Unsplash records. - **JSON:** for APIs, applications, and data pipelines - **CSV or Excel:** for spreadsheet workflows and manual review - **API access:** for automated ingestion into internal systems - **BI and warehouses:** for reporting, dashboards, and historical analysis ### Performance Estimated run times: - **Small runs (< 1,000 outputs):** ~3-5 minutes - **Medium runs (1,000-5,000 outputs):** ~5-15 minutes - **Large runs (5,000+ outputs):** ~15-30 minutes Execution time varies based on filters, result volume, and how much information is returned per record. Highly filtered runs can finish faster, while broad discovery or detail-rich records may take longer. ### Limitations - Availability depends on what publicly exposes at run time. - Some optional fields may be missing on sparse photo, collection, or profile records. - Very broad searches may take longer or require higher limits to collect the desired coverage. - Target-side changes can affect field availability, naming, or visible result ordering. - Regional, account, or availability differences may change visible results. - Unsplash Plus and free content availability can vary by query, category, and current public visibility. ### Troubleshooting - **No results returned:** check filters, category spelling, direct URLs, and whether the target has matching public records. - **Fewer results than expected:** broaden filters, raise the `limit`, or verify that the target contains enough matching records. - **Some fields are empty:** optional fields depend on what each public record provides. - **Run takes longer than expected:** reduce scope, lower `limit` for validation, or split broad collection into smaller segments. - **Output changed:** compare the current output with the field reference and report a small sample if support is needed. ### FAQ #### What data does this actor collect? It collects structured public Unsplash records from search results, direct Unsplash URLs, public collections, and photographer profiles. Photo records can include identifiers, URLs, titles, descriptions, image variants, dimensions, likes, download references, photographer details, flags, attributes, and source context. #### Can I filter by location, category, date, price, or other criteria? The schema supports `category`, `sort_by`, `orientation`, `license`, `style`, and `limit`. It does not include date, price, radius, or location filters; public profile records may still include a photographer location field when Unsplash provides it. #### Why did I receive fewer results than my limit? The target may not expose enough matching public records for the selected query, category, URL, or filters. Broaden the filters, use a different query, or verify that the source page contains enough public results. #### Can I schedule recurring runs? Yes. Use Apify schedules to run the actor daily, weekly, or on a custom cron schedule with saved input parameters. #### How do I avoid duplicates across runs? Use `id` as the primary idempotency key for photo records. If your system is URL-oriented, store `url` as a secondary stable reference. #### Can I export the data to CSV, Excel, or JSON? Yes. Apify datasets support export formats including JSON, CSV, Excel, and other formats available in Apify Console. #### Does this actor collect private data? No. The actor is intended for publicly available Unsplash information visible from the target website. Users are responsible for using the collected data lawfully and responsibly. #### Can I collect Unsplash Plus and free content separately? Yes, keyword photo and illustration searches can use the `license` field with `unsplash_plus` or `free` where that refinement is supported by Unsplash. #### What should I include when reporting an issue? Include the input used, redacted if needed, the run ID, expected versus actual behavior, and a small output sample when it helps explain the issue. ### Compliance & Ethics #### Responsible Data Collection This actor collects publicly available photo, collection, and photographer profile information from **https://unsplash.com** for legitimate business purposes, including: - **Creative and media** research and market analysis - **Content operations** and asset discovery workflows - **Data enrichment** for analytics, catalogs, and internal reporting This section is informational and not legal advice. Users are responsible for ensuring that their use of the actor and the resulting data complies with applicable laws, regulations, and contractual obligations. #### Best Practices - Use collected data in accordance with applicable laws, regulations, and the target site's terms - Respect individual privacy and personal information - Use data responsibly and avoid disruptive or excessive collection - Do not use this actor for spamming, harassment, or other harmful purposes - Follow relevant data protection requirements where applicable, such as GDPR and CCPA ### Support For help, use the Issues tab or the actor page support options. Include the input used, redacted where appropriate, the run ID, expected versus actual behavior, and a small output sample if it helps reproduce or understand the issue. # Actor input Schema ## `queries` (type: `array`): Enter one or more search terms such as nature, office workspace, or black background. Broader terms collect wider result sets, while specific phrases produce more targeted records. ## `category` (type: `string`): Select which Unsplash search area should be used for keyword searches. This only affects records collected from search terms, not direct profile or collection URLs. ## `sort_by` (type: `string`): Choose how keyword photo and illustration searches should be ordered. Relevance is best for general discovery, newest is useful for fresh content, and curated emphasizes editorially selected results where available. ## `orientation` (type: `string`): Limit keyword photo and illustration searches to a specific image layout. Use this when your downstream workflow needs landscape, portrait, or square assets. ## `license` (type: `string`): Limit keyword photo and illustration searches by Unsplash license grouping. Use this when you need to separate free results from Unsplash Plus content. ## `style` (type: `array`): Select one or more illustration styles for keyword searches in the Illustrations category. Leave empty to keep illustration discovery broader. ## `start_url` (type: `array`): Enter full Unsplash URLs, one per line. https://unsplash.com/@marekpiwnicki 0r https://unsplash.com/collections/1319040/nature. ## `limit` (type: `integer`): Set the maximum number of photo records to save for each URL or search term. Leave empty when you want the actor to continue collecting available records until the target is exhausted or the run stops. ## Actor input object example ```json { "queries": [ "nature" ], "category": "photos", "sort_by": "relevance" } ``` # Actor output Schema ## `results` (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" ] }; // Run the Actor and wait for it to finish const run = await client.actor("fatihtahta/unsplash-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("fatihtahta/unsplash-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 fatihtahta/unsplash-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=fatihtahta/unsplash-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Unsplash Scraper | All-In-One", "description": "Extract Unsplash photos, illustrations, collections, and creator profiles at scale with rich image metadata, download links, engagement metrics, and photographer data. Built for enterprise-grade visual intelligence, content sourcing, asset research, and automated data pipelines.", "version": "0.0", "x-build-id": "FEJR8hXpojEN0TZuF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fatihtahta~unsplash-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fatihtahta-unsplash-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/fatihtahta~unsplash-scraper/runs": { "post": { "operationId": "runs-sync-fatihtahta-unsplash-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/fatihtahta~unsplash-scraper/run-sync": { "post": { "operationId": "run-sync-fatihtahta-unsplash-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", "properties": { "queries": { "title": "Add Search Terms", "type": "array", "description": "Enter one or more search terms such as nature, office workspace, or black background. Broader terms collect wider result sets, while specific phrases produce more targeted records.", "items": { "type": "string" } }, "category": { "title": "Choose Search Category", "enum": [ "photos", "illustrations", "collections", "users" ], "type": "string", "description": "Select which Unsplash search area should be used for keyword searches. This only affects records collected from search terms, not direct profile or collection URLs.", "default": "photos" }, "sort_by": { "title": "Choose Search Sort Order", "enum": [ "relevance", "newest", "curated" ], "type": "string", "description": "Choose how keyword photo and illustration searches should be ordered. Relevance is best for general discovery, newest is useful for fresh content, and curated emphasizes editorially selected results where available.", "default": "relevance" }, "orientation": { "title": "Filter by Image Orientation", "enum": [ "landscape", "portrait", "square" ], "type": "string", "description": "Limit keyword photo and illustration searches to a specific image layout. Use this when your downstream workflow needs landscape, portrait, or square assets." }, "license": { "title": "Filter by License Type", "enum": [ "unsplash_plus", "free" ], "type": "string", "description": "Limit keyword photo and illustration searches by Unsplash license grouping. Use this when you need to separate free results from Unsplash Plus content." }, "style": { "title": "Filter by Illustration Style (only applicable to illustrations searches)", "uniqueItems": true, "type": "array", "description": "Select one or more illustration styles for keyword searches in the Illustrations category. Leave empty to keep illustration discovery broader.", "items": { "type": "string", "enum": [ "3d", "hand_drawn", "line_art", "flat" ], "enumTitles": [ "3D | dimensional style", "Hand-drawn | sketch style", "Line art | outline style", "Flat | simplified style" ] } }, "start_url": { "title": "Add Unsplash URLs", "type": "array", "description": "Enter full Unsplash URLs, one per line. https://unsplash.com/@marekpiwnicki 0r https://unsplash.com/collections/1319040/nature.", "items": { "type": "string" } }, "limit": { "title": "Set Maximum Results per Target", "minimum": 1, "type": "integer", "description": "Set the maximum number of photo records to save for each URL or search term. Leave empty when you want the actor to continue collecting available records until the target is exhausted or the run stops." } } }, "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 } } } } } } } } } } ```