Overview

The Safe Browing APIs (v3) enable client applications to check URLs against Google's constantly updated lists of suspected phishing, malware, and unwanted software pages. Clients can check if a URL is safe or unsafe using either Lookup API (v3) or the Update API (v3).

Lookup API (v3)

The Lookup API is an experimental API that enables applications to send URLs to our Safe Browsing service and check their status (e.g. phishing, malware, unwanted software). You don't need to know how the Safe Browsing service is implemented, and the API is simple and easy to use. You can start using the Lookup API now.

Advantages:

  • Simple to implement: API users send a HTTP GET or POST request with the URLs, and the server responds with the state of the URLs.

Drawbacks:

  • Privacy: URLs are not hashed, so the server knows which URLs API users look up.
  • Response time: Every lookup request is processed by the Safe Browsing server. We don't provide guarantees on lookup response time.

Update API (v3)

The Update API (previously referred to as the Safe Browsing API in the Protocol v3.0 Developer's Guide) is an experimental API that enables applications to download an encrypted table for local, client-side lookups of URLs that you would like to check. The Update API adds features and efficiency improvements to the previous version. The Update API is used by several browsers, including Google Chrome and Mozilla Firefox. You can start using the Update API now.

Advantages:

  • Privacy: API users exchange data with the server using hashed URLs, so the server never knows the actual URLs queried by the clients.
  • Response time: API users maintain a local cache of the hashed URLs in our suspected phishing, malware, and unwanted software lists; they do not need to query the server every time they want to check a URL.

Drawbacks:

  • The major drawback of the Update API is its implementation complexity.
    Update API users need to:
  • Be aware of the internal structures of how the server stores hashed URLs in the phishing, malware and unwanted software lists, and implement the hashing and suffix/prefix expressions.
  • Periodically update their local cache of the hashed URLs. If there are updates, they also need to download the new lists of hashed URLs.
  • Download and compare the full hash value of URLs that are hit in the local cache.
  • Canonicalize the URLs.

Choosing the Right API

If you are not too concerned about the privacy of the queried URLs, and you can tolerate the latency induced by a network request, consider using the Lookup API since it's much easier to implement. Otherwise, the Update API may be a better choice for you.