Unsplash

Official Javascript wrapper for the Unsplash API.

Key Links:

• Before using the Unsplash API, register as a developer.
• Before using the Unsplash API, read the API Guidelines. Specifically, you must:
  • hotlink images
  • attribute photographers
  • trigger a download when appropriate
• Once you create an application and have an access key, go try the demos:
  • javascript
  • typescript

Documentation

• Installation
• Dependencies
• Usage
• Types
• Instance Methods

Installation

$ npm i --save unsplash-js

# OR

$ yarn add unsplash-js

Dependencies

Fetch

This library depends on fetch to make requests to the Unsplash API. For environments that don't support fetch, you'll need to provide polyfills of your choosing. Here are the ones we recommend:

• node implementation: node-fetch
• browser polyfill: whatwg-fetch

Adding polyfills

createApi receives an optional fetch parameter. When it is not provided, we rely on the globally scoped fetch.

This means that you can set the polyfills in the global scope:

// server
import fetch from 'node-fetch';
global.fetch = fetch;

// browser
import 'whatwg-fetch';

or explicitly provide them as an argument:

import { createApi } from 'unsplash-js';
import nodeFetch from 'node-fetch';

const unsplash = createApi({
  accessKey: 'MY_ACCESS_KEY',
  fetch: nodeFetch,
});

Note: we recommend using a version of node-fetch higher than 2.4.0 to benefit from Brotli compression.

node-fetch and global types

This library presumes that the following types exist in the global namespace:

• fetch
• RequestInit
• Response

By default TypeScript defines these via the "dom" type definitions.

However, if you're targeting Node and you're using node-fetch you should omit the "dom" type definitions using the lib compiler option and then define the required global types manually like so:

import { createApi } from 'unsplash-js';
import * as nodeFetch from 'node-fetch'

declare global {
  var fetch: typeof nodeFetch.default;
  type RequestInit = nodeFetch.RequestInit;
  type Response = nodeFetch.Response;
}
global.fetch = nodeFetch.default;

const unsplash = createApi({
  accessKey: 'MY_ACCESS_KEY',
  fetch: nodeFetch.default,
});

Unfortunately this won't work with node-fetch v3 due to an issue in node-fetch, whereby the global namespace is polluted with the "dom" type definitions: https://github.com/node-fetch/node-fetch/issues/1285.

As a workaround you use a type assertion:

import { createApi } from 'unsplash-js';
import * as nodeFetch from 'node-fetch'

const unsplash = createApi({
  accessKey: 'MY_ACCESS_KEY',
  fetch: nodeFetch.default as unknown as typeof fetch,
});

URL

This library also depends on the WHATWG URL interface:

• MDN docs for browsers.
• NodeJS docs.

Note: Make sure to polyfill this interface if targetting older environments that do not implement it (i.e. Internet Explorer or Node < v8).

Note 2: For Node, the URL interface exists under require('url').URL since v8 but was only added to the global scope as of v10.0.0. If you are using a version between v8.0.0 and v10.0.0, you need to add the class to the global scope before using unsplash-js:

URL = require('url').URL;

Usage

Creating an instance

To create an instance, simply provide an Object with your accessKey.

NOTE: 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 to abide by the API Guideline to keep keys confidential. We provide an apiUrl property that lets you do so. You should only need to provide one of those two values in any given scenario.

import { createApi } from 'unsplash-js';

// on your node server
const serverApi = createApi({
  accessKey: 'MY_ACCESS_KEY',
  //...other fetch options
});

// in the browser
const browserApi = createApi({
  apiUrl: 'https://mywebsite.com/unsplash-proxy',
  //...other fetch options
});

Making a request

Arguments

All methods have 2 arguments: the first one includes all of the specific parameters for that particular endpoint, while the second allows you to pass down any additional options that you want to provide to fetch. On top of that, the createApi constructor can receive fetch options to be added to every request:

const unsplash = createApi({
  accessKey: 'MY_ACCESS_KEY',
  // `fetch` options to be sent with every request
  headers: { 'X-Custom-Header': 'foo' },
});

unsplash.photos.get(
  { photoId: '123' },
  // `fetch` options to be sent only with _this_ request
  { headers: { 'X-Custom-Header-2': 'bar' } },
);

Example: if you would like to implement request abortion, you can do so like this:

const unsplash = createApi({
  accessKey: 'MY_ACCESS_KEY',
});

const controller = new AbortController();
const signal = controller.signal;

unsplash.photos.get({ photoId: '123' }, { signal }).catch(err => {
  if (err.name === 'AbortError') {
    console.log('Fetch aborted');
  }
});

controller.abort();

Response

When making a request using this SDK, there are 2 possible outcomes to a request.

• Error: we return a result.errors object containing an array of strings (each one representing one error) and result.source describing the origin of the error (e.g. api, decoding). Typically, you will only have on item in this array.
• Success: we return a result.response object containing the data.
  • If the request is for a page from a feed, then result.response.results will contain the JSON received from API, and result.response.total will contain the X-total header value indicating the total number of items in the feed (not just the page you asked for).
  • If the request is something other than a feed, then result.response will contain the JSON received from API

You can inspect which one you have by reading the result.type value or checking the contents of result.errors/result.success

const unsplash = createApi({ accessKey: 'MY_ACCESS_KEY' });

// non-feed example
unsplash.photos.get({ photoId: 'foo' }).then(result => {
  if (result.errors) {
    // handle error here
    console.log('error occurred: ', result.errors[0]);
  } else {
    // handle success here
    const photo = result.response;
    console.log(photo);
  }
});

// feed example
unsplash.users.getPhotos({ username: 'foo' }).then(result => {
  if (result.errors) {
    // handle error here
    console.log('error occurred: ', result.errors[0]);
  } else {
    const feed = result.response;

    // extract total and results array from response
    const { total, results } = feed;

    // handle success here
    console.log(`received ${results.length} photos out of ${total}`);
    console.log('first photo: ', results[0]);
  }
});

NOTE: you can also pattern-match on result.type whose value will be error or success:

unsplash.photos.get({ photoId: 'foo' }).then(result => {
  switch (result.type) {
    case 'error':
      console.log('error occurred: ', result.errors[0]);
    case 'success':
      const photo = result.response;
      console.log(photo);
  }
});

Types

The types for this library target TypeScript v3.7 and above.

This library is written in TypeScript. This means that even if you are writing plain JavaScript, you can still get useful and accurate type information. We highly recommend that you setup your environment (using an IDE such as VSCode) to fully benefit from this information:

Function arguments

Response Types

Instance Methods

NOTE: All of the method arguments described here are in the first parameter. See the arguments section for more information.

• Search
• Photos
• Users
• Collections
• Topics

unsplash.search.getPhotos({
  query: 'cat',
  page: 1,
  perPage: 10,
  color: 'green',
  orientation: 'portrait',
});

unsplash.search.getUsers({
  query: 'cat',
  page: 1,
  perPage: 10,
});

unsplash.search.getCollections({
  query: 'cat',
  page: 1,
  perPage: 10,
});

unsplash.photos.list({});
unsplash.photos.list({ page: 2, perPage: 15 });

unsplash.photos.get({ photoId: 'mtNweauBsMQ' });

unsplash.photos.getStats({ photoId: 'mtNweauBsMQ' });

unsplash.photos.getRandom({});
unsplash.photos.getRandom({
  count: 10,
});
unsplash.photos.getRandom({
  collectionIds: ['abc123'],
  topicIds: ['def456'],
  featured: true,
  username: 'naoufal',
  query: 'dog',
  count: 1,
});

unsplash.photos.get({ photoId: 'mtNweauBsMQ' }).then(result => {
  if (result.type === 'success') {
    const photo = result.response;
    unsplash.photos.trackDownload({
      downloadLocation: photo.links.download_location,
    });
  }
});

// or if working with an array of photos
unsplash.search.photos({ query: 'dogs' }).then(result => {
  if (result.type === 'success') {
    const firstPhoto = result.response.results[0];
    unsplash.photos.trackDownload({
      downloadLocation: firstPhoto.links.download_location,
    });
  }
});

unsplash.users.get({ username: 'naoufal' });

unsplash.users.getPhotos({
  username: 'naoufal',
  page: 1,
  perPage: 10,
  orderBy: 'latest',
  orientation: 'landscape',
});

unsplash.users.getLikes({
  username: 'naoufal',
  page: 1,
  perPage: 10,
  orderBy: 'latest',
  orientation: 'landscape',
});

unsplash.users.getCollections({
  username: 'naoufal',
  page: 2,
  perPage: 15,
});

unsplash.collections.list({ page: 1, perPage: 10 });

unsplash.collections.get({ collectionId: 'abc123' });

unsplash.collections.getPhotos({ collectionId: 'abc123' });

unsplash.collections.getRelated({ collectionId: 'abc123' });

unsplash.topics.list({
  page: 1,
  perPage: 10,
  topicIdsOrSlugs: ['fashion', 'architecture', '6sMVjTLSkeQ'],
});

unsplash.topics.get({ topicIdOrSlug: 'abc123' });

unsplash.topics.getPhotos({ topicIdOrSlug: 'abc123' });

Changelog

7.0.3

• Adds response types to all endpoints.

7.0.0

This version includes a total TypeScript rewrite of the library, with many breaking changes. If upgrading from a previous version, read carefully. You will not be able to upgrade to v7 without making the necessary adjustments.

Breaking Changes

• Replaces the Unsplash class with a named createApi function:

// before
import Unsplash from 'unsplash-js';
const unsplash = new Unsplash({ accessKey: 'MY_ACCESS_KEY' });

// after
import { createApi } from 'unsplash-js';
const unsplash = createApi({ accessKey: 'MY_ACCESS_KEY' });
// or
import Unsplash from 'unsplash-js';
const unsplash = Unsplash.createApi({ accessKey: 'MY_ACCESS_KEY' });

• Removes user authentication features from the library. This means that the createApi function does not recieve secret, callbackUrl or bearerToken.

• Removes the following API methods (primarily due to removal of user authentication):

  • photos:
    • ❌ likePhoto
    • ❌ unlikePhoto
    • ❌ downloadPhoto (deprecated in 6.3, replaced with trackDownload)
  • users:
    • ❌ statistics
  • collections:
    • ❌ createCollection
    • ❌ updateCollection
    • ❌ deleteCollection
    • ❌ addPhotoToCollection
    • ❌ removePhotoFromCollection
  • auth:
    • ❌ getAuthenticationUrl
    • ❌ userAuthentication
    • ❌ setBearerToken
  • currentUser:
    • ❌ profile
    • ❌ updateProfile
  • stats:
    • ❌ total
  • ❌ toJson (the library now takes care of converting the response to JSON).

• Renames all of the remaining API methods:

  • search:
    • ⚠️ photos --> getPhotos
    • ⚠️ users --> getUsers
    • ⚠️ collections --> getCollections
  • photos:
    • ⚠️ listPhotos --> list
    • ⚠️ getPhoto --> get
    • ⚠️ getRandomPhoto --> getRandom
    • ⚠️ getPhotoStats --> getStats
  • users:
    • ⚠️ profile --> get
    • ⚠️ photos --> getPhotos
    • ⚠️ likes --> getLikes
    • ⚠️ collections --> getCollections
  • collections:
    • ⚠️ listCollections --> list
    • ⚠️ getCollection --> get
    • ⚠️ getCollectionPhotos --> getPhotos
    • ⚠️ listRelatedCollections --> listRelated

• Changes the format of the parameters for all API methods. They are now all named parameters within the first argument, instead of multiple arguments. Check the TypeScript types and the Arguments section of the docs for the new parameters format.

• Changes the format of the responses for all API methods. The JSON is now parsed and returned, removing the need for the toJson helper. Feeds have the "x-total" header added to the response. The library now also performs error-handling: expected errors are returned instead of thrown, along with a description of their source. Check the TypeScript types and the Response section of the docs for the new response format.

Changes

• TypeScript support! Everything is now accurately typed (except responses which we plan to add types for soon).
• You can now provide fetch options on a per-call basis using the second parameter. See Arguments.

6.3.0

Changes

• Deprecate photos.downloadPhoto in favor of photos.trackDownload to better clarify method usage. downloadPhoto will continue to be supported until version 7.0.

6.2.0

Changes

• Adds support for the languages beta on search

unsplash.search.photos('nature', 1, 10, { lang: 'en' });

• Adds support for the new search filters and ordering

unsplash.search.photos('nature', 1, 10, {
  orientation: 'landscape',
  color: 'green', // new
  orderBy: 'relevant', // new
});

• Adds support for content filtering on search

unsplash.search.photos('nature', 1, 10, { contentFilter: 'high' });

• Removes any references to 'popular' ordering (due to deprecation)

6.1.0

Enables Brotli compression by default.

6.0

Changes

• To better clarify the use of accessKey when initializing, applicationId has been renamed to accessKey:

  // previously
  const unsplash = new Unsplash({
    applicationId: '{APP_ACCESS_KEY}',
  });
  
  // now
  const unsplash = new Unsplash({
    accessKey: '{APP_ACCESS_KEY}',
  });

• unsplash.photos.getPhotoStats now uses the /photos/:id/statistics endpoint (changelog reference)

• To support additional filters, the unsplash.search.photos method signature has been changed to support an optional filters object, which currently supports collections and orientation keys.

unsplash.search.photos('nature', 1, 10, { orientation: 'landscape', collections: [1, 2] });

Removals

6.0 removes deprecated endpoints and parameters to match the changes from the Unsplash API Changelog. Most of these endpoints have been deprecated on the API and removed from unsplash-js documentation for 2+ years.