Release Notes

2019-09-24 NEW: download_product search filter and metadata field

Customers with multiple license agreements (product_types) often find it difficult to know which agreement will be used if they go to download an asset that has multiple product_type values. To aleviate this confusion, we've released a new search filter called download_product. This filter is used to narrow your search results to just the assets that can be downloaded from a specific product. Here's an example request that might thelp to illustrate this concept...

Say you have both a Premium Access product and an Editorial Subscription product, and you want to find images that will download only against the Editorial Subscription. You would use a request like this:

https://api.gettyimages.com/v3/search/images/editorial?download_product=editorialsubscription&fields=download_product,product_types&phrase=seattle

We have included both the download_product response field, so we can confirm that we really do get only Editorial Subscription images, and the product_types response field, so you can see what we mean by an image having multiple products. While an image or video may have multiple products associated to it, it will only ever download from one product. Here's a snippet of the response:

  "result_count": 166619,
  "images": [
    {
      "id": "1176628458",
      "download_product": "editorialsubscription",
      "product_types": [
        "premiumaccess",
        "editorialsubscription"
      ]
    },
    {
      "id": "1176628366",
      "download_product": "editorialsubscription",
      "product_types": [
        "premiumaccess",
        "editorialsubscription"
      ]
    },
    {
      "id": "1176628362",
      "download_product": "editorialsubscription",
      "product_types": [
        "premiumaccess",
        "editorialsubscription"
      ]
    }

This search filter and response filed are available on the following endpoints:

  • GET /v3/search/images
  • GET /v3/search/images/creative
  • GET /v3/search/images/editorial
  • GET /v3/search/videos
  • GET /v3/search/videos/creative
  • GET /v3/search/videos/editorial

2019-07-30 NEW: Clip length video search filters

We have added two new filters to all video search endpoints - min_clip_length and max_clip_length - letting you retrieve videos with a minimum and/or maximum clip length. These are available on the following endpoints:

  • GET /v3/search/videos
  • GET /v3/search/videos/creative
  • GET /v3/search/videos/editorial

You can use one or both filters in a request, specifying the desired values in seconds. In the following example that shows both filters in use, I have added the clip_length field so I can confirm that the results match my request.

https://api.gettyimages.com/v3/search/videos?fields=clip_length&min_clip_length=30&max_clip_length=60&phrase=pizza

Snipped response:

  "result_count": 978,
  "videos": [
    {
      "id": "1012522584",
      "clip_length": "00:00:55:14"
    },
    {
      "id": "933320670",
      "clip_length": "00:00:31:08"
    },
    {
      "id": "606045006",
      "clip_length": "00:00:30:16"
    }

2019-06-11 Affiliate Partner Search API Endpoints

We have two new search API endpoints that are specific to the needs of our Affiliate Partners:

  • GET /v3/affiliates/search/images
  • GET /v3/affiliates/search/videos

These endpoints are optimized for speed and ease of use, providing you with just right amount of metadata needed to add image and video search results to your site. Unlike the JavaScript widget, you'll need to add your Affiliate ID to the destination URL per the instructions from Impact Radius, our Affiliate management partner.

You can read the full documentation in the AffiliateSearch section of our Open API Documentation (Swagger).

Interested in becoming an Affiliate Partner? Visit our Affiliate hub.

2019-06-04 - NEW: Lightweight HD video files

We have a new, lightweight HD, .mp4 video file size available for all new video assets in our catlog. We are working on creating this file for all existing video assets.

To filter your search to videos that have this as an available file, simply set the format_available filter to "hd_web". It is helpful to also include "download_sizes" in your requested fields. Like this:

https://api.gettyimages.com/v3/search/videos?format_available=hd_web&fields=download_sizes&phrase=coffee

Here's a (snipped) response example. The new file has a format_name value of "HD Web".

  "result_count": 30857,
  "videos": [
    {
      "id": "949190044",
      "download_sizes": [
        {
          "bit_depth": "8-bit",
          "compression": "H.264",
          "content_type": "video/quicktime",
          "description": "HD Web 1280x720 @ 25p H.264",
          "format": "HD_WEB",
          "frame_rate": 25,
          "frame_size": "1280x720",
          "height": 720,
          "interlaced": false,
          "name": "hd15",
          "width": 1280
        },
        {
          "bit_depth": "8-bit",
          "compression": "Photo-JPEG",
          "content_type": "video/quicktime",
          "description": "HD 1920x1080 @ 25p Photo-JPEG",
          "format": "HD",
          "frame_rate": 25,
          "frame_size": "1920x1080",
          "height": 1080,
          "interlaced": false,
          "name": "hd1",
          "width": 1920
        },
        {
          "bit_depth": "8-bit",
          "compression": "H.264",
          "content_type": "video/mp4",
          "description": "Web 640x360 @ 25 fps H.264",
          "format": "Web",
          "frame_rate": 25,
          "frame_size": "640x360",
          "height": 360,
          "interlaced": false,
          "name": "lwf",
          "width": 640
        },
        {
          "bit_depth": "8-bit",
          "compression": "Photo-JPEG",
          "content_type": "video/quicktime",
          "description": "4K 3840x2160 @ 25p Photo-JPEG",
          "format": "4K",
          "frame_rate": 25,
          "frame_size": "3840x2160",
          "height": 2160,
          "interlaced": false,
          "name": "4k1",
          "width": 3840
        },
        {
          "bit_depth": "8-bit",
          "compression": "H.264",
          "content_type": "video/quicktime",
          "description": "HD 1920x1080 @ 25p H.264",
          "format": "HD",
          "frame_rate": 25,
          "frame_size": "1920x1080",
          "height": 1080,
          "interlaced": false,
          "name": "hd16",
          "width": 1920
        }
      ]
    },

2019-05-07 - NEW: Relaxed rules for local hostname redirect URIs

To make it easier to work with the Getty Images API, authentication workflows requiring a redirect URI (Implicit Grant or Authorization Code) now have more relaxed rules around URIs with a local hostname. First, we will no longer require HTTPS for the URI. Additionally, we won't require local URIs to be whitelisted with us. So, for example, you'd be able to use these redirect URIs without needing to pre-register them with us:

These relaxed rules should help both during development as well for native applications whose redirect URIs do not need to leave the device (e.g. mobile apps).

Lastly, we still require HTTPS for all URIs that are not on the above list.

2019-05-07 - NEW: Metadata fields in GET /v3/downloads response

We've added two new fields to the GET /v3/downloads response:

product_id - This field tells you the ID for the product that was used to download an asset. This field will be particulary useful for clients who have multiple Premium Access products. Each product will have it's own unique ID.

download_source - This field tells you the name (values are gettyimages.com, istockphotos.com or api) of the site that was used to download an asset.

Both fields are available today. Try them out in Swagger!

2019-05-03 - NEW: Swagger update

We've upgraded to the latest version of Swagger - https://api.gettyimages.com/swagger/index.html. Reminder - we use Swagger for both our API documentation and as the tool you can use to quickly test our API.

2018-01-02 - NEW: Random sort order

We have implemented a "random" sort order on the following endpoints:

  • /v3/search/images
  • /v3/search/images/editorial
  • /v3/search/images/creative
  • /v3/search/videos
  • /v3/search/videos/creative
  • /v3/search/videos/editorial

This sort order is useful for when you want your users to see different images appear in the top of their search results (so they don't all pick the same pizza photo!). While the top results will be random, they will still be relvant.

Try it out in Swagger today! https://api.gettyimages.com/swagger/ui/index#!/Search

2018-12-13 - NEW: Search Facets

We have added faceting to image and video search results. Facets provide you with a way of refining your original search. The types of facets are:

Artists - this represents the artists for the images or videos in your search results. Use one of these names in the "artists" parameter, along with your original search, to refine your results to just assets from a specific artist.

Events - this facet represents the events at which images (or video) in your search results were shot. Use the id for a specific event in the event_ids parameter in an Editorial search request to find all images from that event.

Locations - this facet represents the locations for images or videos in your search results. Use the name of one of these locations in the phrase parameter, along with your original phrase value, to refine your results to images from that specific location. Alternatively, you can use the "id" data point in the keyword_ids search parameter.

Specific People - this facet represents the names of specific people in the images or videos in your search results. Use the name of one of these people in the phrase parameter, along with your original phrase value, to refine your results to images of that person. Alternatively, you can use the "id" data point in the keyword_ids search parameter.

There are three parameters used when requesting facets:

  • facet_fields is used to specify which facets are to be returned in the response.
  • include_facets must be set to "true" for facets to be returned in the response.
  • The facet_max_count parameter is used to specify the maximum number of facets to be returned for each type. If not specified, the default value of 300 will be used.

These endpoints provide you with facets for artists and locations:

  • /v3/search/images/creative
  • /v3/search/videos/creative

And these endpoints provide you with facets for artists, events, locations and specific people:

  • /v3/search/images/editorial
  • /v3/search/videos/editorial

Lastly, facets will come back translated if you use the Accept-Language header.

Try it out in Swagger today! https://api.gettyimages.com/swagger/ui/index#!/Search

2018-12-12 - NEW: Support for Authorization Code Grant

We now support the Authorization Code grant flow. This flow is very similar to Implicit Grant, and provides our partners with another way to allow Getty Images and/or iStock customers to securely provide their username and password so that they can access content from their license agreement directly in the partner's application.

Technical documentation: https://developers.gettyimages.com/api/oauth2.html

We have added the download_sizes field as an optional field for all search requests. This provides you with the list of available files for any given image or video. Please note that including this field in your request may lead to longer than normal response times as it's an expensive piece of data to generate. We are looking to optimize this in the future.

This field is available in the following endpoints:

  • GET /v3/search/images
  • GET /v3/search/images/creative
  • GET /v3/search/images/creative/by-image
  • GET /v3/search/images/editorial
  • GET /v3/search/videos
  • GET /v3/search/videos/creative
  • GET /v3/search/videos/editorial

Example request: https://api.gettyimages.com/v3/search/images/creative?fields=download_sizes&phrase=chocolate

Example response (snippet):

{
      "id": "951948686",
      "download_sizes": [
        {
          "bytes": 58085,
          "height": 359,
          "media_type": "image/jpeg",
          "name": "x_small",
          "width": 479
        },
        {
          "bytes": 6667900,
          "height": 3750,
          "media_type": "image/jpeg",
          "name": "large",
          "width": 5000
        },
        {
          "bytes": 675488,
          "height": 1502,
          "media_type": "image/jpeg",
          "name": "medium",
          "width": 2003
        },
        {
          "bytes": 266349,
          "height": 889,
          "media_type": "image/jpeg",
          "name": null,
          "width": 1185
        },
        {
          "bytes": 116286,
          "height": 514,
          "media_type": "image/jpeg",
          "name": "small",
          "width": 685
        },
        {
          "bytes": 2799323,
          "height": 2735,
          "media_type": "image/jpeg",
          "name": null,
          "width": 3647
        }

2018-10-24 - NEW: extended licenses for iStock downloads

We have added the ability to purchase one or more extended licenses for iStock images and videos using your iStock credits. This is done through a new endpoint: /v3/asset-licensing/{assetId}. Here's a link to the Open API technical documentation: https://api.gettyimages.com/swagger/ui/index#!/AssetLicensing/AssetLicensing_AcquireAssetLicenseWithCredits

You must first download (/v3/downloads/images/{id} or /v3/downloads/videos/{id}) before you can add an extended license.

This functionality is only available to iStock API keys. You must authenticate with a username that has access to iStock credits.

When you download a file from iStock using credits, you're buying a standard license that lets you use the file for any personal, business or commercial purposes that aren't otherwise restricted by the license. That means you can use our content in advertising, marketing, apps, websites, social media, TV and film, presentations, newspapers, magazines and books, and product packaging, among hundreds of other uses. Adding an extended license lets you use our content in even more ways. The extended license options are:

  • Multiseat - If multiple members of your team need to be able to access your downloaded file, this is the option for you.
  • Unlimited - allows for unlimited reproduction/print runs using the image.
  • Resale - allows use on items for resale: physical products, electronic (websites, design templates, e-greeting cards, etc.) templates.
  • Indemnification - Extended Legal Guarantee covers up to $250,000.

More information about iStock licenses can be found on our site: https://www.istockphoto.com/help/licenses

2018-08-30 - Updates to the site

We have transitioned our API management provider from Mashery to AWS. This change allows us to more quickly update our APIs and takes advantage of the scale of service that comes from with working with AWS. As such, we've made some updates to this site, removing certain sections that were operated by Mashery.

  • Forums - we now have a Status page where we'll post updates during service interruptions. And this Release Notes page will be kept updated with notes on all the cool new functionality we're making availabile.
  • Sign in and Account pages - if you need to retrieve your keys/secrets, please email us at apisupport@gettyimages.com.
  • Contact - all Contact links now point to the Contact page on gettyimages.com.

We've also cleaned up the Docs section, removing several outdated pages. The API Documentation link now points to our Open API (Swagger) page. This is a more useful tool than the previous documentation - it provides the same info and has the added benefit of letting you actually try the API directly in the documentation.

As always, let us know if you have any questions.

2018-08-08 - NEW: istock_collection metadata field

We've added a new metadata field called "istock_collection" to the following endpoints. This field, with values of "essentials" or "signature", will tell you which iStock collection an iStock image is from. Customers with access to the iStock collection (collection code SKP) via their Getty API key (as opposed to an iStock API key) may find this useful as a way of further categorizing iStock images beyond their Getty collection.

  • GET /v3/search/images/creative
  • GET /v3/search/images/creative/by-image
  • GET /v3/search/videos/creative
  • GET /v3/images
  • GET /v3/images/{id}
  • GET /v3/images/{id}/similar
  • GET /v3/videos
  • GET /v3/videos/{id}
  • GET /v3/videos/{id}/similar

2018-07-15 - NEW: exclude vectors from image search results

A common feature request from many partners is to be able to filter an image search so that vector art is excluded from image search results. Imagine you're a business that prints photos for large scale wall installations. The last thing you want is for goofy little icon sets to show up in your customer's searches.

To accomplish this, we've added two things: a value of "vector" to the existing graphical_styles parameter and a new parameter called graphical_styles_filter_type with values of "include" and "exclude". Here's how you would exclude vector art from your search request:

https://api.gettyimages.com/v3/search/images/creative?graphical_styles=vector&graphical_styles_filter_type=exclude&phrase=donuts

This functionality is available in the following endpoints:

  • GET /v3/search/images
  • GET /v3/search/images/creative
  • GET /v3/search/images/editorial

Setting the graphical_styles_filter_type to "include" is the same as not using the filter.

2018-03-30 - New functionality: download with iStock Team Credits

This week, we released an update that lets iStock users download images using their iStock Team Credits.

First, the /products response now provides you with the number of team credits held by the authenticated iStock user via the "team_credits" field. Here's an example. Note that "credits_remaining" indicates the number of personal credits held by the user.

{
  "products": [
    {
      "application_website": "iStockPhoto",
      "credits_remaining": 62,
      "download_limit": null,
      "download_limit_duration": null,
      "download_limit_reset_utc_date": null,
      "downloads_remaining": null,
      "expiration_utc_date": null,
      "id": 0,
      "name": null,
      "status": "active",
      "type": "creditpack",
      "agreement_name": null,
      "imagepack_resolution": null,
      "team_credits": 4
    }
  ]
}

Second, the /downloads/images/{id} and /downloads/videos/{id} requests now have a "use_team_credits" parameter that, when set to "true", will use team credits to download the specified image. Setting the value to "false" or excluding the parameter entirely will download the image with the user's personal credits. Example request:

https://api.gettyimages.com/v3/downloads/images/535761281?auto_download=false&product_type=credit_pack&use_team_credits=false

2018-02-19 - New functionality: Search By Image

You may have noticed that our sites (gettyimages.com and istockphoto.com) have functionality that allows you search for images by uploading your own photo to receive results of similar content from our catalog of creative images.

Well... I have good news for all you Getty Images API fanatics! This same functionality is now available in our API! Load an image to our AWS S3 bucket, receive a URL, then use that URL as the search parameter in your request to /v3/search/images/creative-by-image.

The uses for this functionality are endless... let your users take a photo and then find similar images from the pool of creative content in your license agreement. Find a photo of some tasty donuts online, see what we have in our catalog that's equally delicious. Tired of using the same stock photo of business people shaking hands? See what other agreeable professionals are lurking in our library! Insider tip: there's a lot and they're happily takin' care of Business.

Try it on Swagger