A Universal JavaScript wrapper for the Unsplash API
JavaScript
Latest commit 3dd7343 Jan 17, 2017 @joshwcomeau joshwcomeau v4.5.0

README.md

Unsplash

npm Travis Coveralls

A Universal JavaScript wrapper for the Unsplash API.

Browser Support

Chrome Firefox Safari Opera IE
Latest ✔ Latest ✔ Latest ✔ Latest ✔ 10+ ✔

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.

Usage

Creating an instance

To create an instance, simply provide an Object with your applicationId, secret and callbackUrl.

import Unsplash from 'unsplash-js';

const unsplash = new Unsplash({
  applicationId: "{APP_ID}",
  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({
  applicationId: "{APP_ID}",
  secret: "{APP_SECRET}",
  callbackUrl: "{CALLBACK_URL}",
  bearerToken: "{USER_BEARER_TOKEN}"
});

Credentials can be obtained from Unsplash Developers.

React Native

For use with React Native, import from unsplash-js/native instead.

import Unsplash from 'unsplash-js/native';

Authorization workflow

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.


Error handling

unsplash.users.profile("naoufal")
  .catch(err => {
    // Your flawless error handling code
  });

Instance Methods

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
  });

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.photos(username, page, perPage, orderBy)

Get a list of photos uploaded 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.photos("naoufal", "popular")
  .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)

Get a list of collections created by the user.

Arguments

Argument Type Opt/Required Notes
username string Required
page number Optional
perPage number Optional

Example

unsplash.users.collections("naoufal", 2, 15)
  .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

Example

unsplash.photos.listPhotos(2, 15, "latest")
  .then(toJson)
  .then(json => {
    // Your code
  });

photos.listCuratedPhotos(page, perPage, orderBy)

Get a single page from the list of the curated photos.

Arguments

Argument Type Opt/Required
page number Optional
perPage number Optional
orderBy string Optional

Example

unsplash.photos.listCuratedPhotos(2, 15, "latest")
  .then(toJson)
  .then(json => {
    // Your code
  });

photos.searchPhotos(query, category, page, perPage)

Get a single page from a photo search. Optionally limit your search to a set of categories by supplying the category ID’s.

Arguments

Argument Type Opt/Required
query string Optional
category Array Optional
page number Optional
perPage number Optional

Example

unsplash.photos.searchPhotos("cats", [11, 88], 1, 15)
  .then(toJson)
  .then(json => {
    // Your code
  });

photos.getPhoto(id, width, height, rectangle)

Retrieve a single photo.

Arguments

Argument Type Opt/Required
id string Required
width number Optional
height number Optional
rectangle Array Optional

Example

unsplash.photos.getPhoto("mtNweauBsMQ", 1920, 1080, [0, 0, 1920, 1080])
  .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({ width, height, query, username, featured, category })

Retrieve a single random photo, given optional filters.

Arguments

An Object containing the follow keys:

Argument Type Opt/Required
width number Optional
height number Optional
query string Optional
username string Optional
featured boolean Optional
category Array Optional

Example

unsplash.photos.getRandomPhoto({ username: "naoufal" })
  .then(toJson)
  .then(json => {
    // Your code
  });

photos.uploadPhoto(photo)

Upload a photo on behalf of the logged-in user. This requires the write_photos scope.

Arguments

Argument Type Opt/Required
photo Image Binary Required

Example

import { createReadStream } from "fs";

unsplash.photos.uploadPhoto(createReadStream(__dirname + "path/to/image"))
  .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
  });

categories.listCategories()

Get a list of all photo categories.

Arguments

N/A

Example

unsplash.categories.listCategories()
  .then(toJson)
  .then(json => {
    // Your code
  });

categories.category(id)

Retrieve a single category.

Arguments

Argument Type Opt/Required
id string Required

Example

unsplash.categories.category(4)
  .then(toJson)
  .then(json => {
    // Your code
  });

categories.categoryPhotos(id, page, perPage)

Retrieve a single category’s photos.

Arguments

Argument Type Opt/Required
id string Required
page number Optional
perPage number Optional

Example

unsplash.categories.categoryPhotos(4, 3, 15)
  .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.listCuratedCollections(page, perPage)

Get a single page from the list of curated collections.

Arguments

Argument Type Opt/Required
page number Optional
perPage number Optional

Example

unsplash.collections.listCuratedCollections(1, 10)
  .then(toJson)
  .then(json => {
    // Your code
  });

collections.listFeaturedCollections(page, perPage)

Get a single page from the list of featured collections.

Arguments

Argument Type Opt/Required
page number Optional
perPage number Optional

Example

unsplash.collections.listFeaturedCollections(1, 10)
  .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.getCuratedCollection(id)

Or, for a curated collection:

Arguments

Argument Type Opt/Required
id number Required

Example

unsplash.collections.getCuratedCollection(88)
  .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.getCuratedCollectionPhotos(id, orderBy)

Or, for a curated collection:

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.getCuratedCollectionPhotos(88, 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
  });