Cofounder of @unsplash—the world’s largest, most beautiful collection of free photos. Built probably the world’s most beautiful café and coworking space.

Nov 29, 2017

Unsplash API Guidelines: Triggering a Download

When your application performs something similar to a download (like when a user chooses the image to include in a blog post, set as a header, etc.), you must send a request to the download endpoint returned under the photo.links.download_location property.

Downloads and views are one of the main motivations for many Unsplash contributors. By opening up the Unsplash API to 3rd party applications their photography is seen and used by more users which inspires them to contribute more, other contributors to join, and an even better library for you and your community of creatives.

Every photo has a unique download link that exists on the photo.links.download_location field included with all photos.

When calling the download_location endpoint, be sure to authorize the call (either include your client_id or the user’s bearer token). Otherwise you will get a 401.

An action “similar to a download of an image” can be thought of as an action where a user does something with the photo, usually inserting or setting it somewhere.

Some examples from our own API applications:

on Unsplash Wallpapers, when a user sets the photo as their wallpaper we trigger the download endpoint for the photo

on Unsplash for Google Slides, when a user chooses a photo to insert into their presentation we trigger the download endpoint for the photo

Some examples from 3rd party applications:

on Craft by Invision, when a user inserts a photo into Sketch or Photoshop, the download endpoint is triggered

on Ghost, when a user inserts a photo into a blog post, the download endpoint is triggered

on Trello, when a user chooses a photo as a background for their board, the download endpoint is triggered

on Over, when a user selects a photo to remix, the download endpoint is triggered

We’ve found that it’s best to trigger the endpoint asynchronously to make sure that it doesn’t slow down your user’s interactions.

Note: this is purely an event endpoint used to increment the number of downloads a photo has. You can think of it very similarly to the pageview event in Google Analytics—where you’re incrementing a counter on the backend. The download_location is not to be used to embed the photo (use the photo.urls.* properties instead) or to direct the user downloading the photo to (use the photo.urls.full for that instead).