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.
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:<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.
- 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." }
- 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" }
- Submitting invalid image
id
’s will result in a404 Not Found
response.HTTP/1.1 404 Not Found Content-Type: application/vnd.getty.error+json { "code": "ImageNotFound", "message": "Image not found: 452O76944" }
- 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 perpage
. 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
- 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: Getty Images API client using oEmbed
- Get an access token as described in the authorization section.
- Search for an image, adding the
embed_content_only=true
parameter to the querystring. - Call oEmbed with each of the asset ids of the embeddable images that you wish to use.