Searching

To search for media with the Shutterstock API, you need:

Some API subscriptions return a limited set of results. See Subscriptions in the API reference.

Keyword searches

To search for media with a keyword, pass the search keywords to the appropriate endpoint:

The search keywords must be URL encoded and in the query query parameter. The API searches for the keywords in all textual fields, including but not limited to the description, keywords, and title. For examples of search results, see Results.

Searches do not support wildcards such as *.

Here are some examples of simple image, video, and audio search requests:

Simple image keyword search

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=kites"

Simple video keyword search

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/videos/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=hot air balloon"

Simple audio keyword search

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/audio/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=bluegrass"

Conditional searches

Searches for images and video can use AND, OR, and NOT conditions, but searches for audio do not support these keywords.

To use AND, OR, or NOT in searches, you include these operators in the query query parameter. The operators must be in upper case and they must be in English, regardless of the language the keywords are in.

You can group conditional search terms with parentheses. For example, to search for images with either dogs or cats, but not both, use (dog NOT cat) OR (cat NOT dog).

Here are some examples of searching with conditions:

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=dog AND cat"

curl -X GET "https://api.shutterstock.com/v2/videos/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=mountain NOT camping"

Bulk searches

You can run up to 5 image searches in a single request with the POST /v2/bulk_search/images endpoint. The API returns a maximum of 20 results for each search. To use this endpoint, pass multiple searches in the an array in the request body. Each search the array has the same parameters as an individual image search.

You can also pass query parameters in the request. These parameters become defaults for each search, but the parameters in the individual searches override them.

Here is an example of sending 2 searches in a single request:

cURLCLIPHPJavaScript


DATA='[
  {
    "query": "cat",
    "license": ["editorial"],
    "sort": "popular"
  },
  {
    "query": "dog",
    "orientation": "horizontal"
  }
]'

curl -X POST "https://api.shutterstock.com/v2/bulk_search/images" \
  -H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$DATA"

Paging results

Each search endpoint (as well as many other endpoints) can split the response into multiple pages with the page and per_page parameters. For example, if a search result has 20 pieces of media, you can retrieve items 6-10 by using page=2 and per_page=5 in the request. You can show up to 500 results per page for most requests. Some endpoints have different limits; see the description of the per_page parameter for the individual endpoints.

For example:

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=giraffes" \
--data-urlencode "page=2" \
--data-urlencode "per_page=5"

Sorting results

The sort parameter controls how results are ordered. By default, image and video searches return the most popular media first. Audio searches without the sort parameter return tracks based on the popularity of that track in the location of the request. Use the sort_order parameter to specify if the results are in ascending ("asc") or descending ("desc," the default) order.

The image and video search endpoints can order results in the following ways:

The audio search endpoint can sort results in the following ways:

Here are some examples:

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/videos/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=boats" \
--data-urlencode "sort=popular"


curl -X GET "https://api.shutterstock.com/v2/audio/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "instruments=Piano" \
--data-urlencode "duration_from=300" \
--data-urlencode "sort=bpm" \
--data-urlencode "sort_order=desc"

Result detail

The view parameter controls how much detail is shown in the response. By default (view=minimal), the response includes a moderate amount of detail about each search result, but if you set the view parameter to full, the response includes complete information about each result. For example, full image results include the full list of keywords (human-curated descriptors) and categories (Shutterstock-assigned genres) that apply to each image.

For examples of the results, see Results.

Localizing searches

You can localize searches and their results by setting the language or region for the search.

Search languages

You can provide search keywords in the following languages by specifying the two-character language code in the language parameter.

For example:

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=chien" \
--data-urlencode "language=fr"

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=perro" \
--data-urlencode "language=es" \
--data-urlencode "region=es"

Geo-ranking results

You can customize image search results based on location with the region parameter. This parameter accepts any ISO 3166-1 alpha-2 country code. You can also specify an IP address in this parameter and the API infers a country code from it.

Based on the location, the API changes rankings to provide more appropriate results. For example, searches for the term "football" return images of different sports depending on the location. Search results are raised or lowered in relevance based on how well they relate to the location.

Search parameters

Aside from the keywords in the query field, search requests can include many other search fields. The following sections show common search parameters for image, video, and audio searches.

Some parameters in the search endpoints (and other endpoints) can accept more than one value. In this case, you can specify the same parameter more than one time, as in the following example. For more information about using parameters multiple times, see Passing multiple values.

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=dog" \
--data-urlencode "image_type=illustration" \
--data-urlencode "image_type=vector" \
--data-urlencode "license=enhanced"

For a complete list of these search parameters, see the API documentation for the search endpoints:

Here are examples of searching with multiple fields:

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=earthquake" \
--data-urlencode "sort=newest" \
--data-urlencode "image_type=photo"


curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "sort=popular" \
--data-urlencode "category=Holidays"

Here's an example of providing multiple values for the same field. Note that only certain fields can accept multiple values:

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/audio/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "instruments=Trumpet" \
--data-urlencode "instruments=Drums"

Common image search parameters

To search for images of people, use one or more of these parameters:

To search for images by size (in pixels), use these parameters:

For a complete list of image search parameters, see Search for images.

For example:

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=hiking" \
--data-urlencode "image_type=photo" \
--data-urlencode "orientation=vertical" \
--data-urlencode "people_number=3"

curl -X GET "https://api.shutterstock.com/v2/images/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=ocean" \
--data-urlencode "color=FFFF00" \
--data-urlencode "width_from=4096"

Common video search parameters

To specify the duration of the video, use these parameters:

To search for videos by frames per second (FPS), use these parameters:

To search for videos with people, use one or more of these parameters:

For a complete list of video search parameters, see Search for videos.

For example:

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/videos/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "query=cycling" \
--data-urlencode "resolution=4k" \
--data-urlencode "people_number=1"

Common audio search parameters

To search for tracks by beats per minute (BPM), use these parameters:

To specify the duration of the track, use these parameters:

For a complete list of audio search parameters, see Search for tracks.

For example:

cURLCLIPHPJavaScript


curl -X GET "https://api.shutterstock.com/v2/audio/search" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "genre=Blues"

Aspect ratios

To search for images by aspect ratio, specify the ratio as a positive decimal of the width divided by the height. For example, to search for images with a 4:3 aspect ratio, set the aspect_ratio parameter to 1.3333. The search endpoints calculate aspect ratio to four decimal places and return only images that exactly match this decimal aspect ratio.

Images with a higher aspect ratio are wider and images with a lower aspect ratio are narrower. Images with a landscape orientation have aspect ratios greater than 1 and images with a portrait orientation have aspect ratios less than or equal to 1, such as 0.75 for an image with a 3:4 aspect ratio.

Images do not always exactly match a standard ratio. Because of a difference of a few pixels, images that have a ratio of approximately 3:2 can have decimal aspect ratios of 1.4998, 1.5, or 1.5001. To search for images that have an aspect ratio of approximately 1.5, set the aspect_ratio_max parameter to 1.5005 and the aspect_ratio_min parameter to 1.4995.

To search for videos by aspect ratio, set the aspect_ratio parameter to a preset value such as 4_3 or 16_9. The search returns videos that have approximately that aspect ratio.

Safe search

By default, the API hides media that may not be appropriate for all audiences. The API provides two parameters that you can use to enable this content in the responses of some endpoints:

To disable either type of restriction, set one or both of these parameters to false. The image and video search endpoints support both parameters. The recommended images and similar images and videos endpoints support only the safe parameter.

Computer vision search

Computer vision provides images and videos that are similar to a reference image that you supply.

To upload an image for reverse image and video search or keyword suggestions with computer vision, use the POST /v2/cv/images endpoint. Then, use the upload ID that this endpoint returns to get similar images or videos from the GET /v2/cv/similar/images or GET /v2/cv/similar/videos endpoints. The API returns up to 200 images or videos that appear visually similar to your image.

Images must be in JPG or PNG format. They can be no larger than 25mb and can be no larger than 10,000 pixels in width or height. Some operating systems have a limit on the size of the parameters that you can send in a command-line request, such as with the curl program. If you see an error such as "Argument list too long," send a smaller image or make the request with a programming language such as PHP or Node.JS.

To use the computer vision endpoints, your application must be enabled for computer vision. Please contact us for access.

cURLCLIPHPJavaScript


RESPONSE=$(curl -X POST 'https://api.shutterstock.com/v2/cv/images' \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-H 'Content-Type: application/json' \
-d "{\"base64_image\":\"`base64myImage.jpg`\"}")

echo "The next step requires the jq program."

UPLOAD_ID=$(jq -r .upload_id <<< $RESPONSE)

curl -X GET https://api.shutterstock.com/v2/cv/similar/images \
-H "Accept: application/json" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "asset_id=$UPLOAD_ID"

Computer vision keyword suggestions

Computer vision can also provide suggested keywords for an image.

To get suggested keywords for an image, upload it to the POST /v2/cv/images endpoint as with reverse image search. Then, use the upload ID that this endpoint returns to get suggested keywords from the GET /v2/cv/keywords endpoint. You can also use the ID of an existing image in the Shutterstock collection. In this case, the suggested keywords may not be the same as the keywords in the image metadata.

cURLCLIPHPJavaScript


RESPONSE=$(curl -X POST 'https://api.shutterstock.com/v2/cv/images' \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-H 'Content-Type: application/json' \
-d "{\"base64_image\":\"`base64myImage.jpg`\"}")

echo "The next step requires the jq program."

UPLOAD_ID=$(jq -r .upload_id <<< $RESPONSE)

curl -X GET https://api.shutterstock.com/v2/cv/keywords \
-H "Accept: application/json" \
-H "Authorization: Bearer $SHUTTERSTOCK_API_TOKEN" \
-G \
--data-urlencode "asset_id=$UPLOAD_ID"

Results

The search results start with information about the search and the results, including the search ID, the total number of results, and the paging information. Not all results are returned at once; to page through the results, see Paging results.

Each search result includes one or more preview links that you can use to preview the media before licensing and downloading the full version.

You can sort the search results by factors like the popularity of the media and how recently it was added. For more information about sorting, see Sorting results.

By default, the results show basic information about each search result, including its description, its contributor, information about its dimensions, aspect ratio, or length, and links to previews. You can get more details about each result by including the view=full parameter with the search. For more information, see Result detail.

Here are examples of search results:

Example image search results

Image search responses show information about each image, such as its aspect ratio, its dimensions, the media type (image, in this case, as opposed to video or audio search results), the type of image (such as photo, vector, or illustration), the contributor that provided the image, and a textual description for the image.

{
  "page": 1,
  "per_page": 1,
  "total_count": 6471766,
  "search_id": "BogDL7hW4kdptwSXvWsE3w",
  "data": [
    {
      "id": "755022088",
      "aspect": 1.5,
      "assets": {
        "preview": {
          "height": 300,
          "url": "https://image.shutterstock.com/display_pic_with_logo/2723875/755022088/stock-photo-aerial-view-to-ocean-waves-blue-water-background-755022088.jpg",
          "width": 450
        },
        "small_thumb": {
          "height": 67,
          "url": "https://thumb9.shutterstock.com/thumb_small/2723875/755022088/stock-photo-aerial-view-to-ocean-waves-blue-water-background-755022088.jpg",
          "width": 100
        },
        "large_thumb": {
          "height": 100,
          "url": "https://thumb9.shutterstock.com/thumb_large/2723875/755022088/stock-photo-aerial-view-to-ocean-waves-blue-water-background-755022088.jpg",
          "width": 150
        },
        "huge_thumb": {
          "height": 260,
          "url": "https://image.shutterstock.com/image-photo/aerial-view-ocean-waves-blue-260nw-755022088.jpg",
          "width": 390
        },
        "preview_1000": {
          "url": "https://ak.picdn.net/shutterstock/photos/755022088/watermark_1000/4aa68fbdca3b3c6b9792a555c7b793e9/preview_1000-755022088.jpg",
          "width": 1000,
          "height": 667
        },
        "preview_1500": {
          "url": "https://image.shutterstock.com/z/stock-photo-aerial-view-to-ocean-waves-blue-water-background-755022088.jpg",
          "width": 1500,
          "height": 1000
        }
      },
      "contributor": {
        "id": "2723875"
      },
      "description": "Aerial view to ocean waves. Blue water background",
      "image_type": "photo",
      "media_type": "image"
    }
  ],
  "spellcheck_info": {}
}

Example video search results

Video search responses video search results include the duration of the video in seconds and the aspect ratio expressed both as a ratio and as a decimal.

{
  "page": 1,
  "per_page": 1,
  "total_count": 323254,
  "search_id": "Kz8nE1uZ8f9SVZiC41DbPQ",
  "data": [
    {
      "media_type": "video",
      "id": "32074804",
      "description": "Large container ship at sea - Top down Aerial ",
      "aspect": 1.778,
      "duration": 39,
      "contributor": {
        "id": "474853"
      },
      "aspect_ratio": "16:9",
      "assets": {
        "thumb_webm": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/thumb/stock-footage-large-container-ship-at-sea-top-down-aerial.webm"
        },
        "thumb_mp4": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/thumb/stock-footage-large-container-ship-at-sea-top-down-aerial.mp4"
        },
        "preview_webm": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/preview/stock-footage-large-container-ship-at-sea-top-down-aerial.webm"
        },
        "preview_mp4": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/preview/stock-footage-large-container-ship-at-sea-top-down-aerial.mp4"
        },
        "thumb_jpg": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/thumb/1.jpg"
        },
        "preview_jpg": {
          "url": "https://ak4.picdn.net/shutterstock/videos/32074804/thumb/1.jpg"
        }
      }
    }
  ]
}

Example audio search results

Audio search results include the file size in bytes and the title for the track.

{
  "page": 1,
  "per_page": 1,
  "total_count": 107,
  "search_id": "d375d427-7ba3-4636-b00b-2fb48a0bf41e",
  "data": [
    {
      "id": "394445",
      "description": "Groovy and whimsical, playful marimba and island percussion create an atmosphere of winsome fun.",
      "assets": {
        "clean_audio": {
          "file_size": 29402944
        },
        "preview_mp3": {
          "file_size": 3676706,
          "url": "https://ak.picdn.net/shutterstock/audio/394445/preview/preview.mp3"
        },
        "preview_ogg": {
          "file_size": 3866129,
          "url": "https://ak.picdn.net/shutterstock/audio/394445/preview/preview.ogg"
        },
        "waveform": {
          "file_size": 19060,
          "url": "https://ak.picdn.net/shutterstock/audio/394445/waveform/waveform.png"
        }
      },
      "title": "Calypso Bird",
      "media_type": "audio",
      "contributor": {
        "id": "2847971"
      },
      "published_time": "2015-09-17T11:31:27-04:00",
      "added_date": "2015-09-17"
    }
  ]
}

Previewing media

To preview the media, use the URLs in the assets section of the search response. Each result includes one or more previews. Images include watermarked previews in different sizes, videos include thumbnail images and low-resolution watermarked preview videos, and audio tracks include versions with voice-overs. You can embed these previews on web pages or link to them.

The dimensions for thumbnail and preview images and videos depend on the aspect ratio of the original images and videos.

Image thumbnail and preview dimensions

Image search results and responses to the GET /v2/images/{id} endpoint include thumbnails and previews in multiple sizes. The response includes the dimensions of each image. Which sizes appear in your response depends on the type of your account.

Video thumbnail and preview dimensions

Thumbnails of videos with aspect ratios less than or equal to 16:9 are 180 pixels in height with an appropriate width for the aspect ratio. For example, 16:9 videos (such as 720p, 1080p, and 4K videos) have thumbnails that are 320x180 pixels, and 4:3 videos have thumbnails that are 238x180 pixels. Thumbnails of videos with aspect ratios greater than 16:9 have a height equal to 320 divided by the aspect ratio. For example, 1.9:1 videos have thumbnails that are 320x168. Video thumbnails are watermarked.

Previews of videos with aspect ratios less than or equal to 16:9 are 336 pixels in height with an appropriate width. For example, 16:9 videos have previews that are 596x336. Previews of videos with aspect ratios greater than 16:9 have a height equal to 600 divided by the aspect ratio. For example, 1.9:1 videos have previews that are 600x316. Preview videos are watermarked.

Removing the ID from preview versions of images

Shutterstock preview images and thumbnails, such as the images in the results of requests to GET /v2/images/search, come with image IDs (also known as the "whitestrip") embedded on the images. Depending on the orientation of the image, the whitestrip can be on the side or bottom of an image. This example shows a whitestrip at the bottom of a thumbnail image:

Depending on how you use the previews or thumbnails, you may prefer to hide this image ID whitestrip. The API can not remove the whitestrip itself, but it provides information that you can use to hide it. When the API returns information about preview images or thumbnails, it provides the dimensions of the image without the whitestrip, as in this example:

{
  "page": 1,
  "per_page": 1,
  "total_count": 3207000,
  "search_id": "pH4mTr97r-nHSY6tUrOeVA",
  "data": [
    {
      "id": "228722404",
      "aspect": 1.4997,
      "assets": {
        "preview": {
          "height": 300,
          "url": "https://image.shutterstock.com/display_pic_with_logo/708811/228722404/stock-photo-forest-road-under-sunset-sunbeams-lane-running-through-the-autumn-deciduous-forest-at-dawn-or-228722404.jpg",
          "width": 450
        },
        "small_thumb": {
          "height": 67,
          "url": "https://thumb7.shutterstock.com/thumb_small/708811/228722404/stock-photo-forest-road-under-sunset-sunbeams-lane-running-through-the-autumn-deciduous-forest-at-dawn-or-228722404.jpg",
          "width": 100
        },
        "large_thumb": {
          "height": 100,
          "url": "https://thumb7.shutterstock.com/thumb_large/708811/228722404/stock-photo-forest-road-under-sunset-sunbeams-lane-running-through-the-autumn-deciduous-forest-at-dawn-or-228722404.jpg",
          "width": 150
        },
        "huge_thumb": {
          "height": 260,
          "url": "https://image.shutterstock.com/image-photo/forest-road-under-sunset-sunbeams-260nw-228722404.jpg",
          "width": 390
        },
        "preview_1000": {
          "url": "https://ak.picdn.net/shutterstock/photos/228722404/watermark_1000/007874edefea7d358134ea6c9e29324f/preview_1000-228722404.jpg",
          "width": 1000,
          "height": 667
        },
        "preview_1500": {
          "url": "https://image.shutterstock.com/z/stock-photo-forest-road-under-sunset-sunbeams-lane-running-through-the-autumn-deciduous-forest-at-dawn-or-228722404.jpg",
          "width": 1500,
          "height": 1000
        }
      },
      "contributor": {
        "id": "708811"
      },
      "description": "Forest Road Under Sunset Sunbeams. Lane Running Through The Autumn Deciduous Forest At Dawn Or Sunrise. Toned Instant Photo",
      "image_type": "photo",
      "media_type": "image"
    }
  ]
}

The preview image and thumbnails have a whitestrip on the bottom:

The response from the API says that the preview image has a height of 300 pixels and a width of 450 pixels. These are the dimensions of the image without the whitestrip. Therefore, you can use CSS styles to constrain the image to those dimensions, as in this example:

<div style="height:300px;width:450px;overflow:hidden">
<img src="stock-photo-forest-road-under-sunset-sunbeams-lane-running-through-the-autumn-deciduous-forest-at-dawn-or-228722404.jpg">
</div>

As a result, the page shows the image without the whitestrip:

Considerations for responsive UIs and apps

Removing the whitestrip can be problematic for responsive UIs and apps because the styles may not work the same way after browser actions, user actions, and changes in responsive breakpoints. To account for these changes, you can use the dimensions of the image in various cropping methodologies and add-ons. There are many ways to keep the images at the correct dimensions; which technique you use depends on your platform and language.

Next steps

Now that you have the IDs of pieces of media that you're interested in, you can group them into collections (also known as lightboxes, clipboxes, or soundboxes) on the Shutterstock site then pull it through the API into your application. This way, you can offer this media as a custom collection on your platform.

To license and download media, see Licensing and downloading.

Limitations

By default, searches are limited to 2,000 results. If you receive a message that says "Too Many Results: Please provide more query parameters to narrow your search," suggest to your end users that they add more search terms.

If your application requires more than 2000 search results, please contact us.