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" || "weekly"|photo.randomize("weekly")|Sets the randomization interval fromUser|"username"|photo.fromUser("erondu")|Limits to a specific photographer fromCategory|"category"|photo.fromCategory("nature")|Limits to a specific category of|"keyword" || [arrayOfKeywords]|photo.of("dog")|Limits to tags or locations matching the keywords 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 ..