Edit

Share via

Custom Web Search API v7 query parameters

  • Article

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

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 search results to return in the response. The default is 10 and the maximum value is 50. The actual number delivered may be less than requested.

Use this parameter along with the offset parameter to page results. For more information, see Paging 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. This parameter affects only webpage results and has no impact on the number of results that Bing returns for other answers in the search results such as images or videos.		 UnsignedShort No
customConfig Unique identifier that identifies your custom search instance. String Yes
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.		 Unsigned Short No
q The user's search query term. The term may not be empty.

NOTE: The query string must not contain Bing Advanced Operators. Including them may adversely affect the custom search experience.		 String Yes
safeSearch Used to filter webpages for adult content. The following are the possible filter values:
  • Off — Returns content with adult text.
  • Moderate — Returns webpages with adult text.
  • Strict — Does not return adult text.
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
textDecorations A Boolean value that determines whether display strings in the results should contain decoration markers such as hit highlighting characters. If true, the strings may include markers. The default is false.

To specify whether to use Unicode characters or HTML tags as the markers, see the textFormat query parameter.

For information about hit highlighting, see Hit highlighting.		 Boolean No
textFormat The type of markers to use for text decorations (see the textDecorations query parameter).

The following are the possible values:
  • Raw — Use Unicode characters to mark content that needs special formatting. The Unicode characters are in the range E000 through E019. For example, Bing uses E000 and E001 to mark the beginning and end of query terms for hit highlighting.

  • HTML — Use HTML tags to mark content that needs special formatting. For example, use <b> tags to highlight query terms in display strings.
The default is Raw.

For a list of markers and information about processing strings with the embedded Unicode characters, see Hit highlighting.

For display strings that contain escapable HTML characters such as <, >, and &, if textFormat is set to HTML, Bing escapes the characters as appropriate (for example, < is escaped to &lt;).		 String No

Image filter query parameters

The following are the optional query parameters that you can use to filter the images that Custom Image Search API returns. You must URL encode the query parameters.

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 are greater than or equal to 200x200 pixels but less than 500x500 pixels.
  • Large — Return images that are 500x500 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

Video filter query parameters

The following are the optional query parameters that you can use to filter the videos that Custom Video Search API returns. You must URL encode the query parameters.

Name Value Type
aspect Filter videos by the following aspect ratios:
  • standard — Return videos with standard aspect radio.
  • widescreen — Returns videos with wide screen aspect radio.
 String
embedded Filter videos that are embeddable. The following are the possible options:
  • player — Returns videos with an embeddable player.
 String
freshness Filter videos by the date and time that Bing discovered the video. The following are the possible filter values:
  • Day — Return videos discovered within the last 24 hours.
  • Week — Return videos discovered within the last 7 days.
  • Month — Return videos discovered within the last 30 days.
 String
pricing Filter videos by the following pricing options:
  • Free — Return videos that are free to view.
  • Paid — Return videos that require a subscription or payment to view.
  • All — Do not filter by pricing. Specifying this value is the same as not specifying the pricing parameter.
 String
resolution Filter videos by the following resolutions:
  • lowerthan_360p — Return videos with lower than 360p resolution.
  • 360p — Return videos with a 360p or higher resolution.
  • 480p — Return videos with a 480p or higher resolution.
  • 720p — Return videos with a 720p or higher resolution.
  • 1080p — Return videos with a 1080p or higher resolution.
  • All — Do not filter by resolution. Specifying this value is the same as not specifying the resolution parameter.
 String
videoLength Filter videos by the following lengths:
  • Short — Return videos that are less than 5 minutes.
  • Medium — Return videos that are between 5 and 20 minutes, inclusive.
  • Long — Return videos that are longer than 20 minutes.
  • All — Do not filter by length. Specifying this value is the same as not specifying the videoLength parameter.
 String