Overview

The Lookup API lets your client applications check if a URL is included on any of the Web Risk lists.

Checking URLs

To check if a URL is on a Web Risk list, send an HTTP GET request to the uris.search method:

• The Lookup API supports one URL per request. To check multiple URLs, you need to send a separate request for each URL.

• You can specify multiple threat types in a single request by repeating the threatTypes field. For example:

  &threatTypes=SOCIAL_ENGINEERING&threatTypes=MALWARE
  

• The URL must be valid (see RFC 2396) but it doesn't need to be canonicalized.

• If you use the REST API, you must encode GET parameters, like the URI.

• The HTTP GET response returns the matching threat types, if any, along with the cache expiration.

Example: uris.search

HTTP method and URL:

GET https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY

To send your request, choose one of these options:

curl -X GET \
     "https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY"

$headers = @{  }
Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "threat": {
    "threatTypes": [
      "MALWARE"
    ],
    "expireTime": "2019-07-17T15:01:23.045123456Z"
  }
}

If no results match your request, you will get an empty JSON response of {}. This means that the URL you provided isn't on any threat lists.

Cache durations

The expireTime field indicates the timestamp at which the match should be considered expired. For details, see Caching.

What's next?

Learn about Using the Update API.