Edit

Image Search API v7 query parameters

  • Article

The following are the query parameters that a request may include. The Required column indicates whether you must specify the parameter. You must URL encode the query parameter values.

For information about query parameters used to filter the images that Bing returns, see Filter query parameters.

These parameters do not affect the list of images that Bing Web Search API returns.

Name Value Type Required
cc A 2-character country code of the country where the results come from. For a list of possible values, see Market codes.

If you set this parameter, you must also specify the Accept-Language header. Bing uses the first supported language it finds in the specified languages and combines it with the country code to determine the market to return results for. If the languages list does not include a supported language, Bing finds the closest language and market that supports the request. Or, Bing may use an aggregated or default market for the results.

To know which market Bing used, get the BingAPIs-Market header in the response.

Use this query parameter and the Accept-Language header only if you specify multiple languages. Otherwise, you should use the mkt and setLang query parameters.

This parameter and the mkt query parameter are mutually exclusive — do not specify both.		 String No
count The number of images to return in the response. The actual number delivered may be less than requested. The default is 35 and the maximum is 150.

You may use this parameter along with the offset parameter to page results. For example, if your user interface presents 20 images per page, set count to 20 and offset to 0 to get the first page of results. For each subsequent page, increment offset by 20 (for example, 0, 20, 40).

Use this parameter only when calling the /images/search endpoint. Do not specify this parameter when calling the /images/trending endpoint.		 UnsignedShort No
id An ID that uniquely identifies an image. The Image object's imageId field contains the ID that you set this parameter to.

For the /images/search endpoint, you use this parameter to ensure that the specified image is the first image in the list of images that Bing returns.		 String No
mkt The market where the results come from. Typically, mkt is the country where the user is making the request from. However, it could be a different country if the user is not located in a country where Bing delivers results. The market must be in the form <language>-<country/region>. For example, en-US. The string is case insensitive. For a list of possible market values, see Market codes.

NOTE: If known, you are encouraged to always specify the market. Specifying the market helps Bing route the request and return an appropriate and optimal response. If you specify a market that is not listed in Market codes, Bing uses a best fit market code based on an internal mapping that is subject to change.

To know which market Bing used, get the BingAPIs-Market header in the response.

This parameter and the cc query parameter are mutually exclusive — do not specify both.		 String No
offset The zero-based offset that indicates the number of search results to skip before returning results. The default is 0. The offset should be less than (totalEstimatedMatches - count).

Use this parameter along with the count parameter to page results. For example, if your user interface displays 10 search results per page, set count to 10 and offset to 0 to get the first page of results. For each subsequent page, increment offset by 10 (for example, 0, 10, 20). It is possible for multiple pages to include some overlap in results. To prevent duplicates, see nextOffset.

Use this parameter only when calling the /images/search endpoint. Do not specify this parameter when calling the /images/trending endpoint.		 Unsigned Short No
q The user's search query term. The term may not be empty.

The term may contain Bing Advanced Operators. For example, to limit results to a specific domain, use the site: operator (q=fishing+site:fishing.contoso.com). Note that the results may contain results from other sites depending on the number of relevant results found on the specified site.

Use this parameter only when calling the /images/search endpoint. Do not specify this parameter when calling the /images/trending endpoint.		 String Yes
safeSearch Used to filter images for adult content. The following are the possible filter values:
  • Off — May return images with adult content. If the request is through the Image Search API, the response includes thumbnail images that are clear (non-fuzzy). However, if the request is through the Web Search API, the response includes thumbnail images that are pixelated (fuzzy).

  • Moderate — If the request is through the Image Search API, the response doesn't include images with adult content. If the request is through the Web Search API, the response may include images with adult content (the thumbnail images are pixelated (fuzzy)).

  • Strict — Do not return images with adult content.
The default is Moderate.

NOTE: If the request comes from a market that Bing's adult policy requires that safeSearch be set to Strict, Bing ignores the safeSearch value and uses Strict.

NOTE: If you use the site: query operator, there is a chance that the response may contain adult content regardless of what the safeSearch query parameter is set to. Use site: only if you are aware of the content on the site and your scenario supports the possibility of adult content.		 String No
setLang The language to use for user interface strings. You may specify the language using either a 2-letter or 4-letter code. Using 4-letter codes is preferred.

For a list of supported language codes, see Bing supported languages.

Bing loads the localized strings if setlang contains a valid 2-letter neutral culture code (fr) or a valid 4-letter specific culture code (fr-ca). For example, for fr-ca, Bing loads the fr neutral culture code strings.

If setlang is not valid (for example, zh) or Bing doesn’t support the language (for example, af, af-na), Bing defaults to en (English).

To specify the 2-letter code, set this parameter to an ISO 639-1 language code.

To specify the 4-letter code, use the form <language>-<country/region> where <language> is an ISO 639-1 language code (neutral culture) and <country/region> is an ISO 3166 country/region (specific culture) code. For example, use en-US for United States English.

Although optional, you should always specify the language. Typically, you set setLang to the same language specified by mkt unless the user wants the user interface strings displayed in a different language.

This parameter and the Accept-Language header are mutually exclusive — do not specify both.

A user interface string is a string that's used as a label in a user interface. There are few user interface strings in the JSON response objects. Also, any links to Bing.com properties in the response objects use the specified language.		 String No

Filter query parameters

Use the following optional query parameters with Image Search API to filter the images that Bing returns. You must URL-encode the query parameters.

These do not apply to Trending Images API or Image Insights API. Also, these parameters do not affect the list of images that Bing Web Search API returns.

Name Value Type
aspect Filter images by the following aspect ratios:
  • Square — Return images with standard aspect ratio.
  • Wide — Return images with wide screen aspect ratio.
  • Tall — Return images with tall aspect ratio.
  • All — Do not filter by aspect. Specifying this value is the same as not specifying the aspect parameter.
 String
color Filter images by the following color options:
  • ColorOnly — Return color images.
  • Monochrome — Return black and white images.
Or, Filter images by one of the following dominant colors:
  • Black
  • Blue
  • Brown
  • Gray
  • Green
  • Orange
  • Pink
  • Purple
  • Red
  • Teal
  • White
  • Yellow
 String
freshness Filter images by the following discovery options:
  • Day — Return images discovered by Bing within the last 24 hours.
  • Week — Return images discovered by Bing within the last 7 days.
  • Month — Return images discovered by Bing within the last 30 days.
 String
height Filter images that have the specified height, in pixels.

You may use this filter with the size filter to return; for example, small images that have a height of 150 pixels.		 UnsignedShort
imageContent Filter images by the following content types:
  • Face — Return images that show only a person's face.
  • Portrait — Return images that show only a person's head and shoulders.
 String
imageType Filter images by the following image types:
  • AnimatedGif — Return animated gif images.
  • AnimatedGifHttps — Return animated gif images that are from an HTTPS address.
  • Clipart — Return only clip art images.
  • Line — Return only line drawings.
  • Photo — Return only photographs (excluding line drawings, animated gifs, and clip art).
  • Shopping — Return only images that contain items where Bing knows of a merchant that is selling the items. This option is valid in the en-US market only.
  • Transparent — Return only images with a transparent background.
 String
license Filter images by the following license types:
  • Any — Return images that are under any license type. The response doesn't include images that do not specify a license or the license is unknown.
  • Public — Return images where the creator has waived their exclusive rights, to the fullest extent allowed by law.
  • Share — Return images that may be shared with others. Changing or editing the image might not be allowed. Also, modifying, sharing, and using the image for commercial purposes might not be allowed. Typically, this option returns the most images.
  • ShareCommercially — Return images that may be shared with others for personal or commercial purposes. Changing or editing the image might not be allowed.
  • Modify — Return images that may be modified, shared, and used. Changing or editing the image might not be allowed. Modifying, sharing, and using the image for commercial purposes might not be allowed.
  • ModifyCommercially — Return images that may be modified, shared, and used for personal or commercial purposes. Typically, this option returns the fewest images.
  • All — Do not filter by license type. Specifying this value is the same as not specifying the license parameter.
For more information about these license types, see Filter Images By License Type.		 String
maxFileSize Filter images that are less than or equal to the specified file size.

The maximum file size that you may specify is 520,192 bytes. If you specify a larger value, the API uses 520,192. It is possible that the response may include images that are slightly larger than the specified maximum.

You may specify this filter and minFileSize to filter images within a range of file sizes.		 Integer
maxHeight Filter images that have a height that is less than or equal to the specified height. Specify the height in pixels.

You may specify this filter and minHeight to filter images within a range of heights.

This filter and the height filter are mutually exclusive.		 Integer
maxWidth Filter images that have a width that is less than or equal to the specified width. Specify the width in pixels.

You may specify this filter and maxWidth to filter images within a range of widths.

This filter and the width filter are mutually exclusive.		 Integer
minFileSize Filter images that are greater than or equal to the specified file size.

The maximum file size that you may specify is 520,192 bytes. If you specify a larger value, the API uses 520,192. It is possible that the response may include images that are slightly smaller than the specified minimum.

You may specify this filter and maxFileSize to filter images within a range of file sizes.		 Integer
minHeight Filter images that have a height that is greater than or equal to the specified height. Specify the height in pixels.

You may specify this filter and maxHeight to filter images within a range of heights.

This filter and the height filter are mutually exclusive.		 Integer
minWidth Filter images that have a width that is greater than or equal to the specified width. Specify the width in pixels.

You may specify this filter and maxWidth to filter images within a range of widths.

This filter and the width filter are mutually exclusive.		 Integer
size Filter images by the following sizes:
  • Small — Return images that are less than 200x200 pixels.
  • Medium — Return images that have either the width or height between 200 and 500 pixels.
  • Large — Return images that have either the width or height at 500 pixels or larger.
  • Wallpaper — Return wallpaper images.
  • All — Do not filter by size. Specifying this value is the same as not specifying the size parameter.
You may use this parameter along with the height or width parameters. For example, you may use height and size to request small images that are 150 pixels tall.		 String
width Filter images that have the specified width, in pixels.

You may use this filter with the size filter to return small images that have a width of 150 pixels.		 UnsignedShort