Autosuggest API v7 headers
The following are the headers that a request and response may include.
Note
Remember that the Terms of Use require compliance with all applicable laws, including regarding use of these headers. For example, in certain jurisdictions, such as Europe, there are requirements to obtain user consent before placing certain tracking devices on user devices.
Request headers
Header | Required | Description |
---|---|---|
Accept | No | The default media type is application/json. To specify that the response use JSON-LD, set the Accept header to application/ld+json. |
Accept-Language | No | A comma-delimited list of languages to use for user interface strings. The list is in decreasing order of preference. For more information, including expected format, see RFC2616. This header and the setLang query parameter are mutually exclusive — do not specify both. If you set this header, you must also specify the cc query parameter. To determine the market to return results for, Bing uses the first supported language it finds from the list and combines it with the cc parameter value. If the list does not include a supported language, Bing finds the closest language and market that supports the request or it uses an aggregated or default market for the results. To determine the market that Bing used, see the BingAPIs-Market header.Use this header and the cc query parameter only if you specify multiple languages. Otherwise, use the mkt and setLang query parameters.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. Any links to Bing.com properties in the response objects will apply the specified language. |
Ocp-Apim-Subscription-Key | Yes | The subscription key that you received when you signed up for this service in Azure Portal while creating a Bing resource. |
Pragma | No | By default, Bing returns cached content, if available. To prevent Bing from returning cached content, set the Pragma header to no-cache (for example, Pragma: no-cache). |
User-Agent | No | The user agent originating the request. Bing uses the user agent to provide mobile users with an optimized experience. Although optional, you are encouraged to always specify this header. The user-agent should be the same string that any commonly used browser sends. For information about user agents, see RFC 2616. The following are examples of user-agent strings.
|
X-MSEdge-ClientID | No | This header is used by both requests and responses. Bing uses this header to provide users with consistent behavior across Bing API calls. Bing often flights new features and improvements, and it uses the client ID as a key for assigning traffic on different flights. If you do not use the same client ID for a user across multiple requests, then Bing may assign the user to multiple conflicting flights. Being assigned to multiple conflicting flights can lead to an inconsistent user experience. For example, if the second request has a different flight assignment than the first, the experience may be unexpected. Also, Bing can use the client ID to tailor web results to that client ID’s search history, providing a richer experience for the user. Bing also uses this header to help improve result rankings by analyzing the activity generated by a client ID. The relevance improvements help with better quality of results delivered by Bing APIs and in turn enables higher click-through rates for the API consumer. IMPORTANT: Although optional, you should consider this header required. Persisting the client ID across multiple requests for the same end user and device combination enables: 1) the API consumer to receive a consistent user experience, and 2) higher click-through rates via better quality of results from the Bing APIs. The following are the basic usage rules that apply to this header.
NOTE: Bing responses may or may not include this header. If the response includes this header, capture the client ID and use it for all subsequent Bing requests for the user on that device. NOTE: If you include the X-MSEdge-ClientID, you must not include cookies in the request. |
X-MSEdge-ClientIP | No | The IPv4 or IPv6 address of the client device. The IP address is used to discover the user's location. Bing uses the location information to determine safe search behavior. NOTE: Although optional, you are encouraged to always specify this header and the X-Search-Location header. Do not obfuscate the address (for example, by changing the last octet to 0). Obfuscating the address results in the location not being anywhere near the device's actual location, which may result in Bing serving erroneous results. |
X-Search-Location | No | A semicolon-delimited list of key/value pairs that describe the client's geographical location. Bing uses the location information to determine safe search behavior and to return relevant local content. Specify the key/value pair as <key>:<value>. The following are the keys that you use to specify the user's location.
NOTE: Bing ignores this header if the query includes a location. For example, if this header reflects the user’s location as San Francisco, but the query is restaurants seattle, Bing returns restaurants located in Seattle, Washington. NOTE: Although many of the keys are optional, they are important for providing accurate location results, so provide as many as you can. NOTE: Although optional, you are encouraged to always specify the user's geographical location. Providing the location is especially important if the client's IP address does not accurately reflect the user's physical location (for example, if the client uses VPN). For optimal results, you should include this header and the X-Search-ClientIP header, but at a minimum, you should include this header. |
Response headers
Header | Description |
---|---|
BingAPIs-Market | The market used by the request. The form is <languageCode>-<countryCode>. For example, en-US. This value may be different from the value you specify in the request's mkt query parameter if that market value is not listed in Market codes. The same is true if you specify values for cc and Accept-Language that can't be reconciled. |
BingAPIs-TraceId | The ID of the log entry that contains the details of the request. When an error occurs, capture this ID. If you are not able to determine and resolve the issue, include this ID along with the other information that you provide the Support team. |
Retry-After | The response includes this header if you exceed the number of queries allowed per second (QPS) or per month (QPM). The header contains the number of seconds that you must wait before sending another request. |
X-MSEdge-ClientID | See Request Headers: X-MSEdge-ClientID. |
Accessing headers in JavaScript
If you're using JavaScript, your browser's built-in security features (CORS) might prevent you from accessing the response header values. To handle this case, host a server-side script on the same domain as the Web page that uses the Bing Web Search API. This script should make API calls upon request from the Web page JavaScript and pass all results, including headers, back to the client. Since the two resources (page and script) share an origin, the headers are accessible to the JavaScript on the Web page.
This approach also protects your API key from exposure to the public, since only the server-side script needs it. The script can use another method to make sure the request is authorized.