Unsplash Has a Free API — Search and Download HD Photos Programmatically

#discuss #api #webdev #javascript

Need free stock photos for your app? Unsplash has 4 million+ high-resolution photos, and their API lets you search and download them programmatically.

No watermarks. Free for commercial use. Here is how.

Get Your API Key (2 minutes)

Go to unsplash.com/developers
Create a new application
Copy your Access Key

Free tier: 50 requests/hour (enough for most use cases).

Search Photos

const ACCESS_KEY = 'your_access_key';

async function searchPhotos(query, perPage = 10) {
  const response = await fetch(
    `https://api.unsplash.com/search/photos?query=${query}&per_page=${perPage}`,
    { headers: { Authorization: `Client-ID ${ACCESS_KEY}` } }
  );
  const data = await response.json();

  return data.results.map(photo => ({
    id: photo.id,
    description: photo.description || photo.alt_description,
    url_small: photo.urls.small,
    url_regular: photo.urls.regular,
    url_full: photo.urls.full,
    photographer: photo.user.name,
    download_link: photo.links.download
  }));
}

const photos = await searchPhotos('mountain landscape');
photos.forEach(p => console.log(`${p.description} by ${p.photographer}`));

Get a Random Photo

import requests

def random_photo(query=None):
    params = {}
    if query:
        params['query'] = query

    response = requests.get(
        'https://api.unsplash.com/photos/random',
        headers={'Authorization': f'Client-ID {ACCESS_KEY}'},
        params=params
    )
    photo = response.json()
    return {
        'url': photo['urls']['regular'],
        'photographer': photo['user']['name'],
        'description': photo.get('description', 'No description')
    }

photo = random_photo('coding workspace')
print(f"Photo by {photo['photographer']}: {photo['url']}")

Perfect for dynamic backgrounds, placeholder images, or inspiration boards.

Download a Photo

import requests

def download_photo(photo_id, size='regular'):
    # Trigger download (required by Unsplash guidelines)
    requests.get(
        f'https://api.unsplash.com/photos/{photo_id}/download',
        headers={'Authorization': f'Client-ID {ACCESS_KEY}'}
    )

    # Get photo details
    response = requests.get(
        f'https://api.unsplash.com/photos/{photo_id}',
        headers={'Authorization': f'Client-ID {ACCESS_KEY}'}
    )
    photo = response.json()

    # Download the image
    img_url = photo['urls'][size]
    img_data = requests.get(img_url).content

    filename = f"{photo_id}.jpg"
    with open(filename, 'wb') as f:
        f.write(img_data)

    return filename

Important: Always trigger the download endpoint first. Unsplash uses this to track photo popularity and pay photographers.

Real Use Cases

Blog cover images — search by topic, auto-set as header
Design mockups — fill placeholders with real photos
Social media tools — auto-suggest images for posts
Wallpaper app — random daily wallpaper from Unsplash
E-commerce prototypes — realistic product photography placeholders

Attribution

Unsplash photos are free to use, but crediting photographers is appreciated:

Photo by <a href="https://unsplash.com/@photographer">Name</a> on <a href="https://unsplash.com">Unsplash</a>

What would you build with 4 million free photos?

I used this to auto-generate blog covers. What creative use would you find for an unlimited photo API?

I write about free APIs and developer tools. Follow for weekly discoveries.

More APIs: Wikipedia API | Spotify API

DEV Community