URL Preview supports brief descriptions of Web resources for blog posts, forum discussions, preview pages, etc. The URL can be any type of Internet resource: Web page, news, image, or video. The query must be an absolute URL with an http or https scheme; relative URLs or other schemes like ftp:// are not supported.
Applications that use URL Preview send Web requests to the endpoint with a URL to preview in a query parameter. The request must include the Ocp-Apim-Subscription-Key header.
The JSON response can be parsed for the preview information: name, description of the resource, isFamilyFriendly, and links that provide access to a representative image and to the complete resource online.
You must use only the data from URL Preview to display preview snippets and thumbnail images hyperlinked to their source sites, in end user-initiated URL sharing on social media, chat bot or similar offerings. You must not copy, store or cache any data you receive from Project URL Preview. You must honor any requests to disable previews that you may receive from website or content owners.
To request URL Preview results, send a request to the following endpoint. Use the headers and URL parameters to define further specifications.
Endpoint GET:
https://api.labs.cognitive.microsoft.com/urlpreview/v7.0/search?q=queryURL
The request must use the HTTPS protocol and include following query parameter:
q - The query that identifies the URL to preview
The following sections provide technical details about the response objects, query parameters, and headers that affect the search results.
For information about headers that requests should include, see Headers.
For information about query parameters that requests should include, see Query parameters.
For information about the JSON objects that the response includes, see Response objects.
The maximum query URL length is 2,048 characters. To ensure that your URL length does not exceed the limit, the maximum length of your query parameters should be less than 1,500 characters. If the URL exceeds 2,048 characters, the server returns 404 Not found.
For information about permitted use and display of results, see Use and display requirements.
Note
Some request headers that are meaningful for other search APIs don’t affect URL Preview
- Pragma – the caller does not have control over whether URL Preview uses cache
- User-Agent – For now, Url Preview API doesn’t provide different responses for calls emanating from PC, Laptop, or Mobile.
Also, some parameters are not currently meaningful for URL Preview API, but may be used in the future for improved globalization.
The following are the headers that a request and response may include.
| Header | Description |
|---|---|
| BingAPIs-Market | Response header. The market used by the request. The form is <languageCode>-<countryCode>. For example, en-US. |
| BingAPIs-TraceId | Response header. 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. |
| Ocp-Apim-Subscription-Key | Required request header. The subscription key that you received when you signed up for this service in Cognitive Services. |
| X-MSEdge-ClientID | Optional request and response header. 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. 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 | Optional request header. 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. 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. |
The request may include the following query parameters. See the Required column for required parameters. You must URL encode the query parameters. The query must be an absolute URL with an http or https scheme; we don’t support relative URLs or other schemes like ftp://
| Name | Value | Type | Required |
|---|---|---|---|
| mkt | The market where the results come from. For a list of possible market values, see Market Codes. NOTE: The URL Preview API currently only supports US geography and English language. |
String | Yes |
| q | The URL to preview | String | Yes |
| responseFormat | The media type to use for the response. The following are the possible case-insensitive values.
The default is JSON. For information about the JSON objects that the response contains, see Response Objects. If you specify JsonLd, the response body includes JSON-LD objects that contain the search results. For information about the JSON-LD, see JSON-LD. |
String | No |
| safeSearch | Illegal adult content, or pirated content, is blocked with error code 400, and the isFamilyFriendly flag is not returned. For legal adult content, below is the behavior. Status code returns 200, and the isFamilyFriendly flag is set to false.
|
String | Not required. Defaults to safeSearch=strict. |
The response schema is either a [WebPage] or ErrorResponse, as in the Web Search API. If the request fails, the top-level object is the ErrorResponse object.
| Object | Description |
|---|---|
| WebPage | Top level JSON object that contains attributes of preview. |
Defines the error that occurred.
| Element | Description | Type |
|---|---|---|
| code | The error code that identifies the category of error. For a list of possible codes, see Error Codes. | String |
| message | A description of the error. | String |
| moreDetails | A description that provides additional information about the error. | String |
| parameter | The query parameter in the request that caused the error. | String |
| subCode | The error code that identifies the error. For example, if code is InvalidRequest, subCode may be ParameterInvalid or ParameterInvalidValue. |
String |
| value | The query parameter's value that was not valid. | String |
The top-level object that the response includes when the request fails.
| Name | Value | Type |
|---|---|---|
| _type | Type hint. | String |
| errors | A list of errors that describe the reasons why the request failed. | Error[] |
Defines information about a the Web page in preview.
| Name | Value | Type |
|---|---|---|
| name | The page title, not necessarily the HTML title | String |
| url | The URL that was actually crawled (request may have followed redirects) | String |
| description | Brief description of the page and content | String |
| isFamilyFriendly | Most accurate for items in the web index; realtime fetches do this detection based solely on the URL and not the page content | boolean |
| primaryImageOfPage/contentUrl | The URL to a representative image to include in the preview | String |
| Name | Value | Type |
|---|---|---|
| id | A resource identifier | String |
The following are the possible HTTP status codes that a request returns.
| Status Code | Description |
|---|---|
| 200 | Success. |
| 400 | One of the query parameters is missing or not valid. |
| 400 | ServerError, subCode ResourceError: The requested URL could not be reached |
| 400 | ServerError, subCode ResourceError: The requested URL did not return a success code (including if it returned HTTP 404) |
| 400 | InvalidRequest, subCode Blocked: The requested URL may contain adult content and was blocked |
| 401 | The subscription key is missing or is not valid. |
| 403 | The user is authenticated (for example, they used a valid subscription key) but they don’t have permission to the requested resource. Bing may also return this status if the caller exceeded their queries per month quota. |
| 410 | The request used HTTP instead of the HTTPS protocol. HTTPS is the only supported protocol. |
| 429 | The caller exceeded their queries per second quota. |
| 500 | Unexpected server error. |
If the request fails, the response contains an ErrorResponse object, which contains a list of Error objects that describe what caused of error. If the error is related to a parameter, the parameter field identifies the parameter that is the issue. And if the error is related to a parameter value, the value field identifies the value that is not valid.
{
"_type": "ErrorResponse",
"errors": [
{
"code": "InvalidRequest",
"subCode": "ParameterMissing",
"message": "Required parameter is missing.",
"parameter": "q"
}
]
}
{
"_type": "ErrorResponse",
"errors": [
{
"code": "InvalidAuthorization",
"subCode": "AuthorizationMissing",
"message": "Authorization is required.",
"moreDetails": "Subscription key is not recognized."
}
]
}The following are the possible error code and sub-error code values.
| Code | SubCode | Description |
|---|---|---|
| ServerError | UnexpectedError ResourceError NotImplemented |
HTTP status code is 500. |
| InvalidRequest | ParameterMissing ParameterInvalidValue HttpNotAllowed Blocked |
Bing returns InvalidRequest whenever any part of the request is not valid. For example, a required parameter is missing or a parameter value is not valid. If the error is ParameterMissing or ParameterInvalidValue, the HTTP status code is 400. If you use the HTTP protocol instead of HTTPS, Bing returns HttpNotAllowed, and the HTTP status code is 410. |
| RateLimitExceeded | No sub-codes | Bing returns RateLimitExceeded whenever you exceed your queries per second (QPS) or queries per month (QPM) quota. If you exceed QPS, Bing returns HTTP status code 429, and if you exceed QPM, Bing returns 403. |
| InvalidAuthorization | AuthorizationMissing AuthorizationRedundancy |
Bing returns InvalidAuthorization when Bing cannot authenticate the caller. For example, the Ocp-Apim-Subscription-Key header is missing or the subscription key is not valid.Redundancy occurs if you specify more than one authentication method. If the error is InvalidAuthorization, the HTTP status code is 401. |
| InsufficientAuthorization | AuthorizationDisabled AuthorizationExpired |
Bing returns InsufficientAuthorization when the caller does not have permissions to access the resource. This can occur if the subscription key has been disabled or has expired. If the error is InsufficientAuthorization, the HTTP status code is 403. |