Search for events

v1.0.0

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

You'll need an API key and access token to use this resource.

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 for more information on authorization tokens, and our for code examples of getting a token.

Input

{
  "type": "object",
  "properties": {
    "Accept-Language": {
      "type": "string",
      "description": "Provide a header to specify the language of result values. Supported values: cs (iStock only), de, en-GB, en-US, es, fi (iStock only), fr, hu (iStock only), id (iStock only), it, ja, ko (creative assets only), nl, pl (creative assets only), pt-BR, pt-PT, ro (iStock only), ru (creative assets only), sv, th (iStock only), tr, uk (iStock only), vi (iStock only), zh-HK (creative assets only)."
    },
    "GI-Country-Code": {
      "type": "string",
      "description": "Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more."
    },
    "date_from": {
      "type": "string",
      "format": "date-time",
      "description": "Filters to events that start on or after this date. Use ISO 8601 format (e.g., 1999-12-31). Defaults to UTC unless otherwise specified."
    },
    "date_to": {
      "type": "string",
      "format": "date-time",
      "description": "Filters to events that start on or before this date. Use ISO 8601 format (e.g., 1999-12-31). Defaults to UTC unless otherwise specified."
    },
    "editorial_segment": {
      "type": "string",
      "enum": [
        "archival",
        "entertainment",
        "news",
        "publicity",
        "royalty",
        "sport"
      ]
    },
    "fields": {
      "type": "array",
      "description": "Specifies fields to return. Default set is 'id','name','start_date'.",
      "items": {
        "type": "string",
        "enum": [
          "id",
          "child_event_count",
          "editorial_segments",
          "hero_image",
          "image_count",
          "keywords",
          "location",
          "name",
          "start_date",
          "type"
        ]
      }
    },
    "page": {
      "type": "integer",
      "format": "int32",
      "description": "Request results starting at a page number (default is 1, maximum is 50)."
    },
    "page_size": {
      "type": "integer",
      "format": "int32",
      "description": "Request number of events to return in each page. Default is 30, maximum page_size is 100."
    },
    "phrase": {
      "type": "string",
      "description": "Filters to events related to this phrase"
    },
    "sort_order": {
      "type": "string",
      "enum": [
        "newest",
        "oldest"
      ]
    }
  },
  "additionalProperties": false
}

Output

{
  "type": "object",
  "properties": {
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "child_event_count": {
            "type": "integer",
            "format": "int32"
          },
          "editorial_segments": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "hero_image": {
            "type": "object",
            "properties": {
              "display_sizes": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "is_watermarked": {
                      "type": "boolean"
                    },
                    "name": {
                      "type": "string"
                    },
                    "uri": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false
                }
              },
              "id": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "image_count": {
            "type": "integer",
            "format": "int32"
          },
          "location": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "state_province": {
                "type": "string"
              },
              "venue": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "name": {
            "type": "string"
          },
          "start_date": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": false
      }
    },
    "result_count": {
      "type": "integer",
      "format": "int32"
    }
  },
  "additionalProperties": false
}