Experiment with this API

Search For Events

Use this endpoint to search Getty Images news, sports and entertainment events. Getty Images photographers and videographers cover editorially relevant events occurring around the world. All images or video clips produced in association with an event, are assigned the same EventID. EventIDs are part of the meta-data returned in Search Results. Only content produced under a Getty Images brand name (Getty Images News, Getty Images Sports, Getty Images Entertainment, Film Magic, Wire Image) will be consistently assigned an EventID. The Event framework may also be used to group similar content, such as "Hats from the Royal Wedding" or "Odd-ballOffbeat images of the week".

Quickstart

You'll need an API key and access token to use this resource. Please see our Getting Started page for more information on how to sign up for an API key. There are several SDKs available for popular programming languages to help you get started.

Use the following endpoint to search for images:

GET https://api.gettyimages.com/v3/search/images?phrase=<query term>

Add your API key to the request header:

Api-Key: <your api key>

Your request would look like this using curl:

curl -X GET -H "Api-Key: <your api key>" https://api.gettyimages.com/v3/search/images?phrase=<query term>

The response body will look like the following example:

{
    "result_count": 2,
    "images": [
    {
        "id": "<creative image id>}",
        "asset_family": "creative",
        "caption": "<image description>",
        "collection_code": "<collection code>",
        "collection_id": <collection id>,
        "collection_name": "<collection name>",
        "display_sizes": [
        {
            "is_watermarked": false,
            "name": "thumb",
            "uri": "<display url>"
        }
        ],
        "license_model": "rightsmanaged",
        "max_dimensions": {
        "height": 2738,
        "width": 4442
        },
        "title": "<image title>"
    },
    {
        "id": "<editorial image id>}",
        "asset_family": "editorial",
        "caption": "<image description>",
        "collection_code": "<collection code>",
        "collection_id": <collection id>,
        "collection_name": "<collection name>",
        "display_sizes": [
        {
            "is_watermarked": false,
            "name": "thumb",
            "uri": "<display url>"
        }
        ],
        "license_model": "rightsmanaged",
        "max_dimensions": {
        "height": 2738,
        "width": 4442
        },
        "title": "<image title>"
    }
    ]
}

You can show different information in the response by specifying values on the "fields" parameter (see details below). You can search with only an API key, and that will give you search results that are equivalent to doing a search on the GettyImages.com site without being logged in (anonymous search). If you are a Getty Images API customer and would like to ensure that your API searches return only assets that you have a license to use, you need to also include an authorization token in the header of your request. Please consult our Authorization FAQ for more information on authorization tokens, and our Authorization Workflows for code examples of getting a token. To include your API token in the search request, add it to the headers as a Bearer token (example in curl):

-H "Authorization: Bearer <your-token>"

Request Headers

Api-Key string Provide your API key. Required.
Accept-Language string Specifies the language of result values.
Authorization string Provide access token in the format of 'Bearer {token}'.

Querystring Parameters

date_from string Filters to events that start on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
date_to string Filters to events that start on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
editorial_segment string Filters to events with a matching editorial segment. Possible values: archival entertainment news publicity royalty sport
fields array Specifies fields to return. Default set is 'id','name','start_date'. Possible values: id child_event_count editorial_segments hero_image image_count keywords location name start_date type
phrase string Return only images tagged with specific phrase

Sorting and Pagination

page integer Request results starting at a page number (default is 1).
page_size integer Request number of images to return in each page.

Response Body Fields

events_result

events array [ event ] Lists the event ids matching the search criteria.
result_count integer Specifies the count of matching images returned.

event

child_event_count integer Specifies the count of children events associated with this event.
editorial_segments array [ string ] Lists the editorial segments for this asset. Possible values are archival, entertainment, news, publicity, royalty, sport.
hero_image Spcifies the image that best captures the event.
id integer Specifies the unique identifier for the event.
image_count integer Specifies the count of images associated with event.
location Specifies the location where the event took place.
name string Specifies the name of the event.
start_date string Specifies the start date of event, in ISO 8601 format (e.g., 1999-12-31T00:00:00-00:00).

hero_image

id string Specifies the image id of the image that best captures the associated group of images.
display_sizes array [ hero_display_size ] Lists the display sizes available for this image.

hero_display_size

name string Specifies the name of the display size.
is_watermarked boolean Specifies whether the image is watermarked.
uri string GET this URI to retrieve the display size image.

location

city string Specifies the city where the event took place.
country string Specifies the country where the event took place.
state_province string Specifies the state or province where the event took place.
venue string Specifies the venue where the event took place.

Response Status Codes

200 OK
400 InvalidParameterValue
400 InvalidPage
400 InvalidPageSize
400 UnknownProviderUri
400 IncorrectlyFormedUri
400 MalformedRequest
400 SearchPhraseOrEditorialSegmentRequired
401 AuthorizationTokenRequired
401 Unauthorized
403 UnauthorizedDisplaySize
403 NoAccessToProductType

Some response items contain hyperlinks which you can use to take you directly to the next steps in your workflow, when appropriate. The following URIs are provided in the response for this request.

hero_display_size.uri string GET this URI to retrieve the display size image.