# 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](https://developers.google.com/safe-browsing/reference/rest/v4/threatMatches/find)
method:

- The HTTP `POST` request can include up to 500 URLs. The URLs must be valid (see [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt)) 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](https://developers.google.com/safe-browsing/reference/rest/v4/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](https://developers.google.com/safe-browsing/v4/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](https://developers.google.com/safe-browsing/reference/rest/v4/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](https://developers.google.com/safe-browsing/v4/status-codes)
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](https://developers.google.com/safe-browsing/reference/rest/v4/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](https://developers.google.com/safe-browsing/v4/metadata)).

###### Cache durations

The `cacheDuration` field indicates the amount of time the URL must be considered unsafe
(see [Caching](https://developers.google.com/safe-browsing/v4/caching)).