Unsplash API

# 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

mkdir -p ~/.config/unsplash
echo "YOUR_ACCESS_KEY" > ~/.config/unsplash/access_key
chmod 600 ~/.config/unsplash/access_key

Or set environment variable:

export UNSPLASH_ACCESS_KEY="your_access_key_here"

Rate Limits

Common Operations

Search Photos

curl "https://api.unsplash.com/search/photos?query=nature&per_page=10" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

**Parameters:**

Get Random Photo

curl "https://api.unsplash.com/photos/random?query=coffee&count=1" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

**Parameters:**

Get Photo Details

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.

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

curl "https://api.unsplash.com/photos?per_page=10" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

Browse Collections

# 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

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:

{
  "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!):

**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.

{
  "blur_hash": "LoC%a7IoIVxZ_NM|M{s:%hRjWAo0"
}

Response Structure

Photo Object (abbreviated)

{
  "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

{
  "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

Hotlinking

Caching

Quick Reference

# 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

Common Filters

Colors

`black_and_white`, `black`, `white`, `yellow`, `orange`, `red`, `purple`, `magenta`, `green`, `teal`, `blue`

Orientations

`landscape`, `portrait`, `squarish`

Sort Options

Error Handling

Check `X-Ratelimit-Remaining` header to monitor your rate limit status.