The JSON Output Format

Metadata is a powerful tool when working with images. It can tell you the dimensions of your image, DPI, camera EXIF data, and more—and each piece of data is a signal you can use with imgix to display your images to their best advantage with the JSON Output Format (fm=json).

All of the other imgix output formats are image formats like JPEG, GIF, PNG, WebP, or automatically determined by Automatic Content Negotiation. With the new JSON Output Format, you can read information about your images in a familiar, structured format. This opens up a host of new possibilities.

Easily Retrieve Image Information

The imgix JSON Output Format will cause an image request to return a JSON document rather than an image. This payload will have the MIME type application/json and represent several different aspects of the input image. This is done by adding fm=json to your imgix URL.

Using the JSON Output Format, you can read the DPI, color depth, color profile information, pixel dimensions, EXIF data, and more from source images. By default, imgix strips all image metadata for size and privacy concerns. When using the JSON Output Format, however, it will not strip that data and will format it as the response. Here is an example output for a simple JPEG input image:

{
  "Exif": {
    "ComponentsConfiguration": "1 2 3 0",
    "FocalLengthIn35mmFilm": 51,
    "MeteringMode": 5,
    "CustomRendered": 0,
    "InteroperabilityTag": 13424,
    "GainControl": 1,
    "ExposureProgram": 3,
    "ExposureTime": 0.003125,
    "DateTimeOriginal": "2014:09:14 16:34:09",
    "FocalLength": 25,
    "MaxApertureValue": 1,
    "SceneType": "1",
    "PixelXDimension": 4592,
    "ExposureBiasValue": 0,
    "DateTimeDigitized": "2014:09:14 16:34:09",
    "Contrast": 0,
    "ExposureMode": 0,
    "ExifVersion": "0230",
    "ISOSpeedRatings": 200,
    "ColorSpace": 1,
    "FileSource": "3",
    "WhiteBalance": 1,
    "FNumber": 1.6,
    "SceneCaptureType": 0,
    "FlashpixVersion": "48 49 48 48",
    "SensingMethod": 2,
    "SensitivityType": 1,
    "Saturation": 0,
    "Flash": 16,
    "LightSource": 9,
    "PixelYDimension": 3064,
    "CompressedBitsPerPixel": 2,
    "DigitalZoomRatio": 0,
    "Sharpness": 0
  },
  "Orientation": 1,
  "Content-Type": "image/jpeg",
  "Output": {},
  "Content-Length": "5680640",
  "GPS": {},
  "PixelHeight": 3064,
  "PixelWidth": 4592,
  "TIFF": {
    "Make": "Panasonic",
    "ExifTag": 634,
    "ResolutionUnit": 2,
    "YResolution": 180,
    "DateTime": "2014:09:14 16:34:09",
    "YCbCrPositioning": 2,
    "XResolution": 180,
    "Software": "Ver.1.0  ",
    "Model": "DMC-GM1",
    "Orientation": 1
  },
  "ProfileName": "sRGB IEC61966-2.1"
}

Different input formats will include different keys in their JSON output payloads. Please experiment with your own input images to see which keys will be included in the output document. For a more complex example, please click on the image below.

Using the new JSON Output Format, you can do more than just manipulate images with imgix. You can now reason about them as well. This has already led to richer applications for the customers using this feature.

Demo: Maintaining Aspect Ratios

To demonstrate some of the JSON Output Format’s capabilities, we’ve put together a CodePen to show how to maintain the aspect ratio of several user-generated photos. Without access to the metadata, we would have to download the image and store its dimensions server-side to accomplish the same result.

In the example, by using just a few lines of JavaScript, we’re able to maintain the aspect ratios of our images without any server-side processing. We can read information about an image before we decide how we would like it to render, and use it to determine which parameters to apply.