Unsplash
A Universal JavaScript wrapper for the Unsplash API.
Browser Support
| | | | |
---|
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 browsers 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
.
let 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.
let unsplash = new Unsplash({
applicationId: "{APP_ID}",
secret: "{APP_SECRET}",
callbackUrl: "{CALLBACK_URL}",
bearerToken: "{USER_BEARER_TOKEN}"
});
Credentials can be obtained from Unsplash Developers.
Authorization workflow
Generate an authentication url with the scopes your app requires.
let 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.
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 => {
});
Instance Methods
auth.getAuthenticationUrl(scopes)
Build an OAuth url with requested scopes.
Arguments
Argument | Type | Opt/Required | Default |
---|
scopes | Array | Optional | ["public"] |
Example
let 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 => {
});
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 => {
});
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 => {
});
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 => {
});
users.photos(username)
Get a list of photos uploaded by a user.
Arguments
Argument | Type | Opt/Required |
---|
username | string | Required |
Example
unsplash.users.photos("naoufal")
.then(toJson)
.then(json => {
});
users.likes(username, page, perPage)
Get a list of photos liked by a user.
Arguments
Argument | Type | Opt/Required |
---|
username | string | Required |
page | number | Optional |
perPage | number | Optional |
Example
unsplash.users.likes("naoufal", 2, 15)
.then(toJson)
.then(json => {
});
photos.listPhotos(page, perPage)
Get a single page from the list of all photos.
Arguments
Argument | Type | Opt/Required |
---|
page | number | Optional |
perPage | number | Optional |
Example
unsplash.photos.listPhotos(2, 15)
.then(toJson)
.then(json => {
});
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 => {
});
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 => {
});
photos.getRandomPhoto(category, featured, username, query, width, height)
Retrieve a single random photo, given optional filters.
Arguments
Argument | Type | Opt/Required |
---|
category | Array | Optional |
featured | boolean | Optional |
username | string | Optional |
query | string | Optional |
width | number | Optional |
height | number | Optional |
Example
unsplash.photos.getRandomPhoto([88], true, "naoufal", "cats", 1920, 1080)
.then(toJson)
.then(json => {
});
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 => {
});
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 => {
});
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 => {
});
categories.listCategories()
Get a list of all photo categories.
Arguments
N/A
Example
unsplash.categories.listCategories()
.then(toJson)
.then(json => {
});
categories.category(id)
Retrieve a single category.
Arguments
Argument | Type | Opt/Required |
---|
id | string | Required |
Example
unsplash.categories.category(4)
.then(toJson)
.then(json => {
});
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 => {
});
curatedBatches.listCuratedBatches()
Get a single page from the list of all curated batches.
Arguments
N/A
Example
unsplash.curatedBatches.listCuratedBatches()
.then(toJson)
.then(json => {
});
curatedBatches.curatedBatch(id)
Retrieve a single batch.
Arguments
Argument | Type | Opt/Required |
---|
id | string | Required |
Example
unsplash.curatedBatches.curatedBatch(88)
.then(toJson)
.then(json => {
});
curatedBatches.curatedBatchPhotos(id)
Retrieve a single batch’s ten photos.
Arguments
Argument | Type | Opt/Required |
---|
id | string | Required |
Example
unsplash.curatedBatches.curatedBatchPhotos(88)
.then(toJson)
.then(json => {
});
stats.total()
Get a list of download counts for all of Unsplash.
Arguments
N/A
Example
unsplash.stats.total()
.then(toJson)
.then(json => {
});
Helpers
toJson(res)
Arguments
Argument | Type | Opt/Required |
---|
res | Object | Required |
Example
import Unsplash, { toJson } from "unsplash-js";
let unsplash = new Unsplash({
applicationId: "{YOUR_APPLICATION_ID}",
secret: "{YOUR_SECRET_KEY}",
callbackUrl: "{YOUR_CALLBACK_URL}"
});
unsplash.stats.total()
.then(toJson)
.then(json => {
});
License
Copyright (c) 2015, Naoufal Kadhom
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.