You're viewing documentation for version 3. Find version 4 here.

PhotoShelter Developer

Fetch Image Data

Let's start with the basics - how to fetch image data from the PhotoShelter API. The example code in this guide is written in JavaScript, using the JavaScript library jQuery, but you can use your programming language of choice.

What you need

What to do

Ready? Let's dive in.

Make the call

To get data for an image on PhotoShelter, such as the file name and file size, we need to send a request to the endpoint /psapi/v3/image/{image_id}. We make an Ajax request and pass the following parameters in the query string:

Parameter Description
api_key Set to your API key. Alternatively, you can set X-PS-Api-Key to your API key in the HTTP request header.
fields Specifies output fields to be returned. For this example, let's request image_id, file_name, and file_size. The Endpoint Reference lists the possible output fields for every endpoint on the API.

Let's put it all together. If you want to run the code, don't forget to replace MY_IMAGE_ID with the id of the image you're looking for, and replace MY_API_KEY with your API key.

var apiKey = MY_API_KEY;
var imgId = MY_IMAGE_ID;

var endpoint = '/psapi/v3/image/' + imgId;

var params = [
	'api_key=' + apiKey,
var paramsStr = params.join("&");

var url = endpoint + '?' + paramsStr;

var dfr = $.ajax(url);

The response

Since we didn't specify the format parameter, the default response format is JSON:

  "status": "ok",
  "data": {
    "Image": {
      "image_id": "MY_IMAGE_ID",
      "file_name": "my_image.JPG",
      "file_size": "1800"

See the top-level key Image for the data record? The top-level key, which is always capitalized, is how you'll know the record type that is returned.

You can also request the response to be returned in XML format by passing format=xml in the request URL.

Display the data

Now we have all the data we need. We can compose an HTML string with our data and append it to the HTML <body> element:

dfr.done(function(response) {
	var image =;
	var str = "";

	str += "<p>The image ID is: " + image.image_id + "</p>";
	str += "<p>The file name is: " + image.file_name + "</p>";
	str += "<p>The file size is: " + image.file_size + "</p>";


Further reading