Safe Browsing Lists

This document applies to the following methods:

• Lookup API (v4): threatMatches.find
• Update API (v4): fullHashes.find
• Update API (v4): threatListUpdates.fetch

About the lists

The Safe Browsing lists—also referred to as threat lists or simply lists—are Google's constantly updated lists of unsafe web resources. Examples of unsafe web resources are social engineering sites (phishing and deceptive sites) and sites that host malware or unwanted software.

List names

Each Safe Browsing list is named (identified) using three parameters or type combinations: the threatType, platformType, and threatEntryType (see ThreatListDescriptor).

Before sending a request to the Safe Browsing servers, the client should retrieve the names of the currently available Safe Browsing lists. This will help ensure that the parameters or type combinations specified in the request are valid.

To retrieve the names of the Safe Browsing lists, use the threatLists.list method and HTTP GET request/response.

Example: threatLists.list

HTTP GET request

The request includes a header only (no request body).

Request header

The request header includes the request URL and the content type. Remember to substitute your API key for API_KEY in the URL.

GET https://safebrowsing.googleapis.com/v4/threatLists?key=API_KEY HTTP/1.1
Content-Type: application/json

Request body

There is no request body for this method.

HTTP GET response

The response returns the Safe Browsing lists currently available for query or download. In this example, only two lists are shown, but additional lists are available and will be returned.

Response header

The response header includes the HTTP status code and the content type.

HTTP/1.1 200 OK
Content-Type: application/json

Response body

The Safe Browsing lists are returned as an array of threat lists. As noted, each list is defined by three parameters or type combinations: the threatType, platformType, and threatEntryType.

{
  threatLists: [{
      "threatType":      "MALWARE",
      "platformType":    "WINDOWS",
      "threatEntryType": "URL",
  }, {
      "threatType":      "MALWARE",
      "platformType":    "LINUX",
      "threatEntryType": "URL",
  }, {
    ... additional lists will be returned ...
  }]
}

List contents

Currently, all Safe Browsing lists consist of variable length SHA 256 hashes between 4 and 32 bytes. These hashes are based on the suffix/prefix expressions of the URLs associated with unsafe web resources. Note that the URLs themselves are not stored in the Safe Browsing lists (see URLs and Hashes).

When using the Lookup API to check URLs, the client sends the actual URL in the request and Safe Browsing server converts the URL to a hash before performing the check (see Checking URLs for the Lookup API).

When using the Update API to check URLs, the client must convert the URL to a hash and then send the hash prefix in the request in order to perform the URL check (see Checking URLs for the Update API).