Unsplash

Overview

The Unsplash API gives you programmatic access to millions of high-quality, free-to-use photos: search, curated random photos, and per-photo metadata (author, dimensions, download links, EXIF). Photos are covered by the Unsplash License, which permits commercial use without attribution (attribution is appreciated).

Quick Start

Search photos (replace YOUR_ACCESS_KEY):

curl "https://api.unsplash.com/search/photos?query=mountain&per_page=5" \
  -H "Authorization: Client-ID YOUR_ACCESS_KEY"

A random photo:

curl "https://api.unsplash.com/photos/random?orientation=landscape" \
  -H "Authorization: Client-ID YOUR_ACCESS_KEY"

Get a photo by ID:

curl "https://api.unsplash.com/photos/abc123" \
  -H "Authorization: Client-ID YOUR_ACCESS_KEY"

Use the urls object for the exact sizes you need (raw, full, regular, small, thumb) — raw accepts query params like &w=800&q=80 for server-side resizing.

Authentication

• Register an app at unsplash.com/developers to get an Access Key.
• Read-only API calls use Authorization: Client-ID <ACCESS_KEY>.
• User-scoped actions (liking, creating collections, downloading stats) require the full OAuth flow with a redirect URI.

Rate Limits & Notes

• Free tier (“Demo”): 50 requests/hour — plenty for prototyping; production access needs the application review (higher limits).
• The X-Ratelimit-Remaining response header tells you your remaining quota.
• Always hotlink the urls values (don’t re-host) — that’s what the API is designed for.
• Respect the link header pagination on search results.

FAQ

Is Unsplash free? The API has a free demo tier (50 req/hr); production use requires an approved application. Photos themselves are free to use commercially under the Unsplash License.

Do I need OAuth? For read-only search/photo data you just need the Access Key (Client-ID header). OAuth is only for user-scoped actions.

Can I use the photos commercially? Yes — the Unsplash License allows commercial use without attribution.