Getty Images Editorial API
The Editorial API from Getty Images — 2 operation(s) for editorial.
OpenAPI Specification
openapi: 3.0.1
info:
title: Getty Images Editorial API
version: '3'
description: '
Developer resources for the Getty Images API including SDK, documentation,
release notes, status, notifications and sample code.'
security:
- Api-Key: []
- OAuth2: []
tags:
- name: Editorial
paths:
/v3/search/images/editorial:
get:
tags:
- Editorial
summary: Search for editorial images only
description: "Use this endpoint to search our editorial stock photos, illustrations and archival images. Editorial images represent newsworthy events or illustrate matters of general interest, such as news, sport and entertainment and are generally intended for editorial use.\n\nYou'll need an API key and access token to use this resource.\n\nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou 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](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token.\nTo include your API token in the search request, add it to the headers as a Bearer token (example in curl):\n\n\t-H \"Authorization: Bearer <your-token>\"\n\nSearch requests without a phrase parameter are not supported and may not always work.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **summary_set** query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every image in your result set when you include **summary_set** in your request.\n\n```\n{\n \"images\": \n [\n \"asset_family\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"display_sizes\": \n [\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"max_dimensions\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **detail_set** query string parameter fields value represents a large batch of metadata fields that are often used to build a detailed view of images. The following fields are provided for every image in your result set when you include **detail_set** in your request.\n\n```\n{\n \"images\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\",\n \"call_for_image\",\n \"caption\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\": \n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"editorial_segments\",\n \"event_ids\",\n \"graphical_style\",\n \"license_model\",\n \"max_dimensions\",\n \"orientation\",\n \"product_types\",\n \"quality_rank\",\n \"referral_destinations\",\n \"title\"\n ]\n]\n```\n\n#### Display Fields Set\n\nThe **display_set** query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most frequently used to build a UI displaying search results. The following fields are provided for every image in your result set when you include **display_set** in your request.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"images\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"comp\",\n \"uri\": \"<link>\"\n },\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"preview\",\n \"uri\": \"<link>\"\n },\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"thumb\",\n \"uri\": \"<link>\"\n }\n ]\n ]\n}\n```"
parameters:
- name: Accept-Language
in: header
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).'
schema:
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).'
- name: GI-Country-Code
in: header
description: Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
schema:
type: string
description: Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more.
- name: age_of_people
in: query
description: Filter based on the age of individuals in an image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AgeOfPeopleFilterType'
description: Filter based on the age of individuals in an image.
nullable: true
- name: artists
in: query
description: Search for images by specific artists (free-text, comma-separated list of artists).
schema:
type: string
description: Search for images by specific artists (free-text, comma-separated list of artists).
nullable: true
- name: collection_codes
in: query
description: Filter by collections (comma-separated list of collection codes). Include or exclude based on collections_filter_type.
style: form
explode: false
schema:
type: array
items:
type: string
description: Filter by collections (comma-separated list of collection codes). Include or exclude based on collections_filter_type.
nullable: true
- name: collections_filter_type
in: query
description: Use to include or exclude collections from search. The default is include
schema:
$ref: '#/components/schemas/CollectionsFilterType'
- name: compositions
in: query
description: Filter based on image composition.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CompositionsFilterType'
description: Filter based on image composition.
nullable: true
- name: date_from
in: query
description: Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
schema:
type: string
description: Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
format: date-time
nullable: true
- name: date_to
in: query
description: Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
schema:
type: string
description: Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
format: date-time
nullable: true
- name: download_product
in: query
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
schema:
type: string
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
nullable: true
- name: editorial_segments
in: query
description: Return only events with a matching editorial segment.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialSegmentContract'
description: Return only events with a matching editorial segment.
nullable: true
- name: embed_content_only
in: query
description: Restrict search results to embeddable images. The default is false.
schema:
type: boolean
description: Restrict search results to embeddable images. The default is false.
default: false
- name: ethnicity
in: query
description: Filter search results based on the ethnicity of individuals in an image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EthnicityFilterType'
description: Filter search results based on the ethnicity of individuals in an image.
nullable: true
- name: event_ids
in: query
description: Filter based on specific events
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: Filter based on specific events
nullable: true
- name: exclude_keyword_ids
in: query
description: Return only images not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also do not contain the requested keyword(s) are returned.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: Return only images not tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also do not contain the requested keyword(s) are returned.
nullable: true
- name: fields
in: query
description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.'
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialImagesFieldValues'
description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes, height, and width returned by ''download_sizes'' field are estimates.'
nullable: true
- name: file_types
in: query
description: Return only images having a specific file type.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/SearchFileType'
description: Return only images having a specific file type.
nullable: true
- name: graphical_styles
in: query
description: Filter based on graphical style of the image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialGraphicalStyle'
description: Filter based on graphical style of the image.
nullable: true
- name: graphical_styles_filter_type
in: query
description: Provides searching based on specified graphical style(s). The default is include.
schema:
$ref: '#/components/schemas/GraphicalStylesFilterType'
- name: include_related_searches
in: query
description: Specifies whether or not to include related searches in the response. The default is false.
schema:
type: boolean
description: Specifies whether or not to include related searches in the response. The default is false.
default: false
- name: keyword_ids
in: query
description: Return only images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: Return only images tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those images matching the query phrase which also contain the requested keyword(s) are returned.
nullable: true
- name: minimum_size
in: query
description: Filter based on minimum size requested. The default is x-small.
schema:
$ref: '#/components/schemas/TeeShirtSize'
- name: number_of_people
in: query
description: Filter based on the number of people in the image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/NumberOfPeopleFilterType'
description: Filter based on the number of people in the image.
nullable: true
- name: orientations
in: query
description: Return only images with selected aspect ratios.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageOrientationRequest'
description: Return only images with selected aspect ratios.
nullable: true
- name: page
in: query
description: Request results starting at a page number (default is 1).
schema:
type: integer
description: Request results starting at a page number (default is 1).
format: int32
default: 1
- name: page_size
in: query
description: Request number of images to return in each page. Default is 30, maximum page_size is 100.
schema:
type: integer
description: Request number of images to return in each page. Default is 30, maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Search images using a search phrase.
schema:
type: string
description: Search images using a search phrase.
nullable: true
- name: sort_order
in: query
description: Select sort order of results. The default is best_match
schema:
$ref: '#/components/schemas/SortOrder'
- name: specific_people
in: query
description: Return only images associated with specific people (using a comma-delimited list).
style: form
explode: false
schema:
type: array
items:
type: string
description: Return only images associated with specific people (using a comma-delimited list).
nullable: true
- name: minimum_quality_rank
in: query
description: Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best.
schema:
type: integer
description: Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best.
format: int32
nullable: true
- name: facet_fields
in: query
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialImageSearchFacetsFields'
description: "Specifies the facets to return in the response. Facets provide additional search parameters to refine your results.\r\n The include_facets parameter must be set to \"true\" for facets to be returned."
nullable: true
- name: include_facets
in: query
description: Specifies whether or not to include facets in the result set. Default is "false".
schema:
type: boolean
description: Specifies whether or not to include facets in the result set. Default is "false".
nullable: true
- name: facet_max_count
in: query
description: Specifies the maximum number of facets to return per type. Default is 300.
schema:
type: integer
description: Specifies the maximum number of facets to return per type. Default is 300.
format: int32
default: 300
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EditorialImageSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
/v3/search/videos/editorial:
get:
tags:
- Editorial
summary: Search for editorial videos
description: "Use this endpoint to search current and archival video clips of celebrities, newsmakers, and events.\n\nYou'll need an API key and access token to use this resource.\n\nYou can show different information in the response by specifying values on the \"fields\" parameter (see details below).\nYou 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](http://developers.gettyimages.com/en/authorization-faq.html) for more information on authorization tokens, and our [Authorization Workflows](https://github.com/gettyimages/gettyimages-api/blob/master/OAuth2Workflow.md) for code examples of getting a token.\n\nSearch requests without a phrase parameter are not supported and may not always work.\n\n## Working with Fields Sets\n\nFields sets are used in the **fields** request parameter to receive a suite of metadata fields. The following fields sets are available:\n\n#### Summary Fields Set\n\nThe **summary_set** query string parameter fields value represents a small batch of metadata fields that are often used to build search response results. The following fields are provided for every video in your result set when you include **summary_set** in your request.\n\n```\n{\n \"videos\": \n [\n \"asset_family\", \n \"caption\",\n \"collection_code\",\n \"collection_name\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"license_model\",\n \"title\"\n ]\n}\n```\n\n#### Detail Fields Set\n\nThe **detail_set** query string parameter fields value represents a large batch of metadata fields that are often used to build a detailed view of videos. The following fields are provided for every video in your result set when you include **detail_set** in your request.\n\n```\n{\n \"videos\": \n [\n \"allowed_use\",\n \"artist\",\n \"asset_family\", \n\t\t\"call_for_image\",\n \"caption\", \n \"clip_length\",\n \"collection_code\",\n \"collection_id\",\n \"collection_name\", \n \"color_type\",\n \"copyright\",\n \"date_created\",\n \"display_sizes\":\n [\n {\n \"name\": \"comp\"\n },\n {\n \"name\": \"preview\"\n },\n {\n \"name\": \"thumb\"\n }\n ],\n \"era\",\n \"event_ids\",\n \"license_model\",\n \"mastered_to\",\n \"originally_shot_on\",\n \"product_types\",\n \"quality_rank\",\n \"shot_speed\",\n \"source\",\n \"title\"\n ]\n}\n```\n\n#### Display Fields Set\n\nThe **display_set** query string parameter fields value represents the fields that provide you with URLs for the low resolution files that are most frequently used to build a UI displaying search results. The following fields are provided for every video in your result set when you include **display_set** in your request.\n\nThe URI provided is subject to change at any time and must be used as-is with no modification.\n\n```\n{\n \"videos\":\n [\n \"display_sizes\": \n [\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"comp\",\n \"uri\": \"<link>\"\n },\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"preview\",\n \"uri\": \"<link>\"\n },\n {\n \"is_watermarked\": <boolean>,\n \"name\": \"thumb\",\n \"uri\": \"<link>\"\n }\n ]\n ]\n}\n```"
parameters:
- name: Accept-Language
in: header
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).'
schema:
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).'
- name: GI-Country-Code
in: header
description: Receive regionally relevant search results based on the value specified. Accepts only ISO Alpha-3 country codes. The Countries operation can be used to retrieve the codes.
schema:
type: string
description: Use of this parameter requires configuration changes to your API key. Please contact your sales representative to learn more.
- name: age_of_people
in: query
description: Provides filtering according to the age of individuals in a video.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/AgeOfPeopleFilterType'
description: Provides filtering according to the age of individuals in a video.
nullable: true
- name: artists
in: query
description: Search for videos by specific artists (free-text, comma-separated list of artists).
schema:
type: string
description: Search for videos by specific artists (free-text, comma-separated list of artists).
nullable: true
- name: aspect_ratios
in: query
description: Search for videos by specific aspect ratios.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoAspectRatioFilterType'
description: Search for videos by specific aspect ratios.
nullable: true
- name: collection_codes
in: query
description: Provides filtering by collection code.
style: form
explode: false
schema:
type: array
items:
type: string
description: Provides filtering by collection code.
nullable: true
- name: collections_filter_type
in: query
description: Use to include or exclude collections from search. The default is include
schema:
$ref: '#/components/schemas/CollectionsFilterType'
- name: compositions
in: query
description: Filter based on video composition.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/CompositionsFilterType'
description: Filter based on video composition.
nullable: true
- name: date_from
in: query
description: Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
schema:
type: string
description: Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
format: date-time
nullable: true
- name: date_to
in: query
description: Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
schema:
type: string
description: Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
format: date-time
nullable: true
- name: download_product
in: query
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
schema:
type: string
description: "Filters based on which product the asset will download against.\r\n Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription.\r\n If you have more than one instance of a product, you may also include the ID of the product instance you wish to filter on. \r\n For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. \r\n Product ID can be obtained from the GET /products response."
nullable: true
- name: editorial_video_types
in: query
description: Allows filtering by types of video.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialVideoType'
description: Allows filtering by types of video.
nullable: true
- name: event_ids
in: query
description: Filter based on specific events
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: Filter based on specific events
nullable: true
- name: fields
in: query
description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.'
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EditorialVideosFieldValues'
description: 'Specifies fields to return. Defaults to ''summary_set''. NOTE: Bytes returned by ''download_sizes'' field is an estimate.'
nullable: true
- name: format_available
in: query
description: Filters according to the digital video format available on a film asset.
schema:
$ref: '#/components/schemas/VideoFormatsRequest'
- name: frame_rates
in: query
description: Provides filtering by video frame rate (frames/second).
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/VideoFrameRates'
description: Provides filtering by video frame rate (frames/second).
nullable: true
- name: image_techniques
in: query
description: Filter based on image technique.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/ImageTechniquesFilterType'
description: Filter based on image technique.
nullable: true
- name: include_related_searches
in: query
description: Specifies whether or not to include related searches in the response. The default is false.
schema:
type: boolean
description: Specifies whether or not to include related searches in the response. The default is false.
default: false
- name: keyword_ids
in: query
description: Return only videos tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also contain the requested keyword(s) are returned.
style: form
explode: false
schema:
type: array
items:
type: integer
format: int32
description: Return only videos tagged with specific keyword(s). Specify using a comma-separated list of keyword Ids. If keyword Ids and phrase are both specified, only those videos matching the query phrase which also contain the requested keyword(s) are returned.
nullable: true
- name: min_clip_length
in: query
description: Provides filtering by minimum length of video clip, in seconds
schema:
type: integer
description: Provides filtering by minimum length of video clip, in seconds
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/getty-images/refs/heads/main/openapi/getty-images-editorial-api-openapi.yml