Have opinions about JavaScript? We want to hear them. Take the 2018 JavaScript Ecosystem Survey »

unsplash-js

4.8.0 • Public • Published

Unsplash

npm Travis Coveralls

A Universal JavaScript wrapper for the Unsplash API.

Before using the Unsplash API, you need to register as a developer and read the API Guidelines.

Browser Support

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

Quick start

Quick links to methods you're likely to care about:

Note: Every application must abide by the API Guidelines. Specifically, remember to hotlink images 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.

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

You can also provide headers that will be set on every request by providing them to the constructor.

const unsplash = new Unsplash({
  applicationId: "{APP_ID}",
  secret: "{APP_SECRET}",
  callbackUrl: "{CALLBACK_URL}",
  headers: {
    "X-Custom-Header": "foo"
  }
});

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

Sidenote

All the instance methods below make use of the toJson helper method described below


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

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

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
width number Optional
height number Optional
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]);
  });

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

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

install

npm i unsplash-js

Downloadsweekly downloads

6,382

version

4.8.0

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
  • avatar
Report a vulnerability