API Overview

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 include an Api-Key to authenticate the client. Pass the Api-Key via the custom Api-Key HTTP Header.

curl -i -H "Api-Key:j878g39yx378pa77djthzzpn" "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:j878g39yx378pa77djthzzpn" -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=j878g39yx378pa77djthzzpn&client_secret=hZJS5A3GJpJvcGhaXwev3kwmq3DgtfcQmEuGbGruQBfsz' "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. These limits can be viewed on your account page. Click the View Report link on your key to get the current status of an Api-Key's limits.

There are two throttling limits and each has its own error message.

  • Calls per second limit

      HTTP/1.1 403 Forbidden
      X-Error-Detail: Account Over Queries Per Second Limit
    
      {"message": "Account Over Queries Per Second Limit"}
    
  • Calls per day limit

      HTTP/1.1 403 Forbidden
      X-Error-Detail: Account Over Rate Limit
    
      {"message": "Account Over Rate Limit"}
    

Schema

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

curl -i -H "Api-Key:j878g39yx378pa77djthzzpn" "https://api.gettyimages.com/v3/search/images?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:j878g39yx378pa77djthzzpn" "https://api.gettyimages.com/v3/images/83454800
curl -i -H "Api-Key:j878g39yx378pa77djthzzpn" "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:j878g39yx378pa77djthzzpn" "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:j878g39yx378pa77djthzzpn" "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:j878g39yx378pa77djthzzpn" "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:j878g39yx378pa77djthzzpn" -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.

fields argument description
downloads returns downloadable sizes with hypermedia download links
download_sizes returns downloadable sizes without hypermedia download links
largest_downloads returns hypermedia download links to the largest size
endpoints download_sizes downloads largest_downloads
v3/search/images X
v3/search/images/creative X
v3/search/images/editorial X
v3/images X X X

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.

fields argument description
display_set all display sizes
high_res_comp largest display size
comp large display size
preview medium display size
thumb smallest display size

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.

verb description
GET use to retrieve a resources or collection
POST use to create a resource or perform a custom action
PUT use to store an entity under a specific resource
DELETE unsupported at this time

Parameters

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

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

Additional options can be specified as HTTP querystring parameters.

curl -i -H "Api-Key:j878g39yx378pa77djthzzpn" "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:j878g39yx378pa77djthzzpn" "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/json; charset=utf-8
    
     {
         "message": "Invalid Request. Possible required parameter missing."
     }
    
  2. Omitting, misspelling, or sending invalid Api-Key will result in a 403 Forbidden: Account Inactive response.

     HTTP/1.1 403 Forbidden
     Content-Type: application/json; charset=utf-8
    
     {
         "message": "Account Inactive"
     }
    
  3. Submitting invalid image id's will result in a 404 Not Found response.

     HTTP/1.1 404 Not Found
     Content-Type: application/json; charset=utf-8
    
     {
         "code": "ImageNotFound",
         "message": "Image not found: 452O76944"
     }
    
  4. Exceeding your Api-Key's call per second throttle limit will result in a 403 Forbidden: Account Over Queries Per Second Limit response.

     HTTP/1.1 403 Forbidden
     X-Error-Detail:  Account Over Queries Per Second Limit
     Content-Type: application/json; charset=utf-8
    
     {
         "message": "Account Over Queries Per Second Limit"
     }
    
  5. Exceeding your Api-Key's call per day throttle limit will result in a 403 Forbidden: Account Over Rate Limit response.

     HTTP/1.1 403 Forbidden
     X-Error-Detail:  Account Over Rate Limit
     Content-Type: application/json; charset=utf-8
    
     {
         "message": "Account Over Rate Limit"
     }
    

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:j878g39yx378pa77djthzzpn" "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:j878g39yx378pa77djthzzpn" -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. Call CreateSession or 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 Filter property EmbedContentOnly (boolean) within the SearchForImagesRequestBody.
  3. Call oEmbed with each of the asset ids of the embeddable images that you wish to use.