Unsplash is a stock photography site whose appeal rests on two properties: the photos are good, and they are free for any use, commercial included, with neither permission nor credit required. Less widely known is that Unsplash publishes an API. It is free and unlimited, and it returns JSON: photo URLs plus metadata.
What the search endpoint returns
Unsplash's documentation lists a search endpoint aimed at creating a search experience inside your app: supply a search query and you get photos back, which is how Notion populates its document header images.
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 ...
]
}
A search form inside an app submits the user's query to that endpoint, loops over response.results, and shows each response.results.urls.thumb. The higher-resolution URL and all of a photo's metadata are available for the image the user picks.
URLs are parameters, not fixed assets
The photo URLs are dynamic, configurable through URL parameters. You can resize and crop, change format, and alter compression quality. Size, for instance, is &w=200.
Where it fits: Notion and CodePen
Notion uses the search endpoint for its document header images. In CodePen's Pen Editor, images ship as part of the editor's purpose — an online code editor for coding something up for the web, saving it and sharing it, where an excellent image is often part of the content. Asset Hosting is a PRO feature on CodePen; Unsplash images are offered to everyone free.
A minimal React client
- A search
<form>submits, hits the Unsplash API, and returns photos. - Ajax is handled with Superagent.
- The current search query and the returned data live in state.
Candidate integrations
- Apps in which users create something could add cover images, background images or images for blog posts. Existing partners illustrate the range.
- An avatar-choosing experience could use the same source.
- A plugin could add quicker access to photos inside an app that already exists.



