Project URL Preview v7 reference

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.

Endpoint

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.

Headers

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.
  • Each user that uses your application on the device must have a unique, Bing generated client ID.

    If you do not include this header in the request, Bing generates an ID and returns it in the X-MSEdge-ClientID response header. The only time that you should NOT include this header in a request is the first time the user uses your app on that device.

  • Use the client ID for each Bing API request that your app makes for this user on the device.

  • ATTENTION: You must ensure that this Client ID is not linkable to any authenticatable user account information.

  • Persist the client ID. To persist the ID in a browser app, use a persistent HTTP cookie to ensure the ID is used across all sessions. Do not use a session cookie. For other apps such as mobile apps, use the device's persistent storage to persist the ID.

    The next time the user uses your app on that device, get the client ID that you persisted.

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.

Query parameters

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.
  • JSON
  • JSONLD

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.

  • safeSearch=strict: Title, description, URL and image will not be returned.
  • safeSearch=moderate; Get title, URL and description but not the descriptive image.
  • safeSearch=off; Get all the response objects/elements – title, URL, description, and image.
String Not required.
Defaults to safeSearch=strict.

Response Objects

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.

Error

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

ErrorResponse

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[]

WebPage

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

Identifiable

Name Value Type
id A resource identifier String

Error codes

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.

Next steps