unsplash.com APIunsplash.com ↗
Search Unsplash photos by keyword, orientation, and sort order. Returns image URLs, EXIF data, tags, location, view counts, and photographer profiles.
curl -X GET 'https://api.parse.bot/scraper/d7435d90-1d30-4d76-911f-b0d609c511ae/search_photos?page=1&query=mountain&order_by=relevant&per_page=3' \ -H 'X-API-Key: $PARSE_API_KEY'
Search Unsplash photos by keyword or theme. Returns paginated results with image URLs, descriptions, and photographer details.
| 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: 'relevant' or 'latest' |
| per_page | integer | Number of results per page (max 30) |
| orientation | string | Filter by orientation: 'landscape', 'portrait', or 'squarish' |
{
"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": "cats",
"photos": [
{
"id": "gz0rGe7mhL8",
"slug": "a-close-up-of-a-cat-on-a-bed-gz0rGe7mhL8",
"urls": {
"raw": "https://plus.unsplash.com/premium_photo-1667030474693-6d0632f97029?ixid=...",
"full": "...",
"small": "...",
"thumb": "...",
"regular": "..."
},
"color": "#c0d9d9",
"likes": 55,
"links": {
"html": "https://unsplash.com/photos/a-close-up-of-a-cat-on-a-bed-gz0rGe7mhL8",
"download": "..."
},
"width": 4106,
"height": 6159,
"premium": true,
"description": null,
"photographer": {
"id": "go2iiXuMU50",
"name": "Tim Schmidbauer",
"location": "Germany, Stuttgart",
"username": "timschmidbauer",
"total_photos": 617
},
"alt_description": "a close up of a cat on a bed"
}
],
"per_page": 3,
"total_pages": 515,
"total_results": 10300
},
"status": "success"
}
}About the unsplash.com 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.
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.
- 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 | 250 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.