Getty Images Embed via oEmbed

You can use our API endpoint to request the embed code for Embed eligible still images and 360 content. All responses are in json format.

Request

There are two types of embeds you can request: a single image and a slideshow of images. The snippet for the embed is acquired by making a GET request to,

single: http://embed.gettyimages.com/oembed?url=http://gty.im/[asset-id]&caller=[example.com]

or

slideshow: http://embed.gettyimages.com/oembed?url=http://gty.im/[asset-id],[asset-id],[asset-id]&caller=[example.com] (up to 5 ids)

The asset-id is that of an Embed eligible image indicated by the </> icon on each image and the caller is your domain name. You can search for Embed eligible content on Getty Images.

For example,

http://embed.gettyimages.com/oembed?url=http%3a%2f%2fgty.im%2f74917285&caller=example.com

Note: URL encode the query string as in the example above.

In addition to the above features the oembed api provides a number of other parameters for additional content and customization,

url (required)

The essential parameter for requesting an embed. See the example urls above for both a standalone and slideshow embed.

caller (required)

Your domain name.

maxheight (optional)

The maximum height of the embedded resource. If you have space restrictions, you can use this parameter to restrict the height of the content when it is rendered. There are a few restrictions on the use of this parameter to keep in mind: the maximum value can be no more than the native height of the image and preserving the aspect ratio is prioritzied over honoring the value of maxheight and/or the maxwidth. You most likely will need to do some trial and error to achieve exactly what you need.

maxwidth (optional)

The maximum width of the embedded resource. If you have space restrictions, you can use this parameter to restrict the width of the content when it is rendered. There are a few restrictions on the use of this parameter to keep in mind: the maximum value can be no more than the native width of the image and preserving the aspect ratio is prioritzied over honoring the value of maxwidth and/or the maxheigth. You most likely will need to do some trial and error to achieve exactly what you need.

caption (optional)

Specifying caption=true in the query string will enable the caption feature.

tld (optional)

Specifying tld=[valid tld] will link the embed to the Getty Images site affiliated with the tld. Currently the valid tld values are: com, com.au, be, ca, dk, de, es, fr, in, ie, it, nl, co.nz, no, at, ru, com.pl, pt, ch, fi, se, ae, co.uk, cn, co.jp . The default value is com.

format (optional)

Currently the only supported format is JSON, which is the default. If this parameter is specified the only valid value is json

Response

The oEmbed JSON response has this form, per the oEmbed specification:

{
  "type": string,
  "version": string,
  "title": string,
  "caption": string,
  "photographer": string,
  "collection": string,
  "html": string,
  "width": int,
  "height": int,
  "thumbnail_url": string,
  "thumbnail_height": int,
  "thumbnail_width": int,
  "terms_of_use_url": string
}

Example response:

{
    "type": "rich",
    "version": "1.0",
    "height": 643,
    "width": 395,
    "html": "\u003cdiv style=\"background-color:#fff;display:inline-block;font-family:'Helvetica Neue',Arial,sans-serif;color:#a7a7a7;font-size:11px;width:100%;max-width:395px;min-width:300px;\"\u003e\u003cdiv style=\"overflow:hidden;position:relative;height:0;padding:150.379747% 0 49px 0;width:100%;\"\u003e\u003ciframe src=\"//localhost:3000/embed/74917285?et=GCDFoeg3T3xB1L6jmY5dDQ\u0026sig=mXFz-gxQc_lIp2nmITlHtjjKIvYL1UD6e5yjuPDQ9FU=\" width=\"395\" height=\"643\" scrolling=\"no\" frameborder=\"0\" style=\"display:inline-block;position:absolute;top:0;left:0;width:100%;height:100%;\"\u003e\u003c/iframe\u003e\u003c/div\u003e\u003cp style=\"margin:0;\"\u003e\u003c/p\u003e\u003cdiv style=\"padding:0;margin:4px 0 0 10px;text-align:left;\"\u003e\u003ca href=\"http://www.gettyimages.com/detail/74917285\" target=\"_blank\" style=\"color:#a7a7a7;text-decoration:none;font-weight:normal !important;border:none;display:inline-block;\"\u003e#74917285\u003c/a\u003e / \u003ca href=\"http://www.gettyimages.com\" target=\"_blank\" style=\"color:#a7a7a7;text-decoration:none;font-weight:normal !important;border:none;display:inline-block;\"\u003egettyimages.com\u003c/a\u003e\u003c/div\u003e\u003c/div\u003e",
    "title": "Model Released Basketball",
    "caption": "Model Released: Two young men outdoors, one man holding basketball, portrait (Photo by Black 100/Getty Images)",
    "photographer": "Black 100",
    "collection": "Allsport Concepts",
    "thumbnail_url": "http://delivery.candidate-gettyimages.com/xt/74917285.jpg?v=1\u0026g=fs2|0|editorial3|17|285\u0026s=1",
    "thumbnail_height": "170",
    "thumbnail_width": "113",
    "terms_of_use_url": "http://www.gettyimages.com/Corporate/Terms.aspx"
}

How to Search for oEmbed Eligible Embeds

  1. Call OAuth with system/key and user credentials to create an authentication token.
  2. Call SearchForImages to find images specifying the search is for embeddable images only, by adding the embed_content_only parameter to the querystring with a value of true.
  3. Call oEmbed with each of the asset ids of the embeddable images that you wish to use.