Unsplash Source JS

A javascript wrapper for the Unsplash Source API. Get random Unsplash photos by keyword, location, category, user, or ID.

Usage

Install unsplash-source-node-js with:

npm install unsplash

You can require unsplash-source-node-js like this:

const UnsplashSource = require('unsplash-source-node-js');

// Or you can require the UnsplashPhoto object directly:

const UnsplashPhoto = require('unsplash-source-node-js').UnsplashPhoto;

Then create the photo you want using any of the chainable methods below, calling fetch as the last step to return the photo's URL.

By default, the photos are filtered to featured photos. To remove this filter, call all. We recommend using all when limiting photos to a specific keyword (using of) or limiting photos to specific photographers (using fromUser) to maximize the possiblity of a matching photo.

Resize operations (width, height, size) maintain the aspect ratio of the original photo by cropping if necessary.

Note: Not all methods are compatible with each other. For example, trying to randomize a specific photo doesn't make sense. The wrapper will ignore incompatible methods and only construct URLs compatible with the Unsplash Source API.

Examples

Get a random photo (the Unsplash Source API defaults to a width of 1080px):

var photo = new UnsplashSource.UnsplashPhoto();

photo.fetch(); // => "https://source.unsplash.com/random"

Get a random featured photo that rotates weekly, cropped to 800px x 600px:

var photo = new UnsplashSource.UnsplashPhoto();

photo.randomize("weekly")
     .size(800, 600)
     .fetch(); // => "https://source.unsplash.com/800x600/weekly"

Get a random photo from photographer Jared Erondu cropped to 2048px x 1200px, that changes once a day:

var photo = new UnsplashSource.UnsplashPhoto();

photo.all()
     .fromUser("erondu")
     .width(2048)
     .height(1200)
     .randomize("daily")
     .fetch(); // => "https://source.unsplash.com/user/erondu/2048x1200/daily"

Get a random nature photo of trees and water from the 'all' feed, cropped to 1000px x 1200px:

var photo = new UnsplashSource.UnsplashPhoto();

photo.all()
     .fromCategory("nature")
     .of(["trees", "water"])
     .size(1000, 1200)
     .fetch(); // => "https://source.unsplash.com/category/nature/1000x1200?trees,water"

Get a specific photo (the photo ID matches the photo ID from unsplash.com):

photo = new UnsplashSource.UnsplashPhoto();

photo.find("oMpAz-DN-9I")
     .fetch(); // => "https://source.unsplash.com/oMpAz-DN-9I"