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.

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 ..