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

An API key with PhotoShelter, which is required to access the API. To run the example code in this guide, replace "MY_API_KEY" with your own key. Register for an API key, or learn more about Connecting to the PhotoShelter API.
Access to a PhotoShelter account. If you don't have one, you can sign up for a free Trial Account. Trial Accounts have limited storage and theme options, but it will allow you to test the PhotoShelter API for up to 14 days. If you need an extension on the trial, reach out to our Technical Support team.

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,
	"fields=image_id,file_name,file_size"
];
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 = response.data.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>";

	$('BODY').append(str);
});