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:

Documentation

Installation
Usage
Replacing fetch
Types
Endpoint examples

Installation

$ npm i --save unsplash-js

# OR

$ yarn 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:

You received data: result.data is present and populated.
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:

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

Name		Name	Last commit message	Last commit date
Latest commit History 549 Commits
.github		.github
.vscode		.vscode
src		src
test		test
.gitignore		.gitignore
.oxfmtrc.json		.oxfmtrc.json
.oxlintrc.json		.oxlintrc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
public.json		public.json
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts
vscode-params-completion-1.png		vscode-params-completion-1.png
vscode-params-completion-2.png		vscode-params-completion-2.png
vscode-path-completion.png		vscode-path-completion.png
vscode-response-completion.png		vscode-response-completion.png

Folders and files

Latest commit

History

Repository files navigation

Unsplash

Documentation

Installation

Usage

Creating an instance

Making a request

Response

Authentication

Replacing fetch

Types

Request completion

Response completion

Endpoint examples

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 36

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Packages