Unsplash
A server-side Javascript wrapper for working with the Unsplash API.
Before using the Unsplash API, you need to register as a developer and read the API Guidelines.
Quick start
Quick links to methods you're likely to care about:
- Get a list of new photos ?
- Get a random photo ?
- Trigger a photo download ?
- Search for a photo by keyword ?️♂️
Note: Every application must abide by the API Guidelines. Specifically, remember to hotlink images, attribute photographers, and trigger a download when appropriate.
Documentation
Installation
$ npm i --save unsplash-js
Dependencies
This library depends on fetch to make requests to the Unsplash API. For environments that don't support fetch, you'll need to provide a polyfill.
// ES Modules syntax
import fetch from 'node-fetch';
global.fetch = fetch;
// require syntax
const fetch = require('node-fetch');
global.fetch = fetch;
Usage
If you're using unsplash-js publicly in the browser, you'll need to proxy your requests through your server to sign the requests with the Access Key and/or Secret Key to abide by the API Guideline to keep keys confidential.
Creating an instance
To create an instance, simply provide an Object with your accessKey:
// ES Modules syntax
import Unsplash from 'unsplash-js';
// require syntax
const Unsplash = require('unsplash-js').default;
const unsplash = new Unsplash({ accessKey: "{APP_ACCESS_KEY}" });
const unsplash = new Unsplash({
accessKey: "{APP_ACCESS_KEY}",
// Optionally you can also configure a custom header to be sent with every request
headers: {
"X-Custom-Header": "foo"
},
// Optionally if using a node-fetch polyfill or a version of fetch which supports the timeout option, you can configure the request timeout for all requests
timeout: 500 // values set in ms
});
Credentials can be obtained from Unsplash Developers.
Error handling
unsplash.users.profile("naoufal")
.catch(err => {
// Your flawless error handling code
});
Instance Methods
All the instance methods below make use of the toJson helper method described below
search.photos(keyword, page, per_page, filters)
Get a list of photos matching the keyword.
Arguments, Argument, Type, Opt/Required, Default, ---, ---, ---, ---, keyword, string, Required, page, number, Optional, per_page, number, Optional, 10, filters, object, Optional, filters.orientation, string, Optional, filters.collections, array, Optional, Example
unsplash.search.photos("dogs", 1, 10, { orientation: "portrait" })
.then(toJson)
.then(json => {
// Your code
});
search.users(keyword, page, per_page)
Get a list of users matching the keyword.
Arguments, Argument, Type, Opt/Required, Default, ---, ---, ---, ---, keyword, string, Required, page, number, Optional, per_page, number, Optional, 10, Example
unsplash.search.users("steve", 1)
.then(toJson)
.then(json => {
// Your code
});
search.collections(keyword, page, per_page)
Get a list of collections matching the keyword.
Arguments, Argument, Type, Opt/Required, Default, ---, ---, ---, ---, keyword, string, Required, page, number, Optional, per_page, number, Optional, 10, Example
unsplash.search.collections("dogs", 1)
.then(toJson)
.then(json => {
// Your code
});
photos.listPhotos(page, perPage, orderBy)
Get a single page from the list of all photos.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, page, number, Optional, perPage, number, Optional, orderBy, string, Optional, latest, popular or oldest, Example
unsplash.photos.listPhotos(2, 15, "latest")
.then(toJson)
.then(json => {
// Your code
});
photos.getPhoto(id)
Retrieve a single photo.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, id, string, Required, Example
unsplash.photos.getPhoto("mtNweauBsMQ")
.then(toJson)
.then(json => {
// Your code
});
photos.getPhotoStats(id)
Retrieve a single photo's stats.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, id, string, Required, Example
unsplash.photos.getPhotoStats("mtNweauBsMQ")
.then(toJson)
.then(json => {
// Your code
});
photos.getRandomPhoto({ query, username, featured })
Retrieve a single random photo, given optional filters.
When using this function, It is recommended to double check the types of the parameters,
in particular for the parameters of type Array.
Arguments
Argument 1:
An Object containing the follow keys:, Argument, Type, Opt/Required, ---, ---, ---, query, string, Optional, username, string, Optional, featured, boolean, Optional, collections, Array, Optional, count, string, Optional, Example
unsplash.photos.getRandomPhoto({ username: "naoufal" })
.then(toJson)
.then(json => {
// Your code
});
photos.likePhoto(id)
Like a photo on behalf of the logged-in user. This requires the write_likes scope.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, id, string, Required, Example
unsplash.photos.likePhoto("mtNweauBsMQ")
.then(toJson)
.then(json => {
// Your code
});
photos.unlikePhoto(id)
Remove a user’s like of a photo.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, id, string, Required, Example
unsplash.photos.unlikePhoto("mtNweauBsMQ")
.then(toJson)
.then(json => {
// Your code
});
photos.downloadPhoto(photo)
Trigger a download of a photo as per the download tracking requirement of API Guidelines.
Note: this accepts a photo JSON object, not a URL string or photo ID. See the example below for how to pair it with other calls to trigger it.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, photo, json, Required, Example
unsplash.photos.getPhoto("mtNweauBsMQ")
.then(toJson)
.then(json => {
unsplash.photos.downloadPhoto(json);
});
// or if working with an array of photos
unsplash.search.photos("dogs", 1)
.then(toJson)
.then(json => {
unsplash.photos.downloadPhoto(json["results"][0]);
});
users.profile(username)
Retrieve public details on a given user.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, username, string, Required, Example
unsplash.users.profile("naoufal")
.then(toJson)
.then(json => {
// Your code
});
users.statistics(username, resolution, quantity)
Retrieve statistics for a given user.
Arguments, Argument, Type, Opt/Required, Notes, Default, ---, ---, ---, ---, ---, username, string, Required, resolution, string, Optional, Currently only days, days, quantity, string, Optional, 30, Example
unsplash.users.statistics("naoufal", "days", 30)
.then(toJson)
.then(json => {
// Your code
});
users.photos(username, page, perPage, orderBy, stats)
Get a list of photos uploaded by a user.
Arguments, Argument, Type, Opt/Required, Notes, Default, ---, ---, ---, ---, ---, username, string, Required, page, number, Optional, 1, perPage, number, Optional, 10, orderBy, string, Optional, latest, popular or oldest, latest, stats, boolean, Optional, false, Example
unsplash.users.photos("naoufal", 1, 10, "popular", false)
.then(toJson)
.then(json => {
// Your code
});
users.likes(username, page, perPage, orderBy)
Get a list of photos liked by a user.
Arguments, Argument, Type, Opt/Required, Notes, ---, ---, ---, ---, username, string, Required, page, number, Optional, perPage, number, Optional, orderBy, string, Optional, latest, popular or oldest, Example
unsplash.users.likes("naoufal", 2, 15, "popular")
.then(toJson)
.then(json => {
// Your code
});
users.collections(username, page, perPage, orderBy)
Get a list of collections created by the user.
Arguments, Argument, Type, Opt/Required, Notes, ---, ---, ---, ---, username, string, Required, page, number, Optional, perPage, number, Optional, orderBy, string, Optional, published or updated, Example
unsplash.users.collections("naoufal", 2, 15, "updated")
.then(toJson)
.then(json => {
// Your code
});
collections.listCollections(page, perPage, orderBy)
Get a single page from the list of all collections.
Arguments, Argument, Type, Opt/Required, Notes, ---, ---, ---, ---, page, number, Optional, perPage, number, Optional, orderBy, string, Optional, latest, popular or oldest, Example
unsplash.collections.listCollections(1, 10, "popular")
.then(toJson)
.then(json => {
// Your code
});
collections.getCollection(id)
Retrieve a single collection. To view a user’s private collections, the read_collections scope is required.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, id, number, Required, Example
unsplash.collections.getCollection(123456)
.then(toJson)
.then(json => {
// Your code
});
collections.getCollectionPhotos(id, orderBy)
Retrieve a collection’s photos.
Arguments, Argument, Type, Opt/Required, Notes, ---, ---, ---, ---, id, number, Required, page, number, Optional, perPage, number, Optional, orderBy, string, Optional, latest, popular or oldest, Example
unsplash.collections.getCollectionPhotos(123456, 1, 10, "popular")
.then(toJson)
.then(json => {
// Your code
});
collections.createCollection(title, description, private)
Create a new collection. This requires the write_collections scope.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, title, string, Required, description, string, Optional, private, boolean, Optional, Example
unsplash.collections.createCollection("Birds", "Wild birds from 'round the world", true)
.then(toJson)
.then(json => {
// Your code
});
collections.updateCollection(id, title, description, private)
Update an existing collection belonging to the logged-in user. This requires the write_collections scope.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, id, number, Required, title, string, Optional, description, string, Optional, private, boolean, Optional, Example
unsplash.collections.updateCollection(12345, "Wild Birds", "Wild birds from around the world", false)
.then(toJson)
.then(json => {
// Your code
});
collections.deleteCollection(id)
Delete a collection belonging to the logged-in user. This requires the write_collections scope.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, id, number, Required, Example
unsplash.collections.deleteCollection(88)
.then(toJson)
.then(json => {
// Your code
});
collections.addPhotoToCollection(collectionId, photoId)
Add a photo to one of the logged-in user’s collections. Requires the write_collections scope.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, collectionId, number, Required, photoId, string, Required, Example
unsplash.collections.addPhotoToCollection(88, 'abc1234')
.then(toJson)
.then(json => {
// Your code
});
collections.removePhotoFromCollection(collectionId, photoId)
Remove a photo from one of the logged-in user’s collections. Requires the write_collections scope.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, collectionId, number, Required, photoId, string, Required, Example
unsplash.collections.removePhotoFromCollection(88, 'abc1234')
.then(toJson)
.then(json => {
// Your code
});
collections.listRelatedCollections(collectionId)
Lists collections related to the provided one.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, collectionId, number, Required, Example
unsplash.collections.listRelatedCollections(88)
.then(toJson)
.then(json => {
// Your code
});
stats.total()
Get a list of download counts for all of Unsplash.
Arguments
N/A
Example
unsplash.stats.total()
.then(toJson)
.then(json => {
// Your code
});
When initializing an instance of Unsplash, you'll need to include your application's secretKey and callbackUrl as defined in the API documentation:
const unsplash = new Unsplash({
accessKey: "{APP_ACCESS_KEY}",
secret: "{APP_SECRET}",
callbackUrl: "{CALLBACK_URL}"
});
If you already have a bearer token, you can also provide it to the constructor:
const unsplash = new Unsplash({
accessKey: "{APP_ACCESS_KEY}",
secret: "{APP_SECRET}",
callbackUrl: "{CALLBACK_URL}",
bearerToken: "{USER_BEARER_TOKEN}"
});
Generate an authentication url with the scopes your app requires.
const authenticationUrl = unsplash.auth.getAuthenticationUrl([
"public",
"read_user",
"write_user",
"read_photos",
"write_photos"
]);
Now that you have an authentication url, you'll want to redirect the user to it.
location.assign(authenticationUrl);
After the user authorizes your app she'll be redirected to your callback url with a code querystring present. Request an access token using that code.
// The OAuth code will be passed to your callback url as a querystring
unsplash.auth.userAuthentication(query.code)
.then(toJson)
.then(json => {
unsplash.auth.setBearerToken(json.access_token);
});
For more information on the authroization workflow, consult the Unsplash Documentation.
auth.getAuthenticationUrl(scopes)
Build an OAuth url with requested scopes.
Arguments, Argument, Type, Opt/Required, Default, ---, ---, ---, ---, scopes, Array, Optional, ["public"], Example
const authenticationUrl = unsplash.auth.getAuthenticationUrl([
"public",
"read_user",
"write_user",
"read_photos",
"write_photos"
]);
auth.userAuthentication(code)
Retrieve a user's access token.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, code, string, Required, Example
unsplash.auth.userAuthentication("{OAUTH_CODE}")
.then(toJson)
.then(json => {
// Your code
});
auth.setBearerToken(accessToken)
Set a bearer token on the instance.
Arguments, Argument, Type, Opt/Required, ---, ---, ---, accessToken, string, Required, Example
unsplash.auth.setBearerToken("{BEARER_TOKEN}");
currentUser.profile()
Get the user’s profile.
Arguments
N/A
Example
unsplash.currentUser.profile()
.then(toJson)
.then(json => {
// Your code
});
currentUser.updateProfile(options)
Update the current user’s profile.
Arguments, Argument, Type, Opt/Required, Notes, ---, ---, ---, ---, options, Object, Required, Object with the following optional keys: username, firstName, lastName, email, url, location, bio, instagramUsername, Example
unsplash.currentUser.updateProfile({
username: "drizzy",
firstName: "Aubrey",
lastName: "Graham",
email: "drizzy@octobersveryown.com",
url: "http://octobersveryown.com",
location: "Toronto, Ontario, Canada",
bio: "Views from the 6",
instagramUsername: "champagnepapi"
})
.then(toJson)
.then(json => {
// Your code
});
Helpers
toJson(res)
Arguments, Argument, Type, Opt/Required, ---, ---, ---, res, Object, Required, Example
import Unsplash, { toJson } from "unsplash-js";
const unsplash = new Unsplash({
accessKey: "{YOUR_ACCESS_KEY}",
secret: "{YOUR_SECRET_KEY}"
});
unsplash.stats.total()
.then(toJson)
.then(json => {
// Your code
});