Getty Images Search API
The Search API from Getty Images — 11 operation(s) for search.
OpenAPI Specification
openapi: 3.0.1
info:
title: Getty Images Search 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: Search
paths:
/v3/affiliates/search/images:
get:
tags:
- Search
summary: ''
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: phrase
in: query
description: Search images using a search phrase.
schema:
type: string
description: Search images using a search phrase.
nullable: true
- name: style
in: query
description: Filter based on graphical style of the image.
schema:
$ref: '#/components/schemas/AffiliateSearchStyle'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AffiliateImageSearchResponse'
/v3/affiliates/search/videos:
get:
tags:
- Search
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: phrase
in: query
schema:
type: string
nullable: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AffiliateVideoSearchResponse'
/v3/search/events:
get:
tags:
- Search
summary: Search for events
description: '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 a specific event are assigned the same event ID. Event IDs are part of the metadata 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 event ID.
This endpoint will provide events based on a search phrase or editorial segment and an optional from/to date filter. You can show different information in the response by specifying values on the "fields" parameter. The results will include events whose associated images or videos may not be included in your product(s).
This endpoint requires only an API key. An access token is NOT required.
'
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: editorial_segment
in: query
description: Filters to events with a matching editorial segment.
schema:
$ref: '#/components/schemas/EditorialSegmentContract'
- name: date_from
in: query
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.
schema:
type: string
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.
format: date-time
nullable: true
- name: date_to
in: query
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.
schema:
type: string
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.
format: date-time
nullable: true
- name: fields
in: query
description: Specifies fields to return. Default set is 'id','name','start_date'.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/EventFieldValues'
description: Specifies fields to return. Default set is 'id','name','start_date'.
nullable: true
- name: page
in: query
description: Request results starting at a page number (default is 1, maximum is 50).
schema:
type: integer
description: Request results starting at a page number (default is 1, maximum is 50).
format: int32
default: 1
- name: page_size
in: query
description: Request number of events to return in each page. Default is 30, maximum page_size is 100.
schema:
type: integer
description: Request number of events to return in each page. Default is 30, maximum page_size is 100.
format: int32
default: 30
- name: phrase
in: query
description: Filters to events related to this phrase
schema:
type: string
description: Filters to events related to this phrase
default: ''
nullable: true
- name: sort_order
in: query
description: Specifies the order in which to sort the results. Default is `newest`.
schema:
$ref: '#/components/schemas/EventSearchSortOrder'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EventsSearchResult'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
/v3/search/images/creative:
get:
tags:
- Search
summary: Search for creative images only
description: "Use this endpoint to search our contemporary stock photos, illustrations and archival images.\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 \nbuild 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 \nbuild 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\nfiles that are most frequently used to build a UI displaying search results. The following fields are provided for every image \nin 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```\n\n## Enhanced Search\n\nOur enhanced search uses machine-learning models to understand natural, conversational language. Meaning you can search for longer phrases and get more relevant results from our creative image and creative video libraries. Default is `true`. Set `enhanced_search` to `false` if you require a precise result set and not one expanded through enhanced search."
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 collection codes (comma-separated list). Include or exclude based on collections_filter_type.
style: form
explode: false
schema:
type: array
items:
type: string
description: Filter by collection codes (comma-separated list). 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: color
in: query
description: 'Filter based on predominant color in an image. Use 6 character hexadecimal format (e.g., #002244).'
schema:
type: string
description: 'Filter based on predominant color in an image. Use 6 character hexadecimal format (e.g., #002244).'
nullable: true
- 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: 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: 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: enhanced_search
in: query
description: If set to {false}, your search will not use enhanced search. Defaults to {true}.
schema:
type: boolean
description: If set to {false}, your search will not use enhanced search. Defaults to {true}.
default: true
nullable: true
- 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: exclude_editorial_use_only
in: query
description: Exclude images that are only available for editorial (non-commercial) use. Default value is false.
schema:
type: boolean
description: Exclude images that are only available for editorial (non-commercial) use. Default value is false.
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: exclude_nudity
in: query
description: Excludes images containing nudity. The default is false.
schema:
type: boolean
description: Excludes images containing nudity. The default is false.
default: false
- 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/CreateImageSearchFacetsFields'
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: 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
- 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/CreativeImagesFieldValues'
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/GraphicalStyle'
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_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: 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: moods
in: query
description: Filter based on predominant mood in an image.
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/MoodFilterType'
description: Filter based on predominant mood in an image.
nullable: true
- 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.
default: ''
nullable: true
- name: safe_search
in: query
description: Setting safe_search to "true" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter. Please direct feedback to your Getty Images Account or API support representative.
schema:
type: boolean
description: Setting safe_search to "true" excludes images containing nudity, death, profanity, drugs and alcohol, suggestive content, and graphic content from the result set. The default is false. Because this is a keyword-based filter, it's possible that a small number of unsafe images may not be caught by the filter. Please direct feedback to your Getty Images Account or API support representative.
default: false
- name: sort_order
in: query
description: Select sort order of results. The default is best_match
schema:
$ref: '#/components/schemas/CreativeImageSortOrder'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreativeImageSearchResults'
'400':
description: InvalidParameterValue
'401':
description: AuthorizationTokenRequired
'403':
description: UnauthorizedDisplaySize
'500':
description: InvalidIStockCollection
/v3/search/images/creative/by-image:
get:
tags:
- Search
summary: Search for creative images based on url
description: 'Search for **similar creative images** by passing an `image_url` to an uploaded image OR an `asset_id` of an asset in our catalog. All responses will have the `exclude_nudity` filter automatically applied.
## Searching by URL
Before calling the search by image endpoint, an image in JPEG format must be uploaded to `https://api.gettyimages.com/v3/search/by-image/uploads/{CLIENT_IMAGE.jpg}`, where the client defines the `{CLIENT_IMAGE.jpg}` portion of the URL.
For example, using cURL:
``` sh
curl -i -X PUT https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg -H ''Content-Type: image/jpeg'' -H ''Api-Key: API_KEY'' --data-binary "@testimage.jpg"
```
Once the image has been uploaded, use the full URL in the `image_url` parameter, e.g. `image_url=https://api.gettyimages.com/v3/search/by-image/uploads/my-test-image.jpg`.
- Uploaded files must be 10MB or smaller.
- Uploads to the same URL will overwrite each other, so ensure that the client application is handling naming uniqueness appropriately.
- Uploads expire after 24 hours.
- Uploads and searches must be performed using the _same_ API Key.
## Searching by asset id
When searching by `asset_id`, any image or video asset id in the Getty/iStock catalog can be used as the source for similar images.
'
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: asset_id
in: query
description: Specifies the Getty image id to use in the search.
schema:
type: string
description: Specifies the Getty image id to use in the search.
nullable: true
- name: exclude_editorial_use_only
in: query
description: Exclude images that are only available for editorial (non-commercial) use. Default value is false.
schema:
type: boolean
description: Exclude images that are only available for editorial (non-commercial) use. Default value is false.
nullable: true
# --- truncated at 32 KB (153 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/getty-images/refs/heads/main/openapi/getty-images-search-api-openapi.yml