Safe Browsing Lookup API (v4)

Overview

The Lookup API lets your client applications send requests to the Safe Browsing servers to check if URLs are included on any of the Safe Browsing lists. If a URL is found on one or more lists, the matching information is returned.

Checking URLs

To check if a URL is on a Safe Browsing list, send an HTTP POST request to the threatMatches.find method:

• The HTTP POST request can include up to 500 URLs. The URLs must be valid (see RFC 2396) but they do not need to be canonicalized or encoded.
• The HTTP POST response returns the matching URLs along with the cache duration.

Example: threatMatches.find

HTTP POST request

In the following example, two Safe Browsing lists and three URLs are sent to the server to determine if there is a match.

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.

  POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1
  Content-Type: application/json
  

Request body

The request body includes the client information (ID and version) and the threat information (the list names and the URLs). For more details, see the threatMatches.find request body and the explanations that follow the code example.

  {
    "client": {
      "clientId":      "yourcompanyname",
      "clientVersion": "1.5.2"
    },
    "threatInfo": {
      "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
      "platformTypes":    ["WINDOWS"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [
        {"url": "http://www.urltocheck1.org/"},
        {"url": "http://www.urltocheck2.org/"},
        {"url": "http://www.urltocheck3.com/"}
      ]
    }
  }

Client information

The clientID and clientVersion fields should uniquely identify a client implementation, not an individual user. (Client information is used for server-side logging and accounting. You can choose any name for the client ID, but we suggest you choose a name that represents the true identity of the client, such as your company name, presented as all one word, in all-lowercase letters.)

Safe Browsing lists

The threatType, platformType, and threatEntryType fields are combined to identify (name) Safe Browsing lists. In the example, two lists are identified: MALWARE/WINDOWS/URL and SOCIAL_ENGINEERING/WINDOWS/URL. Before sending a request, make sure the type combinations you specify are valid (see Safe Browsing Lists).

Threat URLs

In the example, the threatEntries array contains three URLs (urltocheck1.org, urltocheck2.org, and urltocheck3.org) that will be checked against the two Safe Browsing lists.

Note: The Lookup API and the threatMatches method should always use the URL field, never the hash field (see ThreatEntry).

HTTP POST response

In the following example, the response returns a match; two of the three URLs specified in the request are found on one of the two Safe Browsing lists specified in the request.

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 response body includes the match information (the list names and the URLs found on those lists, the metadata, if available, and the cache durations). For more details, see the threatMatches.find response body and the explanations that follow the code example.

Note: If there are no matches (that is, if none of the URLs specified in the request are found on any of the lists specified in a request), the HTTP POST response simply returns an empty object in the response body.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck1.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key": "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck2.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key":   "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }]
}

Matches

The matches object lists the names of the Safe Browsing lists and the URLs—if there is match. In the example, two URLs (urltocheck1.org and urltocheck2.org) were found on one of the Safe Browsing lists (MALWARE/WINDOWS/URL) so the matching information is returned. The third URL (urltocheck3.org) was not found on either list, so no information is returned for this URL.

Metadata

The threatEntryMetadata field is optional and provides additional information about the threat match. Currently, metadata is available for the MALWARE/WINDOWS/URL Safe Browsing list (see Metadata).

Cache durations

The cacheDuration field indicates the amount of time the URL must be considered unsafe (see Caching).