Release Notes

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