GET /v3/search/images

This endpoint draws from such a large diversity of content, the results will not be as relevant as when the more specific Creative or Editorial endpoints are used. Additionally, the response time for this endpoint is slower compared to that for Creative and Editorial-specific endpoints. For these reasons, it is highly recommended that those endpoints are used instead of this blended endpoint.

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

Search requests without a phrase parameter are not supported and may not always work.

Working with Fields Sets

Fields sets are used in the fields request parameter to receive a suite of metadata fields. The following fields sets are available:

Summary Fields Set

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

{
    "images": 
    [
        "asset_family",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "display_sizes": 
        [
            {
                "name": "thumb"
            }
        ],
        "license_model",
        "max_dimensions",
        "title"
    ]
}

Detail Fields Set

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

{
    "images": 
    [
        "allowed_use",
        "artist",
        "asset_family",
        "call_for_image",
        "caption",
        "collection_code",
        "collection_id",
        "collection_name",
        "copyright",
        "date_created",
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ],
        "editorial_segments",
        "event_ids",
        "graphical_style",
        "license_model",
        "max_dimensions",
        "orientation",
        "product_types",
        "quality_rank",
        "referral_destinations",
        "title"
    ]
]

Display Fields Set

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

The URI provided is subject to change at any time and must be used as-is with no modification.

{
    "images":
    [
        "display_sizes": 
        [
            {
                "is_watermarked": <boolean>,
                "name": "comp",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "preview",
                "uri": "<link>"
            },
            {
                "is_watermarked": <boolean>,
                "name": "thumb",
                "uri": "<link>"
            }
        ]
    ]
}

Request Usage Considerations

Specifying the "entity_details" response field can have significant performance implications. The field should be used only when necessary.

Servers

https://api.gettyimages.com

Request headers

Name	Type	Required	Description
`GI-Country-Code`	String	No	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.
`Accept-Language`	String	No	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).

Query parameters

Name	Type	Required	Description
`include_related_searches`	Boolean	No	Specifies whether or not to include related searches in the response. The default is false. Default value: false
`number_of_people[]`	Array	No	Filter based on the number of people in the image.
`page_size`	Integer	No	Request number of images to return in each page. Default is 30, maximum page_size is 100. Default value: 30
`keyword_ids[]`	Array	No	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.
`exclude_nudity`	Boolean	No	Excludes images containing nudity. The default is false. Default value: false
`file_types[]`	Array	No	Return only images having a specific file type.
`ethnicity[]`	Array	No	Filter search results based on the ethnicity of individuals in an image.
`sort_order`	String	No	Select sort order of results. The default is best_match Valid values: `"newest"` `"most_popular"` `"best_match"` `"random"`
`embed_content_only`	Boolean	No	Restrict search results to embeddable images. The default is false. Default value: false
`graphical_styles[]`	Array	No	Filter based on graphical style of the image.
`artists`	String	No	Search for images by specific artists (free-text, comma-separated list of artists).
`compositions[]`	Array	No	Filter based on image composition.
`minimum_size`	String	No	Filter based on minimum size requested. The default is x-small Valid values: `"medium"` `"large"` `"small"` `"vector"` `"x_small"` `"x_large"` `"xx_large"`
`phrase`	String	No	Search images using a search phrase.
`download_product`	String	No	Filters based on which product the asset will download against. Allowed values are easyaccess, editorialsubscription, imagepack, premiumaccess and royaltyfreesubscription. 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. For example, some users may have more than one premiumaccess product, so the download_product value would be premiumaccess:1234. Product ID can be obtained from the GET /products response.
`fields[]`	Array	No	Specifies fields to return. Defaults to 'summary_set'.
`event_ids[]`	Array	No	Filter based on specific events
`collection_codes[]`	Array	No	Filter by collection codes (comma-separated list). Include or exclude based on collections_filter_type.
`page`	Integer	No	Request results starting at a page number (default is 1). Default value: 1
`graphical_styles_filter_type`	String	No	Provides searching based on specified graphical style(s). The default is Include Valid values: `"include"` `"exclude"`
`orientations[]`	Array	No	Return only images with selected aspect ratios.
`specific_people[]`	Array	No	Return only images associated with specific people (using a comma-delimited list).
`collections_filter_type`	String	No	Provides searching based on specified collection(s). The default is Include Valid values: `"include"` `"exclude"`
`age_of_people[]`	Array	No	Filter based on the age of individuals in an image.
`color`	String	No	Filter based on predominant color in an image. Use 6 character hexidecimal format (e.g., #002244). Note: when specified, results will not contain editorial images.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.