Location

• The API is available at https://api.unsplash.com/. Responses are sent as JSON.

Public Actions

• Many actions can be performed without requiring authentication from a specific user. For example, downloading a photo does not require a user to log in.

• To authenticate requests in this way, pass your application’s access key via the HTTP Authorization header:

Authorization: Client-ID YOUR_ACCESS_KEY

• You can also pass this value using a client_id query parameter: https://api.unsplash.com/photos/?client_id=YOUR_ACCESS_KEY If only your access key is sent, attempting to perform non-public actions that require user authorization will result in a 401 Unauthorized response.

Link URL’s for the first, last, next, and previous pages are supplied, if applicable. They are comma-separated and differentiated with a rel attribute.

1. For example, after requesting page 3 of the photo list: **Link: <https://api.unsplash.com/photos?page=1>; rel="first", *<https://api.unsplash.com/photos?page=2>; rel="prev", *<https://api.unsplash.com/photos?page=346>; rel="last", *<https://api.unsplash.com/photos?page=4>; rel="next"

• We officially support the parameters:
• w, h: for adjusting the width and height of a photo.
• crop: for applying cropping to the photo.
• fm: for converting image format.
• auto=format: for automatically choosing the optimal image format depending on user browser.
• q: for changing the compression quality when using lossy file formats.
• fit: for changing the fit of the image within the specified dimensions.
• dpi: for adjusting the device pixel ratio of the image.

• query Search terms.
• page Page number to retrieve. (Optional; default: 1)
• per_page Number of items per page. (Optional; default: 10)
• collections Collection ID(‘s) to narrow search. If multiple, comma-separated.
• orientation Filter search results by photo orientation. Valid values are landscape, portrait, and squarish.

• The photo objects returned here are abbreviated. For full details use GET /photos/:id 200 OK Link: <https://api.unsplash.com/search/photos?page=1&query=office>; rel="first", <https://api.unsplash.com/search/photos? page=1&query=office>; rel="prev", <https://api.unsplash.com/search/photos?page=3&query=office>; rel="last",https://api.unsplash.com/search/photos?page=3&query=office>; rel="next" X-Ratelimit-Limit: 1000 X-Ratelimit-Remaining: 999

Get a random photo

1. Retrieve a single random photo, given optional filters.

GET /photos/random

1. Note: See the note on hotlinking.

Parameters

1. All parameters are optional, and can be combined to narrow the pool of photos from which a random one will be chosen.

param Description

1. collections Public collection ID(‘s) to filter selection. If multiple, comma-separated
2. featured Limit selection to featured photos.
3. username Limit selection to a single user.
4. query Limit selection to photos matching a search term.
5. orientation Filter search results by photo orientation. Valid values are landscape, portrait, and squarish.
6. count The number of photos to return. (Default: 1; max: 30)