Experiment with this API

Search for Similar Images

This endpoint will search our asset database for images similar to the specified asset id. Due to a wide variety of available image resolutions, the images are grouped into a handful of size categories for simplicity.

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 search for similar images:

GET https://api.gettyimages.com/v3/images/<asset id>/similar

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/images/<asset id>/similar

Your response will look like this:

{
    "result_count": 973,
    "images": [
    {
        "id": "AA027431",
        "asset_family": "creative",
        "caption": null,
        "collection_code": "PDI",
        "collection_id": 2,
        "collection_name": "Photodisc",
        "display_sizes": [
        {
            "is_watermarked": false,
            "name": "thumb",
            "uri": "http://delivery.candidate-gettyimages.com/xt/AA027431.jpg?v=1&g=fs1|0|PDI|27|431&s=1&b=RTRE"
        }
        ],
        "license_model": "royaltyfree",
        "max_dimensions": {
        "height": 4094,
        "width": 4094
        },
        "title": "Kitten"
    }
    ...
}

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.

{
    "images":
    [
        "display_sizes": 
        [
            {
                "name": "comp"
            },
            {
                "name": "preview"
            },
            {
                "name": "thumb"
            }
        ]
    ]
}

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}'.

URI Path Parameters

id string Identifies an existing image Required.

Querystring Parameters

fields array Specifies fields to return. Defaults to 'summary_set'. Possible values: accessrestriction allowed_use alternative_ids artist asset_family call_for_image caption collection_code collection_id collection_name color_type comp copyright date_camera_shot date_created detail_set display_set editorial_segments editorial_source entity_details event_ids graphical_style id keywords largest_downloads license_model max_dimensions orientation people prestige preview product_types quality_rank referral_destinations summary_set thumb title uri_oembed istock_licenses

Sorting and Pagination

page integer Identifies page to return. Default is 1.
page_size integer Specifies page size. Default is 30, maximum page_size is 100.

Response Status Codes

200 OK
400 InvalidParameterValue
400 MalformedRequest
400 InvalidPage
400 InvalidPageSize
400 ImageIdMustBeSpecified
401 AuthorizationTokenRequired
401 Unauthorized
403 UnauthorizedDisplaySize
404 ImageNotFound