# Safe Browsing Lists

This document applies to the following methods:

- [Lookup API (v4)](https://developers.google.com/safe-browsing/v4/lookup-api): [threatMatches.find](https://developers.google.com/safe-browsing/v4/lookup-api#example-threatmatchesfind)
- [Update API (v4)](https://developers.google.com/safe-browsing/v4/update-api): [fullHashes.find](https://developers.google.com/safe-browsing/v4/update-api#example-fullhashesfind)
- [Update API (v4)](https://developers.google.com/safe-browsing/v4/update-api): [threatListUpdates.fetch](https://developers.google.com/safe-browsing/v4/update-api#example-threatlistupdatesfetch)

## 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](https://developers.google.com/safe-browsing/reference/rest/v4/threatLists/list#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](https://developers.google.com/safe-browsing/reference/rest/v4/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](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 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](https://developers.google.com/safe-browsing/v4/urls-hashing)).

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](https://developers.google.com/safe-browsing/v4/lookup-api#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](https://developers.google.com/safe-browsing/v4/update-api#checking-urls) for the Update API).