Unsplash API Documentation

Create with the world's most powerful photo engine

Getting Started with Unsplash API

The Unsplash API is a modern JSON API that serves the most powerful photo engine in the world. It's used by tens of thousands of developers to power their apps, including some of the biggest names in tech.

Key Features

Access to millions of high-resolution photos
Powerful search functionality
Photo statistics and download tracking
User authentication and interaction
Collections and curated photo lists
Topic-based photo discovery

Authentication

To use the Unsplash API, you need to register as a developer:

Create an Unsplash account at https://unsplash.com/join
Go to your applications page
Click "New Application" and fill in the required details
You'll receive your Access Key and Secret Key

Note: Keep your Secret Key confidential. Never expose it in client-side code or public repositories.

Making Requests

All requests should be made to the base URL: https://api.unsplash.com/

Include your Access Key in the Authorization header:

Authorization: Client-ID YOUR_ACCESS_KEY

Core Endpoints

GET /photos

Get a single page from the list of all photos


GET https://api.unsplash.com/photos

GET /photos/random

Retrieve a random photo


GET https://api.unsplash.com/photos/random

GET /search/photos

Search for photos


GET https://api.unsplash.com/search/photos?query=nature

Key Parameters for Search

Parameter	Description
query	Search terms
page	Page number to retrieve (default: 1)
per_page	Number of items per page (default: 10)
order_by	How to sort the photos (relevance, latest)
collections	Collection ID('s) to narrow search
content_filter	Limit results by content safety (low, high)
color	Filter by color (black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue)
orientation	Filter by photo orientation (landscape, portrait, squarish)

Example Response


{
  "id": "Dwu85P9SOIk",
  "created_at": "2016-05-03T11:00:28-04:00",
  "updated_at": "2016-07-10T11:00:01-05:00",
  "width": 2448,
  "height": 3264,
  "color": "#6E633A",
  "blur_hash": "LFC$yHwc8^$yIAS$%M%00KxukYIp",
  "downloads": 1345,
  "likes": 24,
  "liked_by_user": false,
  "description": "A man drinking a coffee.",
  "exif": {
    "make": "Canon",
    "model": "Canon EOS 40D",
    "exposure_time": "0.011111111111111112",
    "aperture": "4.970854",
    "focal_length": "37",
    "iso": 100
  },
  "location": {
    "name": "Montreal, Canada",
    "city": "Montreal",
    "country": "Canada",
    "position": {
      "latitude": 45.473298,
      "longitude": -73.638488
    }
  },
  "urls": {
    "raw": "https://images.unsplash.com/photo-1417325384643-aac51acc9e5d",
    "full": "https://images.unsplash.com/photo-1417325384643-aac51acc9e5d?q=75&fm=jpg",
    "regular": "https://images.unsplash.com/photo-1417325384643-aac51acc9e5d?q=75&fm=jpg&w=1080&fit=max",
    "small": "https://images.unsplash.com/photo-1417325384643-aac51acc9e5d?q=75&fm=jpg&w=400&fit=max",
    "thumb": "https://images.unsplash.com/photo-1417325384643-aac51acc9e5d?q=75&fm=jpg&w=200&fit=max"
  },
  "links": {
    "self": "https://api.unsplash.com/photos/Dwu85P9SOIk",
    "html": "https://unsplash.com/photos/Dwu85P9SOIk",
    "download": "https://unsplash.com/photos/Dwu85P9SOIk/download"
  },
  "user": {
    "id": "QPxL2MGqfrw",
    "updated_at": "2016-07-10T11:00:01-05:00",
    "username": "exampleuser",
    "name": "Joe Example",
    "portfolio_url": "https://example.com/",
    "bio": "Just an everyday Joe",
    "location": "Montreal",
    "total_likes": 5,
    "total_photos": 10,
    "total_collections": 13,
    "links": {
      "self": "https://api.unsplash.com/users/exampleuser",
      "html": "https://unsplash.com/@exampleuser",
      "photos": "https://api.unsplash.com/users/exampleuser/photos",
      "likes": "https://api.unsplash.com/users/exampleuser/likes",
      "portfolio": "https://api.unsplash.com/users/exampleuser/portfolio"
    }
  }
}

Image Examples

Tropical Beach

By: John Doe

Mountain Vista

By: Jane Smith

City Lights

By: Alex Johnson

Rate Limits

The Unsplash API has the following rate limits:

50 requests per hour for demo applications
5000 requests per hour for production applications

Rate limit information is included in the response headers.

Ready to start using the Unsplash API?