Add Beautiful Images with the Unsplash API

Perhaps you know Unsplash? I’d wager it’s the most popular stock photography site out there for two big reasons:
Every photo on there is pretty darn niceEvery photo is entirely free even for commercial use. You don’t have to ask permission or even credit it (although that’s appreciated).
Here’s something you might not know though: Unsplash has an API, and it’s unlimited and free. Brass tacks: it’s exactly what you hope it’s going to be. A really clean, well documented, well-performing, JSON API that gives you URLs to photos with metadata.
What would you use the Unsplash API for?
There are lots of examples on Unsplash’s developer area, from Medium to Squarespace to Trello, but here is another one of my favorites!
I use Notion every day. It’s a great app for note-taking, planning, and all sorts of stuff. One of the features it has is giving every document you create within it a custom image header. These give the documents some great personality. Notion has a handful you can choose from or you can upload your own. Or, you can search Unsplash for them!
How does that work? Lemme show you first:
They use the Unsplash API to do it and here’s an article about that. There is a search endpoint as part of the API that makes this quite easy to do.
For example, you’d hit a URL like:
https://api.unsplash.com/search/photos?page=1&query=SEARCH_QUERY
And you’ll get JSON back like:
{
total: 133,
total_pages: 7,
results: [
{
id: eOLpJytrbsQ,
created_at: 2014-11-18T14:35:36-05:00,
width: 4000,
height: 3000,
color: #A7A2A1,
likes: 286,
liked_by_user: false,
description: A man drinking a coffee.,
user: {
id: Ul0QVz12Goo,
username: ugmonk,
name: Jeff Sheldon,
first_name: Jeff,
last_name: Sheldon,
instagram_username: instantgrammer,
twitter_username: ugmonk,
portfolio_url: http://ugmonk.com/,
profile_image: {
small: https://images.unsplash.com/profile-1441298803695-accd94000cac?ixlib=rb-0.3.5&q=80&fm=jpg&crop=faces&cs=tinysrgb&fit=crop&h=32&w=32&s=7cfe3b93750cb0c93e2f7caec08b5a41,
medium: https://images.unsplash.com/profile-1441298803695-accd94000cac?ixlib=rb-0.3.5&q=80&fm=jpg&crop=faces&cs=tinysrgb&fit=crop&h=64&w=64&s=5a9dc749c43ce5bd60870b129a40902f,
large: https://images.unsplash.com/profile-1441298803695-accd94000cac?ixlib=rb-0.3.5&q=80&fm=jpg&crop=faces&cs=tinysrgb&fit=crop&h=128&w=128&s=32085a077889586df88bfbe406692202
},
links: {
self: https://api.unsplash.com/users/ugmonk,
html: http://unsplash.com/@ugmonk,
photos: https://api.unsplash.com/users/ugmonk/photos,
likes: https://api.unsplash.com/users/ugmonk/likes
}
},
current_user_collections: [],
urls: {
raw: https://images.unsplash.com/photo-1416339306562-f3d12fefd36f,
full: https://hd.unsplash.com/photo-1416339306562-f3d12fefd36f,
regular: https://images.unsplash.com/photo-1416339306562-f3d12fefd36f?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&s=92f3e02f63678acc8416d044e189f515,
small: https://images.unsplash.com/photo-1416339306562-f3d12fefd36f?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=400&fit=max&s=263af33585f9d32af39d165b000845eb,
thumb: https://images.unsplash.com/photo-1416339306562-f3d12fefd36f?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=200&fit=max&s=8aae34cf35df31a592f0bef16e6342ef
},
links: {
self: https://api.unsplash.com/photos/eOLpJytrbsQ,
html: http://unsplash.com/photos/eOLpJytrbsQ,
download: http://unsplash.com/photos/eOLpJytrbsQ/download
}
},
// more photos …
]
}
So to offer a search experience inside an app like Notion, you’d have a little search form and when users submit that search query, you’d hit the API with the value they entered, then loop over response.results using the response.results.urls.thumb to show the images returned. If the user picks one, you can use a higher-res URL to do something with and have access to all that photos metadata.
Hot tip! The URLs to photos are dynamic in that you can resize them, crop them, serve them in different formats, and even change the compression quality all from URL parameters. For example, changing size is like &w=200.
That is exactly what we do on CodePen
The purpose of CodePen Pen Editor is to provide an online code editor that makes it tremendously easy to code something up for the web, save it, and share it. Images are a big part of the web, so it’s very possible that you might want to use a gorgeous image in a Pen. We have Asset Hosting ourselves on CodePen as a PRO feature, but we also offer Unsplash images to everyone for free!
Check out how it works:
A basic example in React
Let’s make a search