Documentation

Current Version

The Getty Images API is currently at version 3. Use the following base URI to access version 3 endpoints.

https://api.gettyimages.com/v3/

Authentication

The Getty Images API requires all requests to include an Api-Key to authenticate the client. Pass the Api-Key via the custom Api-Key HTTP Header.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800"

Authorization

The Getty Images API allows, and in some cases requires, requests to include an access token to authorize elevated client privileges. Pass the access token via the standard Authorization HTTP header as type Bearer.

curl -H "Api-Key:<YOUR_API_KEY>" -H "Authorization: Bearer <access_token>" \
https://api.gettyimages.com/v3/downloads/83454811 -d "'" -L -o sample.jpg

Acquire an access token using one of the Getty Images API OAuth2 grants. This example uses the OAuth2 client credentials flow.

curl -d 'grant_type=client_credentials&client_id=<YOUR_API_KEY>&client_secret=<YOUR_API_SECRET' \
"https://api.gettyimages.com/oauth2/token"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 123

{"access_token": "{token_string}", "token_type": "Bearer", "expires_in": "1800"}

If elevated client privilege is required but missing, the API returns an authorization challenge in the response.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Download",error="invalid_token",error_description="The access token is missing"

Request Throttling

The Getty Images API throttles client requests based on limits associated with the client’s Api-Key.

Response message when exceeding calls per second limit:

HTTP/1.1 429 Too Many Requests
X-Error-Detail: Account Over Queries Per Second Limit

{"message": "Account Over Queries Per Second Limit"}

Schema

All API access is over HTTPS. All data is sent and received as JSON.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/search/images/creative?phrase=books"

HTTP/1.1 200 OK
Access-Control-Allow-Headers: origin, accept, content-type
Access-Control-Allow-Methods: options, post
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 1728000
Cache-Control: no-cache,no-cache
Content-Language: en-US
Content-Type: application/json; charset=utf-8
Date: Wed, 16 Jul 2014 17:43:01 GMT
Expires: -1
Pragma: no-cache
Server: Mashery Proxy
X-Mashery-Responder: prod-j-worker-us-west-1b-19.mashery.com
Content-Length: 29728
Connection: keep-alive

{"result_count": 867845, "images": [ /* snipped */ ]}

The Getty Images API returns UTC date/time values in ISO 8601 format.

YYYY-MM-DDTHH:MM:SSZ

Summary, Detail, and Custom Representations

Some fields are computationally expensive for the API to provide or require additional access privileges; and therefore, are not returned by default. Clients can specify additional fields be returned for a resource using the fields querystring parameter.

The default set of fields returned are the summary_set. Both of the following produce the same response.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800
curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800?fields=summary_set

The API provides a detail_set specifier that will include additional fields.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800?fields=detail_set

Alternately, clients can pass a comma delimited list of the specific fields they are interested in.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800?fields=id,title"

Some fields are in neither summary_set nor detail_set and must be explicitly specified.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800?fields=download_sizes"

Some fields require additional access priviledges and must be explicitly specified. In these cases clients must also provide an access token.

curl -i -H "Api-Key:<YOUR_API_KEY>" -H "Authorization: Bearer <access_token>" \
"https://api.gettyimages.com/v3/images/83454800?fields=downloads"

Download Sizes

Authorizing download of an image is computationally expensive. Therefore, clients that wish to receive details of available download sizes for images must explicitly specify that they want this information via the fields querystring parameter. The following tables show the available and allowed fields arguments for the endpoints that can return sizes and/or links to the downloadable image.

Note that clients using the download_sizes or largest_downloads arguments must also provide an access token.

Display Sizes

Display sizes can be retrieved by passing any of the following arguments in the fields parameter.

Resources

The Getty Images API provides a RESTful API centered around resources, identified by a URI, that can be acted upon by the standard HTTP verbs. Descriptions of the Getty Images API resources are provided on our interactive documentation page.

HTTP Verbs

The Getty Images API strives to use appropriate HTTP verbs to perform actions on our resources.

Parameters

Some API endpoints take parameters specified as a segment in the path.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800"

Additional options can be specified as HTTP querystring parameters.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/search/images?phrase=books"

Some resources allow filtering on their representations using the fields querystring parameter.

curl -i -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/images/83454800?fields=id,title"

In the last example the response will contain only the fields id and title.

Hypermedia

All resources may have one or more URI properties linking to other resources. These provide explicit URIs to additional resources, saving API clients from the need to construct the URIs on their own.

Here’s an example of a search result providing a URI for downloading the image’s largest size.

{
  "images": [
    {
      "id": "3231670",
      "largest_downloads": [
        {
          "media_type": "image/jpeg",
          "bytes": 2226077,
          "downloads": [
            {
              "product_type": "premiumaccess",
              "uri": "https://api.gettyimages.com/v3/downloads/3231670"
            }
          ],
          "height": 3000,
          "width": 1607
        }
      ]
    }
  ]
}

A POST to the provided URI with a valid Api-Key and access token will download the image.

HTTP Redirects

The Getty Images API uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection and be prepared to follow the redirect. Redirect responses will have a Location header field which contains the URI of the resource to which the client should repeat the requests. The API currently uses 302 Found and 303 See Other for redirects.

Errors

There are the most common errors a client may receive when calling the API.

1. Sending misspelled or improperly formatted request bodies or querystring parameters will result in a 400 Bad Request response.

   HTTP/1.1 400 Bad Request
   Content-Type: application/vnd.getty.error+json
   
   {
       "message": "Invalid Request. Possible required parameter missing."
   }
   

2. Omitting, misspelling, or sending invalid Api-Key will result in a 401 Unauthorized response.

   HTTP/1.1 401 Unauthorized
   Content-Type: application/json
   
   {
       "message": "Unauthorized"
   }
   

3. Submitting invalid image id’s will result in a 404 Not Found response.

   HTTP/1.1 404 Not Found
   Content-Type: application/vnd.getty.error+json
   
   {
       "code": "ImageNotFound",
       "message": "Image not found: 452O76944"
   }
   

4. Exceeding your Api-Key’s call per second throttle limit will result in a 429 Too many requests response.

Pagination

Many Getty Images API endpoints provide support for pagination of results. Pagination can be controlled by using the page and page_size querystring parameters. Default values will be used if none are provided.

• The page parameter defaults to 1.
• Search results default to a page_size of 30 items per page. Valid values are: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 25, 30, 50, 60, 75, 100.

This example demonstrates requesting the first page, containing 20 items, of search results.

curl -H "Api-Key:<YOUR_API_KEY>" "https://api.gettyimages.com/v3/search/images?phrase=dogs&page=1&page_size=20"

Cross Origin Resource Sharing

We support cross origin resource sharing (CORS). All endpoints (except /oauth2/token and /oauth2/auth) return the following header.

Access-Control-Allow-Origin: *

Localization

Many Connect endpoints provide support for localization of certain request or response fields using the Accept-Language HTTP header. This header value defaults to en-US if

• the client omits the Accept-Language HTTP header,
• the client omits a locale, or
• the client specifies an unsupported locale.

This example will return country names in French.

curl -i -H "Api-Key:<YOUR_API_KEY>" -H "Accept-Language:fr" https://api.gettyimages.com/v3/countries

oEmbed

What is oEmbed?

oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.

Full documentation and various client libraries for the oEmbed specification can be found here: http://oembed.com

Endpoint

Use the following endpoints to access this operation:

http://embed.gettyimages.com/oembed

Request

The oEmbed request is a GET with the following required parameter. Note: URL encode query string parameters.

url: http://gty.im/[asset-id]

In addition, you should use the optional caller parameter, providing descriptive value identifying your application.

caller: example.com

The oEmbed request returns JSON. If the optional “format” parameter is used it must contain the value “json”. Other formats are not supported and using another value such as “xml” will result in a 501 (Not Implemented) error.

Example request:

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

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"
	}

Workflow example: oEmbed

1. Find embeddable images on www.gettyimages.com (see embed.gettyimages.com for more information)
2. Call oEmbed using the asset id of the embeddable image that you wish to use.

Workflow example: Getty Images API client using oEmbed

1. Get an access token as described in the authorization section.
2. Search for an image, adding the embed_content_only=true parameter to the querystring.
3. Call oEmbed with each of the asset ids of the embeddable images that you wish to use.