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

• client - should be used to specify the type of client, in this case "api". (Required for both getkey and update requests.)
• 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 update request only)
• 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 update request only)
• wrkey - the wrapped key sent by the server in response to a getkey request. It should only be used if the client wishes to receive a MAC. (Optional for update request)

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:

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: