Unsplash APIunsplash.com ↗
Search Unsplash photos by keyword, orientation, and sort order. Returns image URLs, EXIF data, tags, location, view counts, and photographer profiles.
What is the Unsplash API?
This API exposes 3 endpoints for querying and retrieving Unsplash photo data, returning up to 30 results per page with image URLs at five resolutions, photographer profiles, and metadata including tags, EXIF fields, and location. The search_photos endpoint accepts keyword queries with optional orientation and sort filters, while get_photo_details returns per-photo depth including view counts, download counts, and related collections.
curl -X GET 'https://api.parse.bot/scraper/d7435d90-1d30-4d76-911f-b0d609c511ae/search_photos?page=1&query=nature&order_by=relevant&per_page=3&orientation=landscape' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace unsplash-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.unsplash_image_api import Unsplash, Sort, Orientation, PhotoNotFound
unsplash = Unsplash()
# Search for landscape nature photos sorted by relevance
for summary in unsplash.photosummaries.search(query="nature", order_by=Sort.RELEVANT, orientation=Orientation.LANDSCAPE, limit=5):
print(summary.alt_description, summary.likes, summary.photographer.name)
print(summary.urls.regular)
# Navigate to full photo details for the first result
photo = summary.details()
print(photo.tags, photo.views, photo.downloads)
if photo.exif:
print(photo.exif.make, photo.exif.model)
break
# Search with tags pre-fetched (enriched results)
for tagged_photo in unsplash.photosummaries.search_with_tags(query="ocean", orientation=Orientation.PORTRAIT, limit=3):
print(tagged_photo.slug, tagged_photo.tags, tagged_photo.photographer.username)
Search Unsplash photos by keyword or theme. Returns paginated results with image URLs, dimensions, descriptions, and photographer details. Server-side filtering limited to query, orientation, and sort order. Paginates via page number.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (1-based) |
| queryrequired | string | Search keyword or theme (e.g., 'nature', 'architecture', 'ocean') |
| order_by | string | Sort order for results |
| per_page | integer | Number of results per page (max 30) |
| orientation | string | Filter by photo orientation |
{
"type": "object",
"fields": {
"page": "integer — current page number",
"query": "string — the search query used",
"photos": "array of photo objects with id, slug, description, urls, photographer, etc.",
"per_page": "integer — results per page",
"total_pages": "integer — total pages available",
"total_results": "integer — total matching photos on Unsplash"
},
"sample": {
"data": {
"page": 1,
"query": "nature",
"photos": [
{
"id": "fWBZ9r4vO9M",
"slug": "a-lush-green-forest-filled-with-lots-of-trees-fWBZ9r4vO9M",
"urls": {
"raw": "https://plus.unsplash.com/premium_photo-1673292293042-cafd9c8a3ab3?ixid=...",
"full": "https://plus.unsplash.com/premium_photo-1673292293042-cafd9c8a3ab3?...",
"small": "https://plus.unsplash.com/premium_photo-1673292293042-cafd9c8a3ab3?...&w=400",
"thumb": "https://plus.unsplash.com/premium_photo-1673292293042-cafd9c8a3ab3?...&w=200",
"regular": "https://plus.unsplash.com/premium_photo-1673292293042-cafd9c8a3ab3?...&w=1080"
},
"color": "#EFEFEF",
"likes": 592,
"links": {
"html": "https://unsplash.com/photos/a-lush-green-forest-filled-with-lots-of-trees-fWBZ9r4vO9M",
"download": "https://unsplash.com/photos/fWBZ9r4vO9M/download?ixid=..."
},
"width": 4000,
"height": 6000,
"premium": true,
"asset_type": "photo",
"created_at": "2023-01-12T15:26:03Z",
"updated_at": "2026-06-09T23:13:24Z",
"description": null,
"photographer": {
"id": "10S_nPICv74",
"bio": "Young photogapher based in switzerland",
"name": "Dario Brönnimann",
"location": "switzerland, Bern",
"username": "dariobroe",
"last_name": "Brönnimann",
"first_name": "Dario",
"profile_url": "https://unsplash.com/@dariobroe",
"total_photos": 484,
"portfolio_url": "https://dariobroe.darkroom.tech/",
"profile_image": "https://images.unsplash.com/profile-...?crop=faces&fit=crop&w=64&h=64",
"twitter_username": null,
"instagram_username": "dariobroe"
},
"alt_description": "a lush green forest filled with lots of trees"
}
],
"per_page": 3,
"total_pages": 3435,
"total_results": 10303
},
"status": "success"
}
}About the Unsplash API
Search and Filter Photos
The search_photos endpoint accepts a required query string and optional parameters — orientation (landscape, portrait, or squarish), order_by (relevant or latest), per_page (up to 30), and page for pagination. The response includes total_results and total_pages so you can page through an entire result set, plus an array of photo objects carrying id, slug, description, and urls at raw, full, regular, small, and thumb sizes.
Full Photo Details
The get_photo_details endpoint takes a photo_id or slug and returns the most complete record available: an exif object (make, model, exposure_time, aperture, focal_length, iso), a location object (name, city, country), views, downloads, a tags array, and a photographer object with username, bio, location, and social links. It also returns a related_collections summary with a total count and collection array.
Tag-Enriched Search
The search_photos_with_tags endpoint combines search and detail retrieval in one call. It accepts the same query, order_by, and orientation parameters as search_photos but returns each photo already enriched with its tags array. The limit parameter (1–30) controls how many enriched results come back. The response also surfaces returned_count and total_available for result-set context.
Response Shape Notes
All three endpoints share a consistent photo object structure. URLs are delivered in five size variants directly usable in <img> tags or download flows. Photographer data includes social links when provided by the source. Tags are title strings (e.g., "mountain", "sunset"), not IDs, making them straightforward to use as labels or filter keys without a separate lookup.
The Unsplash API is a managed, monitored endpoint for unsplash.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when unsplash.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official unsplash.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Populating a design tool's stock photo picker using
search_photoswith orientation filtering - Building a photo attribution widget by pulling photographer name, username, and bio from
get_photo_details - Training an image classifier using keyword search results with their
tagsarrays fromsearch_photos_with_tags - Displaying location metadata (city, country) alongside editorial photos retrieved via
get_photo_details - Surfacing EXIF camera data (ISO, aperture, focal length) in a photography reference tool
- Aggregating view and download counts to rank photo popularity by search topic
- Curating themed mood boards by searching keywords and filtering results to
squarishorientation
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Unsplash have an official developer API?+
What does `get_photo_details` return beyond what the search endpoints provide?+
exif object (make, model, exposure_time, aperture, focal_length, iso), a location object (name, city, country), views, downloads, and a related_collections summary. Search endpoints return urls, description, and basic photographer info, but not those depth fields.Does the API return photo collections or user portfolios?+
get_photo_details includes a related_collections object with a total count and collection array tied to a specific photo, but there are no endpoints for browsing collections independently or retrieving all photos from a given photographer's portfolio. You can fork the API on Parse and revise it to add those endpoints.Is there a way to search by color or topic category rather than a text keyword?+
query (text), orientation, and order_by. Color-based filtering and Unsplash's topic/collection taxonomy are not exposed. You can fork the API on Parse and revise it to add color or topic parameters.What is the maximum number of results I can retrieve in one call, and how does pagination work?+
per_page is capped at 30 for search_photos. The response returns total_pages and total_results so you can iterate using the page parameter. search_photos_with_tags uses a limit parameter (1–30) instead and does not support page-level pagination in the same way.