Using the Unsplash API to Search for Photos in a React App

Photo by Markus Spiske on Unsplash

I was recently given the task of adding a feature to an app that would give the users the ability to choose an image to save with an object. Fortunately, the choice of API was up to me! Unfortunately, I hadn’t really worked with any image APIs before! So, as you might have guessed, I started playing around with the Unsplash API — and I’m here to share my experience using this very easy-to-use interface, specifically in the context of incorporating it into a React project.

Getting Started

To get access to the API, first hop over to the Unsplash Developers page and create an account. Once your account has been set up, you’ll need to register your app — note that while initially in demo mode, you will be limited to 50 requests per hour (which I found was more than enough for testing, etc). Then, on the page for the app you just registered, take note of the two unique keys you’ve been given to access the API, the ‘Access Key’ and the ‘Secret Key,’ which you’ll need when you make certain requests, depending on the permissions required.

Because we’re specifically looking at incorporating this into a React app, let’s make use of the JavaScript wrapper for the API. To add it to your project/package.json file:

$ npm install unsplash-js

This library makes interacting with the API very easy by creating an instance of an Unsplash object that contains your app/auth keys, on which you can call various methods to hit specific endpoints and perform certain tasks.

Photo by David Sinclair on Unsplash

Searching By Keyword

The API has an incredible depth of functionality, but we’re going to focus on just one task — searching for photos by a given keyword. The endpoint that we’re hitting in this case is:

GET https://api.unsplash.com/search/photos

The params that we can send along with the request include: query, which is the search terms, page, and per_page, which are the page number to retrieve and the number of items you’d like to return per page. Both of these params are optional, defaulting to 1 and 10, respectively. You can also pass collections IDs to narrow the search to specific collections, as well as orientation to retrieve only landscape, portrait, or squarish oriented photos.

So, for example, a search for photos with a keyword ‘dogs,’ including the default values for page and per_page, would look like this:

GET https://api.unsplash.com/search/photos?query=dogs

Which then returns an object like this:

{
    "total": 30536,
    "total_pages": 3054,
    "results": [
        {
            "id": "dO2WTawCTC4",
            "created_at": "2019-03-25T12:30:46-04:00",
            "updated_at": "2019-05-17T19:52:55-04:00",
            "width": 4000,
            "height": 5000,
            "color": "#261D16",
            "description": null,
            "alt_description": "A gray and white husky drinking water out of a Boxed Water carton",
            "urls": {
                "raw": "https://images.unsplash.com/photo-1553531384-411a247ccd73?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjcyMDI4fQ",
                "full": "https://images.unsplash.com/photo-1553531384-411a247ccd73?ixlib=rb-1.2.1&q=85&fm=jpg&crop=entropy&cs=srgb&ixid=eyJhcHBfaWQiOjcyMDI4fQ",
                "regular": "https://images.unsplash.com/photo-1553531384-411a247ccd73?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&ixid=eyJhcHBfaWQiOjcyMDI4fQ",
                "small": "https://images.unsplash.com/photo-1553531384-411a247ccd73?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=400&fit=max&ixid=eyJhcHBfaWQiOjcyMDI4fQ",
                "thumb": "https://images.unsplash.com/photo-1553531384-411a247ccd73?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=200&fit=max&ixid=eyJhcHBfaWQiOjcyMDI4fQ"
            },
            "links": {
                "self": "https://api.unsplash.com/photos/dO2WTawCTC4",
                "html": "https://unsplash.com/photos/dO2WTawCTC4",
                "download": "https://unsplash.com/photos/dO2WTawCTC4/download",
                "download_location": "https://api.unsplash.com/photos/dO2WTawCTC4/download"
            },
// ...

So then from the results array, we can grab links, tags, descriptions, etc. from each photo returned pretty easily.

But before we get that far, we first need to get things set up in our React app. Create an Unsplash instance with your access key and secret key:

import Unsplash from 'unsplash-js';

const unsplash = new Unsplash({
  applicationId: "{APP_ACCESS_KEY}",
  secret: "{APP_SECRET}"
});

This library also includes React Native integration — when using, simply import from unsplash-js/native instead.

Now, we can simply call various instance methods on unsplash which provides access to the endpoints of the API. In our case, we’re searching for photos by keyword, so we’ll be using search.photos(keyword, page, per_page). This method takes up to three arguments— keyword, a string, which is required, while the other two arguments, page, and per_page are optional.

unsplash.search.photos("cats", 1)
  .then(toJson)
  .then(json => {
    // Do something with the json object
  });

The above code also makes use of the handy helper method toJson, which performs the task of converting the API response to JSON data — usually done with something along the lines of res => res.json(). To use this helper method, simply import it from unsplash-js as well:

import Unsplash, { toJson } from 'unsplash-js

And that’s that! Now you’ve got your photo objects, with which you can do whatever your little heart desires!

Resources

Unsplash Image API | Free HD Photo API

unsplash/unsplash-js