Getty Images Connect API 3.0

Seamlessly integrate Getty Images' expansive digital content, powerful search technology, and rich metadata into your publishing tools, products and services!

Search for images from our extensive creative and editorial catalogs.
Get image metadata.
Download files using your Getty Images products (e.g., Editorial subscriptions, Easy Access, Thinkstock Subscriptions, and Image Packs).

This page describes Connect version 3.0. Documentation for prior versions is also available.

New Features

Simplified authentication and authorization. Client applications no longer need to maintain session tokens. Instead, applications identify themselves on every call to Connect with an Api-Key. Resources that require or support authorization based on user identity will accept OAuth2 access tokens in addition to the application’s Api-Key.
RESTful API for working with image and metadata resources leveraging HTTP verbs and returning standard HTTP Status codes.
Simplified image download process by providing direct download links in search and metadata resources.
Interactive documentation that is always up-to-date and in sync with our latest API functionality.
Localization support using the Accept-Language HTTP header.

Quick links

Getting Started

If you already have a Mashery Member account

Sign in with your Mashery Member credentials.
Click the My Account link near the top right of the page.
Click the Get API keys button.
Register your application and select your desired type of Api-Key. We provide two key options.
- Issue a new key for Getty Test
  - Use to test Getty Images Connect functionality including: image search and metadata, download, and account management.
- Issue a new key for Connect Embed
  - Use to search for and embed from over 40 million embeddable images.

If you do not have a Mashery Member account

Register a new Mashery Member account and your application.
Select your desired type of Api-Key. We provide two key options.
- Issue a new key for Getty Test
  - Use to test Getty Images Connect functionality including: image search and metadata, download, and account management.
- Issue a new key for Connect Embed
  - Use to search for and embed from over 40 million embeddable images.
Click Register. You will receive an email presently with a confirmation link. Click the link.
Sign in with your Mashery Member credentials.

After registering an application and receiving an Api-Key

Finish reading this overview.
Play with and learn more about the technical details using our interactive endpoint documentation.
Begin developing your application! All calls must be authenticated with your Api-Key. To authorize access to protected resources (e.g. https://connect.gettyimages.com/v3/downloads/{id}) get an access token using the OAuth 2 client credentials flow.

Current Version

Connect is currently at version 3. Use the following base URI to access version 3 endpoints.

https://connect.gettyimages.com/v3/

Authentication

Connect 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://connect.gettyimages.com/v3/images/452224426"

Authorization

Connect 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://connect.gettyimages.com/v3/downloads/83454811 -d "'" -L -o sample.jpg

Acquire an access token using one of the Connect OAuth2 flows. This example uses the OAuth2 client credentials flow.

curl -d 'grant_type=client_credentials&client_id=j878g39yx378pa77djthzzpn&client_secret=hZJS5A3GJpJvcGhaXwev3kwmq3DgtfcQmEuGbGruQBfsz' "https://connect.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, Connect 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

Connect 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 Connect access is over HTTPS. All data is sent and received as JSON.

curl -i -H "Api-Key:j878g39yx378pa77djthzzpn" "https://connect.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 */ ]}

Connect 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 Connect 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://connect.gettyimages.com/v3/images/452224426
curl -i -H "Api-Key:j878g39yx378pa77djthzzpn" "https://connect.gettyimages.com/v3/images/452224426?fields=summary_set

Connect provides a detail_set specifier that will include additional fields.

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

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

HTTP Verbs

Connect 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 creating a resource or perform a custom action
PUT	unsupported at this time
DELETE	unsupported at this time

Parameters

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

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

Additional options can be specified as HTTP querystring parameters.

curl -i -H "Api-Key:j878g39yx378pa77djthzzpn" "https://connect.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://connect.gettyimages.com/v3/images/452224426?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 Connect 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",
         "largestDownloads": [
            {
                "product-type": "premiumaccess",
                "uri": "https://connect.gettyimages.com/Public/3.0/downloads/3231670"
            }
        ]
    }
]

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

HTTP Redirects

Connect 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. Connect currently uses 302 Found and 303 See Other for redirects.

Errors

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

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

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

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

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

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 Connect 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. The maximum page_size is 100.

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

curl -H "Api-Key:j878g39yx378pa77djthzzpn" "https://connect.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://connect.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

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

Workflow example: Connect client using oEmbed

Call CreateSession or OAuth with system/key and user credentials to create an authentication token.
Call SearchForImages to find images specifying the search is for embeddable images only, by adding the Filter property EmbedContentOnly (boolean) within the SearchForImagesRequestBody.
Call oEmbed with each of the asset ids of the embeddable images that you wish to use.

Name		Name	Last commit message	Last commit date
Latest commit History 512 Commits
code-samples		code-samples
documentation/endpoints/oembed		documentation/endpoints/oembed
v2		v2
README.md		README.md
oauth2.md		oauth2.md
release-notes.md		release-notes.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Getty Images Connect API 3.0

New Features

Quick links

Getting Started

If you already have a Mashery Member account

If you do not have a Mashery Member account

After registering an application and receiving an Api-Key

Connect Overview

Current Version

Authentication

Authorization

Request Throttling

Schema

Summary, Detail, and Custom Representations

Download Sizes

Display Sizes

Resources

HTTP Verbs

Parameters

Hypermedia

HTTP Redirects

Errors

Pagination

Cross Origin Resource Sharing

Localization

oEmbed

What is oEmbed?

Endpoint

Request

Response

Workflow example: oEmbed

Workflow example: Connect client using oEmbed

About

Releases

Packages

Languages

bryceageno/connect

Folders and files

Latest commit

History

Repository files navigation

Getty Images Connect API 3.0

New Features

Quick links

Getting Started

If you already have a Mashery Member account

If you do not have a Mashery Member account

After registering an application and receiving an Api-Key

Connect Overview

Current Version

Authentication

Authorization

Request Throttling

Schema

Summary, Detail, and Custom Representations

Download Sizes

Display Sizes

Resources

HTTP Verbs

Parameters

Hypermedia

HTTP Redirects

Errors

Pagination

Cross Origin Resource Sharing

Localization

oEmbed

What is oEmbed?

Endpoint

Request

Response

Workflow example: oEmbed

Workflow example: Connect client using oEmbed

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages