Method: threatListUpdates.fetch

Fetches the most recent threat list updates. A client can request updates for multiple lists at once.

HTTP request

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "client": {
    object (ClientInfo)
  },
  "listUpdateRequests": [
    {
      object (ListUpdateRequest)
    }
  ]
}
Fields
client

object (ClientInfo)

The client metadata.
listUpdateRequests[]

object (ListUpdateRequest)

The requested threat list updates.

Response body

If successful, the response body contains data with the following structure:

JSON representation 
{
  "listUpdateResponses": [
    {
      object (ListUpdateResponse)
    }
  ],
  "minimumWaitDuration": string
}
Fields
listUpdateResponses[]

object (ListUpdateResponse)

The list updates requested by the clients. The number of responses here may be less than the number of requests sent by clients. This is the case, for example, if the server has no updates for a particular list.
minimumWaitDuration

string (Duration format)

The minimum duration the client must wait before issuing any update request. If this field is not set clients may update as soon as they want.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

ListUpdateRequest

A single list update request.

JSON representation 
{
  "threatType": enum (ThreatType),
  "platformType": enum (PlatformType),
  "threatEntryType": enum (ThreatEntryType),
  "state": string,
  "constraints": {
    object (Constraints)
  }
}
Fields
threatType

enum (ThreatType)

The type of threat posed by entries present in the list.
platformType

enum (PlatformType)

The type of platform at risk by entries present in the list.
threatEntryType

enum (ThreatEntryType)

The types of entries present in the list.
state

string (bytes format)

The current state of the client for the requested list (the encrypted client state that was received from the last successful list update).

A base64-encoded string.
constraints

object (Constraints)

The constraints associated with this request.

Constraints

The constraints for this update.

JSON representation 
{
  "maxUpdateEntries": integer,
  "maxDatabaseEntries": integer,
  "region": string,
  "supportedCompressions": [
    enum (CompressionType)
  ],
  "language": string,
  "deviceLocation": string
}
Fields
maxUpdateEntries

integer

The maximum size in number of entries. The update will not contain more entries than this value. This should be a power of 2 between 2**10 and 2**20. If zero, no update size limit is set.
maxDatabaseEntries

integer

Sets the maximum number of entries that the client is willing to have in the local database for the specified list. This should be a power of 2 between 2**10 and 2**20. If zero, no database size limit is set.
region

string

Requests the list for a specific geographic location. If not set the server may pick that value based on the user's IP address. Expects ISO 3166-1 alpha-2 format.
supportedCompressions[]

enum (CompressionType)

The compression types supported by the client.
language

string

Requests the lists for a specific language. Expects ISO 639 alpha-2 format.
deviceLocation

string

A client's physical location, expressed as a ISO 31166-1 alpha-2 region code.

CompressionType

The ways in which threat entry sets can be compressed.

Enums
COMPRESSION_TYPE_UNSPECIFIED Unknown.
RAW Raw, uncompressed data.
RICE Rice-Golomb encoded data.

ListUpdateResponse

An update to an individual list.

JSON representation 
{
  "threatType": enum (ThreatType),
  "threatEntryType": enum (ThreatEntryType),
  "platformType": enum (PlatformType),
  "responseType": enum (ResponseType),
  "additions": [
    {
      object (ThreatEntrySet)
    }
  ],
  "removals": [
    {
      object (ThreatEntrySet)
    }
  ],
  "newClientState": string,
  "checksum": {
    object (Checksum)
  }
}
Fields
threatType

enum (ThreatType)

The threat type for which data is returned.
threatEntryType

enum (ThreatEntryType)

The format of the threats.
platformType

enum (PlatformType)

The platform type for which data is returned.
responseType

enum (ResponseType)

The type of response. This may indicate that an action is required by the client when the response is received.
additions[]

object (ThreatEntrySet)

A set of entries to add to a local threat type's list. Repeated to allow for a combination of compressed and raw data to be sent in a single response.
removals[]

object (ThreatEntrySet)

A set of entries to remove from a local threat type's list. In practice, this field is empty or contains exactly one ThreatEntrySet.
newClientState

string (bytes format)

The new client state, in encrypted format. Opaque to clients.

A base64-encoded string.
checksum

object (Checksum)

The expected SHA256 hash of the client state; that is, of the sorted list of all hashes present in the database after applying the provided update. If the client state doesn't match the expected state, the client must disregard this update and retry later.

ResponseType

The type of response sent to the client.

Enums
RESPONSE_TYPE_UNSPECIFIED Unknown.
PARTIAL_UPDATE Partial updates are applied to the client's existing local database.
FULL_UPDATE Full updates replace the client's entire local database. This means that either the client was seriously out-of-date or the client is believed to be corrupt.

ThreatEntrySet

A set of threats that should be added or removed from a client's local database.

JSON representation 
{
  "compressionType": enum (CompressionType),
  "rawHashes": {
    object (RawHashes)
  },
  "rawIndices": {
    object (RawIndices)
  },
  "riceHashes": {
    object (RiceDeltaEncoding)
  },
  "riceIndices": {
    object (RiceDeltaEncoding)
  }
}
Fields
compressionType

enum (CompressionType)

The compression type for the entries in this set.
rawHashes

object (RawHashes)

The raw SHA256-formatted entries.
rawIndices

object (RawIndices)

The raw removal indices for a local list.
riceHashes

object (RiceDeltaEncoding)

The encoded 4-byte prefixes of SHA256-formatted entries, using a Golomb-Rice encoding. The hashes are converted to uint32, sorted in ascending order, then delta encoded and stored as encodedData.
riceIndices

object (RiceDeltaEncoding)

The encoded local, lexicographically-sorted list indices, using a Golomb-Rice encoding. Used for sending compressed removal indices. The removal indices (uint32) are sorted in ascending order, then delta encoded and stored as encodedData.

RawHashes

The uncompressed threat entries in hash format of a particular prefix length. Hashes can be anywhere from 4 to 32 bytes in size. A large majority are 4 bytes, but some hashes are lengthened if they collide with the hash of a popular URL.

Used for sending ThreatEntrySet to clients that do not support compression, or when sending non-4-byte hashes to clients that do support compression.

JSON representation 
{
  "prefixSize": integer,
  "rawHashes": string
}
Fields
prefixSize

integer

The number of bytes for each prefix encoded below. This field can be anywhere from 4 (shortest prefix) to 32 (full SHA256 hash).
rawHashes

string (bytes format)

The hashes, in binary format, concatenated into one long string. Hashes are sorted in lexicographic order. For JSON API users, hashes are base64-encoded.

A base64-encoded string.

RawIndices

A set of raw indices to remove from a local list.

JSON representation 
{
  "indices": [
    integer
  ]
}
Fields
indices[]

integer

The indices to remove from a lexicographically-sorted local list.

RiceDeltaEncoding

The Rice-Golomb encoded data. Used for sending compressed 4-byte hashes or compressed removal indices.

JSON representation 
{
  "firstValue": string,
  "riceParameter": integer,
  "numEntries": integer,
  "encodedData": string
}
Fields
firstValue

string (int64 format)

The offset of the first entry in the encoded data, or, if only a single integer was encoded, that single integer's value. If the field is empty or missing, assume zero.
riceParameter

integer

The Golomb-Rice parameter, which is a number between 2 and 28. This field is missing (that is, zero) if numEntries is zero.
numEntries

integer

The number of entries that are delta encoded in the encoded data. If only a single integer was encoded, this will be zero and the single value will be stored in firstValue.
encodedData

string (bytes format)

The encoded deltas that are encoded using the Golomb-Rice coder.

A base64-encoded string.

Checksum

The expected state of a client's local database.

JSON representation 
{
  "sha256": string
}
Fields
sha256

string (bytes format)

The SHA256 hash of the client state; that is, of the sorted list of all hashes present in the database.

A base64-encoded string.