Experiment with this API

Get Metadata for Multiple Events

This endpoint returns the detailed event metadata for all specified events. Getty Images news, sports and entertainment 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 SearchForImages 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 retrieve metadata for multiple events:

GET https://api.gettyimages.com/v3/events?ids=<event id>,< event id>

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/events?ids=<event id>

Your response will look like this:

{
    "events": [{
        "child_event_count": 0,
        "editorial_segments": [""],
        "hero_image": {
            "id": "",
            "display_sizes": [{
                "name": "",
                "is_watermarked": false,
                "uri": ""
            }]
        },
        "id": 0,
        "image_count": 0,
        "location": {
            "city": "",
            "country": "",
            "state_province": "",
            "venue": ""
        },
        "name": "",
        "start_date": ""
    }],
    "events_not_found": [0]
}

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

fields array A comma separated list of fields to return in the response. Possible values: id child_event_count editorial_segments hero_image image_count location name start_date type
ids array A comma separated list of event ids.

Response Body Fields

events_result

events array [ event ] Lists the event ids matching the search criteria.
events_not_found array [ integer ] Lists the event ids which were not found.

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 MalformedRequest
401 Unauthorized
404 EventNotFound

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.