Unsplash

# Unsplash API Search, browse, and download high-quality free photos from Unsplash's library of millions of images. ## Setup & Authentication ### Get your Access Key 1. Create account at https://unsplash.com/developers 2. Register a new application 3. Copy your **Access Key** (starts with your app name) ### Store credentials ```bash mkdir -p ~/.config/unsplash echo "YOUR_ACCESS_KEY" > ~/.config/unsplash/access_key chmod 600 ~/.config/unsplash/access_key ``` Or set environment variable: ```bash export UNSPLASH_ACCESS_KEY="your_access_key_here" ``` ### Rate Limits - **Demo**: 50 requests/hour - **Production**: 5,000 requests/hour (after app approval) - Only `/v1/messages` endpoints count; image URLs (`images.unsplash.com`) don't ## Common Operations ### Search Photos ```bash curl "https://api.unsplash.com/search/photos?query=nature&per_page=10" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" ``` **Parameters:** - `query`: Search terms (required) - `page`: Page number (default: 1) - `per_page`: Results per page (default: 10, max: 30) - `order_by`: `relevant` (default) or `latest` - `color`: Filter by color (`black_and_white`, `black`, `white`, `yellow`, `orange`, `red`, `purple`, `magenta`, `green`, `teal`, `blue`) - `orientation`: `landscape`, `portrait`, or `squarish` ### Get Random Photo ```bash curl "https://api.unsplash.com/photos/random?query=coffee&count=1" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" ``` **Parameters:** - `query`: Limit to search term (optional) - `count`: Number of photos (1-30, default: 1) - `orientation`: Filter by orientation - `collections`: Filter by collection IDs (comma-separated) ### Get Photo Details ```bash curl "https://api.unsplash.com/photos/PHOTO_ID" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" ``` Returns full photo metadata including EXIF, location, user info, and all image URLs. ### Track Download (Required!) **Important:** You MUST trigger this endpoint when downloading a photo to comply with API guidelines. ```bash curl "https://api.unsplash.com/photos/PHOTO_ID/download" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" ``` This increments the download counter. Response includes the download URL. ### List Editorial Feed ```bash curl "https://api.unsplash.com/photos?per_page=10" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" ``` ### Browse Collections ```bash # List all collections curl "https://api.unsplash.com/collections?per_page=10" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" # Get collection photos curl "https://api.unsplash.com/collections/COLLECTION_ID/photos" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" ``` ### User Photos ```bash curl "https://api.unsplash.com/users/USERNAME/photos?per_page=10" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" ``` ## Working with Images ### Image URLs Every photo response includes these URLs: ```json { "urls": { "raw": "https://images.unsplash.com/photo-xxx?ixid=xxx", "full": "...?ixid=xxx&q=80&fm=jpg", "regular": "...?ixid=xxx&w=1080&fit=max", "small": "...?w=400&fit=max", "thumb": "...?w=200&fit=max" } } ``` ### Dynamic Resizing Add parameters to any image URL (keep the `ixid` parameter!): - `w=1500`: Set width - `h=800`: Set height - `dpr=2`: Device pixel ratio - `q=75`: Quality (1-100) - `fm=jpg`: Format (jpg, png, webp, avif) - `fit=crop`: Fit mode (crop, max, clip) - `crop=entropy`: Crop mode **Example:** ``` https://images.unsplash.com/photo-xxx?ixid=xxx&w=1500&h=1000&fit=crop&q=85 ``` ### BlurHash Placeholders Each photo includes a `blur_hash` field - a compact string representation for showing blurred placeholders while images load. ```json { "blur_hash": "LoC%a7IoIVxZ_NM|M{s:%hRjWAo0" } ``` ## Response Structure ### Photo Object (abbreviated) ```json { "id": "LBI7cgq3pbM", "created_at": "2016-05-03T11:00:28-04:00", "width": 5245, "height": 3497, "color": "#60544D", "blur_hash": "LoC%a7IoIVxZ_NM|M{s:%hRjWAo0", "description": "A man drinking coffee", "urls": { "raw": "...", "full": "...", "regular": "..." }, "links": { "download": "...", "download_location": "https://api.unsplash.com/photos/xxx/download" }, "user": { "username": "johndoe", "name": "John Doe", "profile_image": { "small": "...", "medium": "...", "large": "..." } } } ``` ### Search Response ```json { "total": 133, "total_pages": 7, "results": [ /* array of photo objects */ ] } ``` ## Best Practices ### Attribution Always attribute photos to their creators: ``` Photo by [Name] on Unsplash ``` Link to photographer's Unsplash profile when possible. ### Download Tracking - Call `/photos/:id/download` before allowing users to download - This is required by Unsplash API Guidelines - Don't use it for just displaying images (that's tracked automatically via hotlinking) ### Hotlinking - You can hotlink images directly from `images.unsplash.com` - These don't count against rate limits - Views are tracked automatically - Always keep the `ixid` parameter in URLs ### Caching - Public endpoints (search, photos) are cacheable - Consider caching search results client-side to reduce API calls ## Quick Reference ```bash # Store key export UNSPLASH_ACCESS_KEY="your_key" # Search curl "https://api.unsplash.com/search/photos?query=ocean&per_page=5" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" # Random photo curl "https://api.unsplash.com/photos/random?query=mountains" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" # Get photo curl "https://api.unsplash.com/photos/PHOTO_ID" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" # Track download (required when downloading!) curl "https://api.unsplash.com/photos/PHOTO_ID/download" \ -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}" ``` ## Notes - Base URL: `https://api.unsplash.com` - All responses are JSON - Pagination via `page` and `per_page` parameters - Link headers provide first/prev/next/last page URLs - Image requests to `images.unsplash.com` don't count against rate limits - Keep the `ixid` parameter when using/manipulating image URLs - For production use, apply for increased rate limits in your dashboard ## Common Filters ### Colors `black_and_white`, `black`, `white`, `yellow`, `orange`, `red`, `purple`, `magenta`, `green`, `teal`, `blue` ### Orientations `landscape`, `portrait`, `squarish` ### Sort Options - Photos: `latest`, `oldest`, `popular` - Search: `relevant`, `latest` ## Error Handling - `401 Unauthorized`: Invalid or missing access key - `403 Forbidden`: Rate limit exceeded or forbidden action - `404 Not Found`: Photo/user/collection doesn't exist Check `X-Ratelimit-Remaining` header to monitor your rate limit status.