Using Unsplash API to Seed Placeholder Data

There are numerous sites that serve placeholder images. These are great when working in development and wanting to see how real images will behave in your application.

The challenge is that you almost always need to know the context of an image to use one of these services if it's going to look like it fits. Otherwise, you're just using random images that may not provide the proper feel or context for where they are being used.

For example, say you're building a pet adoption application. Photos of Nicolas Cage wouldn't feel quite right. Photos of kittens would, but you might want this to feel more real and balanced, including other animals. And most of these services are not built to be dynamic.

Fortunately, Unsplash has an API that includes searching for images that can help you grab more contextual images.

Dynamic Placeholder Images with Unsplash

Here's a simplified process for including dynamic placeholder images in your application.

Unsplash API Setup

To use the Unsplash API, you need to create a developer account and register an application. The docs are well-written and make this an easy process.

Install Dependencies

In this example, we'll use three dependencies:

• unsplash-js to search images via the Unsplash API
• node-fetch to make the API request
• @faker-js/faker (optional) as an example of using dummy data to generate images

Install the necessary dependencies:

npm install --save-dev unsplash-js node-fetch @faker-js/faker

Fetch Images

Here's some basic code that will fetch images from Unsplash and write the response to a file called photos.json in your project. Note that it is using a UNSPLASH_ACCESS_KEY environment variable that contains the API key given to your Unsplash developer application.

import fetch from "node-fetch";
import fs from "fs";
import path from "path";
import { createApi } from "unsplash-js";
import { faker } from "@faker-js/faker";

global.fetch = fetch;

// Initiate Unsplash API
const unsplash = createApi({ accessKey: process.env.UNSPLASH_ACCESS_KEY });
// Search photos for a random animal (from Faker library)
const photos = await unsplash.search.getPhotos({ query: faker.animal.type() });
// Write response to a photos.json file
const filePath = path.join(process.cwd(), "photos.json");
fs.writeFileSync(filePath, JSON.stringify(photos, null, 2));

After running this code, inspect the photos.json file to see the shape of the response, assuming there were images that matched the random image.

Manipulate Images as Needed

Unsplash uses Imgix to serve its images, which means that you can manipulate them using their rendering API.

You may search insect and be returned this image:

But you can resize and manipulate this image as needed. For example, you can crop it to a square.

Improving the Code

Once you implement the code to fit your application, here are some additional suggestions for building on this code:

• Catch when no results are returned. The code doesn't do this. If there are no image results returned, you may want to adjust the text and do another search.
• Because there are limitations with the API (see below), you may want to cache the results. You could do this by storing them in a database or a series of files from which you look up first before hitting the Unsplash API.

Unsplash API Limitations

There are a couple limitations and restrictions with the code that you should be aware of when implementing this solution:

• You are limited to 50 requests per hour when your Unsplash application is in development mode. You could cache responses locally to help with this. Or you can apply for production, where your limits will increase significantly.
• To follow the usage agreement, you must keep the ixid parameter that is included with every URL. This is how Unsplash knows you are using the image and it is part of the guidelines. If you manipulate the URL parameters, be sure to keep ixid intact.