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.
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.
getkey request takes one required
The response to the
includes a client key and a wrapped key.
update request takes three required
one optional parameter (
The response to the
update request includes the appropriate
table data, to bring that client up to date.
The API supports the following query parameters:
client- should be used to specify the type of client, in this case "api". (Required for both
apikey- authenticates the user as a valid api user. See the Getting Started section in the Developer's Guide for information on getting an API key. (Required for
version- specifies the tables and versions that the client has, i.e. "version=goog-black-hash:1:432,goog-malware-hash:1:32". (Required for
wrkey- the wrapped key sent by the server in response to a
getkeyrequest. It should only be used if the client wishes to receive a MAC. (Optional for
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:
|18.104.22.168||22.214.171.124||normal decimal form|
|012.034.01.055||10.28.1.45||octal components, identified by a leading zero|
|0x12.0x43.0x44.0x01||126.96.36.199||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||188.8.131.52||mixed bases, fewer than 4 components|
|276.2.3||184.108.40.206||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:
These examples cover canonicalizing URLs so that they can be used to create suffix/prefix expressions:
|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|