Guideline: Triggering a Download
Luke Chesser avatar
Written by Luke Chesser
Updated over a week ago

From the API Guidelines:

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.

  "id": "LBI7cgq3pbM",
  "width": 5245,
  "height": 3497,
  "color": "#60544D",
  "urls": { ... },
  "user": { ... },
  "links": {
    "self": "",
    "html": "",
    "download": "", // don't use this property
    "download_location": "" // use this one ;)

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. Be sure to include any query parameters included in the URL (like the ixid).

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).

Some example pseudo-ish code using the unsplash-js library:

// user searches for 'dogs' and chooses to use the first result{ query: 'dogs' }).then(result => {
if (result.type === 'success') {
const firstPhoto = result.response.results[0];
    // do something with the image URLs, like embedding it in a hypothetical post
    $('').attr('src', firstPhoto['urls']['regular']);
    // trigger a download event{ downloadLocation: photo.links.download_location, });
Did this answer your question?