Using the Update API

Overview

The Update API lets your client applications download hashed versions of the Web Risk lists for storage in a local or in-memory database. URLs can then be checked locally. When a match is found in the local database, the client sends a request to the Web Risk servers to verify whether the URL is included on the Web Risk lists.

Updating the local database

To stay current, clients are required to periodically update the Web Risk lists in their local database. To save bandwidth, clients download the hash prefixes of URLs rather than the raw URLs. For example, if "www.badurl.com/" is on a Web Risk list, clients download the SHA256 hash prefix of that URL rather than the URL itself. In the majority of cases the hash prefixes are 4 bytes long, meaning that the average bandwidth cost of downloading a single list entry is 4 bytes before compression.

To update the Web Risk lists in the local database, send an HTTP GET request to the threatLists.computeDiff method:

• The HTTP GET request includes the name of the list to be updated along with client constraints to account for memory and bandwidth limitations.
• The HTTP GET response returns either a full update or a partial update. The response could also return a recommended wait time until the next compute diff operation.

Example: threatLists.computeDiff

HTTP GET request

In the following example, the diffs for the MALWARE Web Risk list are requested. For more details, see the threatLists.computeDiff query parameters and the explanations that follow the code example.

HTTP method and URL:

GET https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY

To send your request, choose one of these options:

curl -X GET \
     "https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY"

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY" | Select-Object -Expand Content

You should receive a JSON response similar to the following: