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:
  • typescript

Documentation

• Installation
• Usage
• Replacing fetch
• Types
• Endpoint examples

Installation

$ npm i --save unsplash-js

# OR

$ yarn add unsplash-js

# OR

$ pnpm add unsplash-js

Usage

Creating an instance

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

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({
  baseUrl: "https://mywebsite.com/unsplash-proxy",
  //...other fetch options
});

NOTE: If you're using unsplash-js in the browser, you must proxy your requests through your server by setting baseUrl. This is to authenticate requests with your Access Key to abide by the API Guideline, and keeps your keys confidential. If baseUrl is set, accessKey is unnecessary and vice-versa.

Making a request

createApi returns an instance whose methods each accept a params object and standard fetch options.

Each method is named after an HTTP verb (GET, POST, DELETE, PUT, PATCH).

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

unsplash.GET("/photos/{assetSlug}", {
  params: { path: { assetSlug: "123" } },
});

Global fetch options can be set on the constructor; per-request fetch options override them:

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

unsplash.GET("/photos/{assetSlug}", {
  params: { path: { assetSlug: "123" } },
  // `fetch` options to be sent with only this request
  headers: { "X-Custom-Header-2": "bar" },
});

Example: Using an AbortController on a specific request:

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

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

unsplash
  .GET("/photos/{assetSlug}", {
    params: { path: { assetSlug: "123" } },
    signal,
  })
  .catch((err) => {
    if (err.name === "AbortError") {
      console.log("Fetch aborted");
    }
  });

controller.abort();

Response

There are two possible outcomes to a request:

1. You received data: result.data is present and populated.
2. The server returned an error: result.error is present and contains error details.

If you'd like to inspect the full response, result.response contains the raw Response object. You can use this to get the X-Total header value on feed responses, for example.

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

// non-feed example
const result = await unsplash.GET("/photos/{assetSlug}", {
  params: { path: { assetSlug: "foo" } },
});

if (result.error) {
  // handle error here
  console.log("error occurred: ", result.error.errors[0]);
} else {
  // handle success here
  const photo = result.data;
  console.log(photo);
}

// feed example
const result = await unsplash.GET("/users/{username}/photos", {
  params: { path: { username: "foo" } },
});

if (result.error) {
  // handle error here
  console.log("error occurred: ", result.error.errors[0]);
} else {
  // extract total and results array from response
  const feed = result.data;
  const total = parseInt(result.response.headers.get("x-total"));

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

NOTE: All usual fetch exceptions can get thrown when making requests using this library.

Authentication

When using the accessKey parameter on the createApi constructor, the Authorization header will be automatically set to use public authentication.

If you need to use either the user authentication or dynamic client registration scheme, set the Authorization header on each request according to the requirements of the authentication method you've chosen.

Replacing fetch

This is useful when mocking fetch in tests, targeting an older runtime, or providing a custom fetch implementation.

Fetch can be replaced globally or as an argument to createApi.

// Globally

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

// browser
import "whatwg-fetch";

// As an argument to `createApi`

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

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

See the openapi-fetch documentation for more information.

Types

The types for this library target TypeScript v4.5 and above.

This library is written in TypeScript, which 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 editor such as VSCode) to fully benefit from type hinting:

Request completion

Response completion

Endpoint examples

createApi returns a preconfigured openapi-fetch instance whose methods correspond to the usual HTTP verbs (.GET, .POST, .PUT, .DELETE, .PATCH).

For a full list of Unsplash's public endpoints, see the API documentation.

The endpoints covered here are grouped by category:

• Search
• Photos
• Users
• Collections
• Topics

For a full list of all available endpoints and their parameters, see the OpenAPI spec.

.GET("/search/photos", { params: { ... }})

Get a list of photos matching the query. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | Note | | -------------------- | -------- | ----------------------------------------- | ----------------- | ---------- | ---------------------------------------------------------- | | query | query | string | Required | | | | page | query | number | Optional | 1 | | | per_page | query | number | Optional | 10 | | | orientation | query | "portrait" | "landscape" | "squarish" | Optional | | | | content_filter | query | "low" | "high" | Optional | "low" | | | color | query | string | Optional | | see https://unsplash.com/documentation#search-photos | | order_by | query | "latest" | "relevant" | Optional | "relevant" | | | collections | query | Array | Optional | | | | lang | query | string | Optional | "en" | see https://unsplash.com/documentation#supported-languages |

Example

const { data, error } = await unsplash.GET("/search/photos", {
  params: {
    query: {
      query: "cat",
      page: 1,
      per_page: 10,
      color: "green",
      orientation: "portrait",
    },
  },
});

.GET("/search/users", { params: { ... }})

Get a list of users matching the query. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | | -------------- | -------- | -------- | ----------------- | ------- | | query | query | string | Required | | | page | query | number | Optional | 1 | | per_page | query | number | Optional | 10 |

Example

const { data, error } = await unsplash.GET("/search/users", {
  params: {
    query: {
      query: "cat",
      page: 1,
      per_page: 10,
    },
  },
});

.GET("/search/collections", { params: { ... }})

Get a list of collections matching the query. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | | -------------- | -------- | -------- | ----------------- | ------- | | query | query | string | Required | | | page | query | number | Optional | 1 | | per_page | query | number | Optional | 10 |

Example

const { data, error } = await unsplash.GET("/search/collections", {
  params: {
    query: {
      query: "cat",
      page: 1,
      per_page: 10,
    },
  },
});

.GET("/photos", { params: { ... }})

Get a single page from the list of all photos. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | | -------------- | -------- | -------- | ----------------- | ------- | | page | query | number | Optional | 1 | | per_page | query | number | Optional | 10 |

Example

const { data, error } = await unsplash.GET("/photos", {
  params: {
    query: { page: 2, per_page: 15 },
  },
});

.GET("/photos/{assetSlug}", { params: { ... }})

Retrieve a single photo. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | | --------------- | -------- | -------- | ----------------- | | assetSlug | path | string | Required |

Example

const { data, error } = await unsplash.GET("/photos/{assetSlug}", {
  params: {
    path: { assetSlug: "mtNweauBsMQ" },
  },
});

.GET("/photos/{assetSlug}/statistics", { params: { ... }})

Retrieve a single photo's stats. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | | ---------------- | -------- | -------- | ----------------- | ------- | | assetSlug | path | string | Required | | | resolution | query | "days" | Optional | "days" | | quantity | query | number | Optional | 30 |

Example

const { data, error } = await unsplash.GET("/photos/{assetSlug}/statistics", {
  params: {
    path: { assetSlug: "mtNweauBsMQ" },
    query: {
      resolution: "days",
      quantity: 30,
    },
  },
});

.GET("/photos/random", { params: { ... }})

Retrieve a single random photo, given optional filters. See endpoint docs 🚀. Note: if you provide a value for count greater than 1, you will receive an array of photos. Otherwise, you will receive a single photo object.

Parameters

| Parameter | Location | Type | Optional/Required | Default | | -------------------- | -------- | ----------------------------------------- | ----------------- | ------- | | count | query | number | Optional | 1 | | collections | query | Array | Optional | | | topics | query | Array | Optional | | | username | query | string | Optional | | | orientation | query | "portrait" | "landscape" | "squarish" | Optional | | | content_filter | query | "low" | "high" | Optional | "low" | | query | query | string | Optional | |

Example

const { data, error } = await unsplash.GET("/photos/random", {
  params: {
    query: {
      collections: ["abc123"],
      topics: ["def456"],
      username: "naoufal",
      query: "dog",
      count: 1,
    },
  },
});

.GET("/photos/{id}/download", { params: { ... }})

Trigger a download of a photo as per the download tracking requirement of API Guidelines. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | | --------- | -------- | -------- | ----------------- | | id | path | string | Required |

Example

const photoResult = await unsplash.GET("/photos/{assetSlug}", {
  params: {
    path: { assetSlug: "mtNweauBsMQ" },
  },
});

if (photoResult.data) {
  await unsplash.GET("/photos/{id}/download", {
    params: {
      path: { id: photoResult.data.id },
    },
  });
}

// or if working with an array of photos
const searchResult = await unsplash.GET("/search/photos", {
  params: {
    query: { query: "dogs" },
  },
});

if (searchResult.data) {
  const firstPhoto = searchResult.data.results[0];

  await unsplash.GET("/photos/{id}/download", {
    params: {
      path: { id: firstPhoto.id },
    },
  });
}

.GET("/users/{username}", { params: { ... }})

Retrieve public details on a given user. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | | -------------- | -------- | -------- | ----------------- | | username | path | string | Required |

Example

const { data, error } = await unsplash.GET("/users/{username}", {
  params: {
    path: { username: "naoufal" },
  },
});

.GET("/users/{username}/photos", { params: { ... }})

Get a list of photos uploaded by a user. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | | ----------------- | -------- | ------------------------------------------------------------ | ----------------- | -------- | | username | path | string | Required | | | page | query | number | Optional | 1 | | per_page | query | number | Optional | 10 | | order_by | query | "latest" | "oldest" | "popular" | "views" | "download" | Optional | "latest" | | stats | query | boolean | Optional | false | | resolution | query | "days" | Optional | "days" | | quantity | query | number | Optional | 30 | | orientation | query | "portrait" | "landscape" | "squarish" | Optional | |

Example

const { data, error } = await unsplash.GET("/users/{username}/photos", {
  params: {
    path: { username: "naoufal" },
    query: {
      page: 1,
      per_page: 10,
      order_by: "latest",
      orientation: "landscape",
    },
  },
});

.GET("/users/{username}/collections", { params: { ... }})

Get a list of collections created by the user. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | | -------------- | -------- | -------- | ----------------- | ------- | | username | path | string | Required | | | page | query | number | Optional | 1 | | per_page | query | number | Optional | 10 |

Example

const { data, error } = await unsplash.GET("/users/{username}/collections", {
  params: {
    path: { username: "naoufal" },
    query: {
      page: 2,
      per_page: 15,
    },
  },
});

.GET("/collections", { params: { ... }})

Get a single page from the list of all collections. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | | -------------- | -------- | -------- | ----------------- | ------- | | page | query | number | Optional | 1 | | per_page | query | number | Optional | 10 |

Example

const { data, error } = await unsplash.GET("/collections", {
  params: {
    query: { page: 1, per_page: 10 },
  },
});

.GET("/collections/{collectionId}", { params: { ... }})

Retrieve a single collection. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | | ------------------ | -------- | -------- | ----------------- | | collectionId | path | string | Required |

Example

const { data, error } = await unsplash.GET("/collections/{collectionId}", {
  params: {
    path: { collectionId: "abc123" },
  },
});

.GET("/collections/{collectionId}/photos", { params: { ... }})

Retrieve a collection’s photos. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | | ------------------ | -------- | ----------------------------------------- | ----------------- | ------- | | collectionId | path | string | Required | | | page | query | number | Optional | 1 | | per_page | query | number | Optional | 10 | | orientation | query | "portrait" | "landscape" | "squarish" | Optional | |

Example

const { data, error } = await unsplash.GET("/collections/{collectionId}/photos", {
  params: {
    path: { collectionId: "abc123" },
    query: {
      page: 1,
      per_page: 10,
      orientation: "landscape",
    },
  },
});

.GET("/collections/{collectionId}/related", { params: { ... }})

Lists collections related to the provided one. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | | ------------------ | -------- | -------- | ----------------- | | collectionId | path | string | Required |

Example

const { data, error } = await unsplash.GET("/collections/{collectionId}/related", {
  params: {
    path: { collectionId: "abc123" },
  },
});

.GET("/topics", { params: { ... }})

Get a single page from the list of all topics. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | | -------------- | -------- | -------------------------------------------------- | ----------------- | ---------- | | page | query | number | Optional | 1 | | per_page | query | number | Optional | 10 | | order_by | query | "featured" | "latest" | "oldest" | "position" | Optional | "position" | | ids | query | Array | Optional | |

Example

const { data, error } = await unsplash.GET("/topics", {
  params: {
    query: {
      page: 1,
      per_page: 10,
      ids: ["fashion", "architecture", "6sMVjTLSkeQ"],
    },
  },
});

.GET("/topics/{topicSlug}", { params: { ... }})

Retrieve a single topic. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | | --------------- | -------- | -------- | ----------------- | | topicSlug | path | string | Required |

Example

const { data, error } = await unsplash.GET("/topics/{topicSlug}", {
  params: {
    path: { topicSlug: "wallpapers" },
  },
});

.GET("/topics/{topicSlug}/photos", { params: { ... }})

Retrieve a topic’s photos. See endpoint docs 🚀

Parameters

| Parameter | Location | Type | Optional/Required | Default | | ----------------- | -------- | ----------------------------------------- | ----------------- | -------- | | topicSlug | path | string | Required | | | page | query | number | Optional | 1 | | per_page | query | number | Optional | 10 | | orientation | query | "portrait" | "landscape" | "squarish" | Optional | | | order_by | query | "latest" | "oldest" | "popular" | Optional | "latest" |

Example

const { data, error } = await unsplash.GET("/topics/{topicSlug}/photos", {
  params: {
    path: { topicSlug: "wallpapers" },
    query: {
      page: 1,
      per_page: 10,
      order_by: "latest",
      orientation: "landscape",
    },
  },
});