Safe Browsing API

Reference Guide

Contents

Audience

This document is intended for programmers who want to use Google phishing and malware data to protect users from potentially malicious websites.

It's a reference document; it assumes that you understand the concepts presented in the Developer's Guide.

Request Types

The API consists of two different types of HTTP requests:

  • https://sb-ssl.google.com/safebrowsing/getkey: This request requires SSL support. It provides the client with a private key for confidential communication with the server.
  • http://sb.google.com/safebrowsing/update: The client provides a list of tables that it wants the server to update. The server either provides the full content of the current tables or incremental updates to bring the client's tables up to the current version.

The getkey request takes one required parameter (client).

The response to the getkey request includes a client key and a wrapped key.

The update request takes three required parameters (client, apikey and version and one optional parameter (wrkey).

The response to the update request includes the appropriate table data, to bring that client up to date.

Query Parameters

The API supports the following query parameters:

Canonicalization Examples

This section provides some examples of canonicalizing IP addresses and URLs. To make sure you're able to look up URLs in the blacklists, you should verify that your client implementation handles these test cases correctly.

The first set of examples covers normalizing IP addresses into dotted decimal form:

Original Canonicalized Explanation
1.2.3.4 1.2.3.4 normal decimal form
012.034.01.055 10.28.1.45 octal components, identified by a leading zero
0x12.0x43.0x44.0x01 18.67.68.1 hex components, identified by a leading 0[xX]
167838211 10.1.2.3 fewer than 4 components, extend the last component to fill the remaining bytes
12.0x12.01234 12.18.2.156 mixed bases, fewer than 4 components
276.2.3 20.2.0.3 since 276 is not the last component, it's only allowed to take up 1 byte in the result
0x10000000b 0.0.0.11 if the number is larger than 32 bits, take the low 32 bits

The following strings are not well-formed IP addresses, and should not be normalized:
"0x120x34"
"123.123.0.0.1"
"1.2.3.00x0"

These examples cover canonicalizing URLs so that they can be used to create suffix/prefix expressions:

Original Canonicalized Explanation
http://google.com/ http://google.com/ already in canonical form
http://GOOgle.com http://google.com/ need a trailing slash, and lowercase the host
http://..google..com../ http://google.com/ strip leading and trailing dots, collapse multiple dots
http://google.com/%25%34%31%25%31%46 http://google.com/A%1F fully unescape, then re-escape once
http://google^.com/ http://google%5E.com/ escape characters in the hostname
http://google.com/1/../2/././ http://google.com/2/ relative path resolution
http://google.com/1//2?3//4 http://google.com/1/2?3//4 collapse consecutive slashes in the path

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.