Release Notes

  • Safe Browsing APIs v4 transitions to using HTTP POST requests with JSON format, replacing the previous GET method and plain text format.

  • The Update API v4 introduces a new diff-based update system for efficient threat list management and prioritizes threat lists based on client context.

  • A new threatLists.list method enables retrieval of available Safe Browsing lists.

  • The key parameter is now the sole requirement in HTTP POST request URLs for both Lookup and Update APIs.

  • Updated HTTP status codes reflect the changes in request and response handling within the v4 APIs.

Version 4.0

The following updates and new features are included in the Safe Browsing APIs (v4).

Lookup API (v4)

What's the same:

  • The API still has clients directly query the Google Safe Browsing server and Safe Browsing lists.

What's different:

  • The HTTP GET method is no longer supported. Use the HTTP POST method instead.
  • The key parameter is now the only parameter required in the HTTP POST request URL.
  • The HTTP POST request and response format have changed. Plain text is no longer supported. Use JSON instead.

Update API (v4)

What's the same:

  • The API still has clients periodically update the SHA256 hash prefixes in the local database's lists.
  • The API also has a similar request to retrieve the SHA256 full-length hashes when a client encounters a hash prefix collision.

What's different:

  • The key parameter is now the only parameter required in the HTTP POST request URL.
  • The HTTP POST request and response format have changed. Plain text is no longer supported. Use JSON instead.
  • The way updates are encoded has changed. Instead of serving add and sub chunks, the API now serves diffs using a simple versioning protocol. The client sends its current state to the server along with the requested updates. The server responds with a new client state and a diff to get the client fully updated.
  • To ensure minimal sacrifice of protection when accommodating client constraints, the API serves prioritized threat lists. Device resources, bandwidth, geolocation, and other signals are used to serve the highest priority threat data to each client.

threatLists.list Method

A new method, threatLists.list, returns a list of the Safe Browsing lists currently available for lookup or download.

Status Codes

The HTTP status codes generated by the server in response to an HTTP POST request have changed.