Experiment with this API

Search For Editorial Images

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.

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 editorial images:

GET https://api.gettyimages.com/v3/search/images/editorial?phrase=<query term>

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/search/images/editorial?phrase=<query term>

The response body will look like the following example:

{
    "result_count": 1,
    "images": [
    {
        "id": "<image id>}",
        "asset_family": "editorial",
        "caption": "<image description>",
        "collection_code": "<collection code>",
        "collection_id": <collection id>,
        "collection_name": "<collection name>",
        "display_sizes": [
        {
            "is_watermarked": false,
            "name": "thumb",
            "uri": "<display url>"
        }
        ],
        "license_model": "rightsmanaged",
        "max_dimensions": {
        "height": 2738,
        "width": 4442
        },
        "title": "<image title>"
    }
    ]
}

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

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 Usage Considerations

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

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

Querystring Parameters

age_of_people array Filter based on the age of individuals in an image. Possible values: newborn baby child teenager young_adult adult adults_only mature_adult senior_adult 0-1_months 2-5_months 6-11_months 12-17_months 18-23_months 2-3_years 4-5_years 6-7_years 8-9_years 10-11_years 12-13_years 14-15_years 16-17_years 18-19_years 20-24_years 20-29_years 25-29_years 30-34_years 30-39_years 35-39_years 40-44_years 40-49_years 45-49_years 50-54_years 50-59_years 55-59_years 60-64_years 60-69_years 65-69_years 70-79_years 80-89_years 90_plus_years 100_over
artists string Search for images by specific artists (free-text, comma-separated list of artists).
collection_codes array Filter by collections (comma-separated list of collection codes). Include or exclude based on collections_filter_type.
collections_filter_type string Use to include or exclude collections from search. Possible values: include exclude
color string Filter based on predominant color in an image. Use 6 character hexidecimal format (e.g., #002244).
compositions array Filter based on image composition. Possible values: abstract candid close_up copy_space cut_out full_frame full_length headshot looking_at_camera macro portrait sparse still_life three_quarter_length waist_up
date_from string Return only images that are created on or after this date. Use ISO 8601 format (e.g., 1999-12-31).
date_to string Return only images that are created on or before this date. Use ISO 8601 format (e.g., 1999-12-31).
editorial_segments array Return only events with a matching editorial segment. Possible values: archival entertainment news publicity royalty sport
embed_content_only boolean Restrict search results to embeddable images. The default is false.
entity_uris array specify linked data entity uri.
ethnicity array Filter search results based on the ethnicity of individuals in an image. Possible values: black caucasian east_asian hispanic_latino japanese middle_eastern mixed_race_person multiethnic_group native_american_first_nations pacific_islander south_asian southeast_asian
event_ids array Filter based on specific events
exclude_nudity boolean Excludes images containing nudity. The default is false.
fields array Specifies fields to return. Defaults to 'summary_set'. Possible values: 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 preview product_types quality_rank referral_destinations summary_set thumb title uri_oembed
file_types array Return only images having a specific file type. Possible values: eps jpg
graphical_styles array Filter based on graphical style of the image. Possible values: photography illustration
keyword_ids array 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.
minimum_quality_rank integer Filter search results based on minimum quality ranking. Possible values 1, 2, 3 with 1 being best.
minimum_size string Filter based on minimum size requested. Possible values: x_small small medium large x_large xx_large
number_of_people array Filter based on the number of people in the image. Possible values: none one two group
orientations array Return only images with selected aspect ratios. Possible values: Horizontal Vertical Square PanoramicHorizontal PanoramicVertical
phrase string Search images using a search phrase.
product_types array Filter images to those having product types from the selected list. Possible values: easyaccess editorialsubscription imagepack premiumaccess royaltyfreesubscription creditpack
specific_people array Return only images associated with specific people (using a comma-delimited list).

Sorting and Pagination

page integer Request results starting at a page number (default is 1).
page_size integer Request number of images to return in each page.
sort_order string Select sort order of results. Possible values: best_match most_popular newest oldest

Response Body Fields

editorial_image_search_results

result_count integer Specifies the count of matching images returned.
images array [ editorial_image_search_item ] List of image search results.

editorial_image_search_item

allowed_use Specifies how customers are allowed to use the image.
alternative_ids array [ KeyValuePair[String,String] ] Lists all of the alternative ids for the asset.
artist string Specifies image creator.
asset_family string Indicates the asset family classification. Possible values are: creative, editorial.
call_for_image boolean Indicates whether a customer needs to call Getty Images in order to license this image.
caption string Gives a brief description of the image.
collection_code string Specifies the code of the collection to which the image belongs.
collection_id integer Specifies the id of the collection to which the image belongs.
collection_name string Specifies the name of the collection to which the image belongs.
color_type string Specifies whether the image or video is color or black and white. Possible values are color, black_and_white, and null.
copyright string Specifies the copyright of the image.
date_camera_shot string Specifies the date the image was shot, in ISO 8601 format (e.g., 1999-12-31T00:00:00-00:00).
date_created string Specifies the date the image was created, in ISO 8601 format (e.g., 1999-12-31T00:00:00-00:00).
display_sizes array [ display_size ] Lists the display sizes available for this image.
editorial_segments array [ string ] Lists the editorial segments for this asset. Possible values are archival, entertainment, news, publicity, royalty, sport.
editorial_source Specifies the editorial source of the image
event_ids array [ integer ] Lists the events that are relevant for this image.
graphical_style string Specifies the graphical style for the image. Possible values are Photography, Fine Art, and Illustration.
id string Specifies the unique identifier for the image.
keywords array [ keywords ] Lists the keywords that are associated with this image.
largest_downloads array [ download ] Lists the available largest download sizes.
license_model string Specifies the licensing model for the image. Possible values are: royaltyfree, rightsmanaged.
max_dimensions Specifies the maximum height and width of any size for this image.
orientation string Specifies the orientation of the image. Possible values are: Horizontal, PanoramicHorizontal, PanoramicVertical, Square, Vertical, and null.
people array [ string ] List of people appearing in the image.
product_types array [ string ] Lists the product types for the image. Possible values are: premiumaccess, easyaccess, editorialsubscription, imagepack, royaltyfreesubscription, creditpack.
quality_rank integer Specifies the quality ranking of the image.
referral_destinations array [ referral_destination ] Lists the referral destinations for Getty Images assets.
title string Specifies the image title.
uri_oembed string GET this URI to retrieve oEmbed data for the image, if embeddable.

allowed_use

how_can_i_use_it string Specifies how the asset can be used.
release_info string Specifies the release status.
usage_restrictions array [ string ] Specifies the asset usage restriction.

KeyValuePair[String,String]

Key string
Value string

display_size

is_watermarked boolean Specifies whether the image is watermarked.
name string Specifies the name of the display size.
uri string GET this URI to retrieve the display size image.

EditorialSource

id integer Specifies the editorial source id of the image

keywords

keyword_id string Specifies the unique identifier for the keyword.
text string Provides localized text of the keyword.
type string Specifies the keyword type.
relevance integer Specifies the relevancy of the keyword to the asset. 0-5 or null, 5 being most relevant.
entity_uris array [ string ] Lists the URIs where detailed information can be found for a specific person.
entity_types array [ string ] Lists the person types for a specific person. E.g., 'Musician', 'Politician'.

download

product_id string Specifies the given product based on a company agreement. Applies only to royaltyfreesubscription and imagepack.
product_type string Specifies the license agreement applied to this download. Possible values are: premiumaccess, easyaccess, editorialsubscription, imagepack, royaltyfreesubscription, creditpack, sandbox.
uri string POST this URI to download the asset.
agreement_name string Specifies the customer-defined name of the Premium Access agreement

max_dimensions

height integer Specifies the height in pixels.
width integer Specifies the width in pixels.

referral_destination

site_name string Specifies the asset domain name.
uri string GET this URI to retrieve appropriate referral destination data.

Response Status Codes

200 OK
400 InvalidParameterValue
400 InvalidPage
400 InvalidPageSize
400 UnknownProviderUri
400 IncorrectlyFormedUri
400 MalformedRequest
400 InvalidColor
400 MinimumQualityRankOutOfRange
401 AuthorizationTokenRequired
401 Unauthorized
403 UnauthorizedDisplaySize
403 NoAccessToProductType

Some response items contain hyperlinks which you can use to take you directly to the next steps in your workflow, when appropriate. The following URIs are provided in the response for this request.

display_size.uri string GET this URI to retrieve the display size image.
keywords.entity_uris array Lists the URIs where detailed information can be found for a specific person.
download.uri string POST this URI to download the asset.
referral_destination.uri string GET this URI to retrieve appropriate referral destination data.
editorial_image_search_item.uri_oembed string GET this URI to retrieve oEmbed data for the image, if embeddable.