Unsplash Source JS

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

Usage

Include unsplash-source.js or unsplash-source.min.js in your page:

<script src="/js/unsplash-source.js"></script>

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.

Method	Arguments	Example	Description
find	"publicId"	photo.find("oMpAz-DN-9I")	Finds a photo by its ID
width	width	photo.width(2000)	Sets the width in pixels
height	height	photo.height(2000)	Sets the height in pixels
size	width, height	photo.size(1080,800)	Shorthand for setting the width and height in pixels
randomize	`null		"daily"
fromUser	"username"	photo.fromUser("erondu")	Limits to a specific photographer
fromCategory	"category"	photo.fromCategory("nature")	Limits to a specific category
of	`"keyword"		[arrayOfKeywords]`
all		photo.all()	Searches for all photos, instead of just featured photos
fetch		photo.fetch()	Returns the configured 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 UnsplashPhoto();

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

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

var photo = new 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 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 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 UnsplashPhoto();

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

Development

To contribute, make sure Node and NPM are installed. Then:

git clone ..

npm install
grunt test // => should all pass

// make your changes to the `/src` folder
// add tests to `/tests`

grunt test // => should all pass

grunt build // => creates a bundled version of the script

git commit ..