Google Safe Browsing Getting Started: API Key & First Scan (2026)

Getting started overview

Google Safe Browsing offers two primary APIs for developers to implement threat detection: the Lookup API and the Update API. The Lookup API allows for real-time checks of individual URLs against Google's threat lists. The Update API enables applications to maintain a local database of unsafe URLs, suitable for scenarios where frequent checks or offline capabilities are necessary Google Safe Browsing Lookup API overview. Both APIs require an API key for authentication and adhere to a usage quota, with a free tier available for initial development and lower-volume applications. Integration typically involves configuring your project in the Google Cloud Console, enabling the Safe Browsing API, and making HTTP requests to the designated API endpoints.

The initial setup process focuses on acquiring the necessary credentials and sending a basic request to confirm connectivity and authentication. This guide will walk through the steps to get an API key, activate the Safe Browsing API, and execute a simple URL check using the Lookup API. Understanding the distinction between the Lookup and Update APIs is crucial for selecting the appropriate integration strategy for your application's security requirements Google Safe Browsing Update API details.

Quick Reference Table

Create an account and get keys

To begin using Google Safe Browsing, you must have a Google Cloud account and an active project. If you do not have a Google Cloud account, you can sign up and create one. Once an account is established, follow these steps to enable the Safe Browsing API and generate an API key:

1. Navigate to the Google Cloud Console: Sign in with your Google account at the Google Cloud Console.
2. Select or Create a Project: From the project selector at the top of the page, choose an existing project or create a new one. All API usage is tied to a project.
3. Enable the Safe Browsing API:
   • In the navigation menu, go to APIs & Services > Library.
   • Search for "Safe Browsing API".
   • Select the "Safe Browsing API" from the search results.
   • Click the Enable button. This activates the API for your selected project Google Safe Browsing developer guide.
4. Generate an API Key:
   • In the navigation menu, go to APIs & Services > Credentials.
   • Click "Create Credentials" and select "API Key".
   • A new API key will be generated and displayed. Copy this key immediately.
   • (Optional but Recommended) Restrict the API Key: To enhance security, consider restricting the API key to specific IP addresses, HTTP referrers, or the Safe Browsing API itself. Click "Edit API key" and configure the application or API restrictions Securing API keys in Google Cloud.

The generated API key is a secret credential and should be handled securely. Avoid embedding it directly in client-side code or public repositories. Use environment variables or a secure configuration management system to store and access it.

Your first request

With your API key in hand and the Safe Browsing API enabled, you can now make your first request using the Lookup API. This example demonstrates how to check a URL for known threats. The Lookup API accepts a list of URLs and returns threat information if any are found on Google's unsafe lists. For this example, we will use curl, a command-line tool for making HTTP requests.

Example: Checking a URL with the Lookup API (v4)

The Lookup API endpoint is https://safebrowsing.googleapis.com/v4/threatMatches:find. You need to include your API key as a query parameter and send a JSON payload in the request body specifying the client information and the URL(s) to check.

curl -X POST \ 
  -H "Content-Type: application/json" \ 
  "https://safebrowsing.googleapis.com/v4/threatMatches:find?key=YOUR_API_KEY" \ 
  -d @- << EOF
{
  "client": {
    "clientId": "your-company-name",
    "clientVersion": "1.5.2"
  },
  "threatInfo": {
    "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE", "POTENTIALLY_HARMFUL_APPLICATION", "PHISHING"],
    "platformTypes": ["ANY_PLATFORM"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"url": "http://testsafebrowsing.appspot.com/s/malware.html"}
    ]
  }
}
EOF

Replace YOUR_API_KEY with the API key you generated. For clientId and clientVersion, provide a unique identifier for your application and its version. These values help Google monitor API usage and identify potential issues.

The example URL http://testsafebrowsing.appspot.com/s/malware.html is a known test URL designed to trigger a malware detection from Safe Browsing Testing Google Safe Browsing API. Using this URL helps confirm that your API key is correctly configured and that the API is returning expected threat matches.

Expected Response

A successful request against the test URL should return a JSON response similar to this, indicating a threat match:

{
  "matches": [
    {
      "threatType": "MALWARE",
      "platformType": "ANY_PLATFORM",
      "threatEntryType": "URL",
      "threatEntry": {
        "url": "http://testsafebrowsing.appspot.com/s/malware.html"
      },
      "cacheDuration": "300s"
    }
  ]
}

If no threats are detected for a given URL, the matches array in the JSON response will be empty.

Common next steps

After successfully making your first request, consider these common next steps to further integrate Google Safe Browsing into your applications:

1. Implement Error Handling: Develop robust error handling for API responses, including handling rate limits, invalid API keys, and other potential issues. The API returns standard HTTP status codes for various error conditions Google Safe Browsing API error responses.
2. Explore the Update API: For applications that process large volumes of URLs or require lower latency, investigate the Google Safe Browsing Update API. This API allows you to download and maintain local threat lists, reducing the number of requests to the Lookup API and potentially improving performance.
3. Caching Threat Matches: The Lookup API response includes a cacheDuration field. Implement caching mechanisms for detected threats to avoid redundant API calls for URLs that are known to be unsafe for a specified period.
4. Client-side Integration: For web applications, consider how to integrate Safe Browsing checks without exposing your API key client-side. This typically involves making API calls from your backend server.
5. Monitor Usage & Quotas: Regularly check your API usage in the Google Cloud Console API Dashboard to ensure you stay within the free tier limits or to anticipate when you might transition to paid usage. Google Safe Browsing offers a free tier of up to 10,000 requests per day, after which a per-request fee applies Google Safe Browsing pricing details.
6. Understand Threat Types: Familiarize yourself with the different threatTypes and platformTypes returned by the API to categorize and respond to threat detections appropriately. For instance, a MALWARE threat might warrant a different user alert than a SOCIAL_ENGINEERING one. Mozilla's Safe Browsing API documentation also provides context on threat list types and how they are used Mozilla Safe Browsing API threat types.
7. Optimize Payload Structure: When checking multiple URLs, consolidate them into a single request to minimize API call overhead, as the Lookup API supports checking multiple threatEntries in one go.

Troubleshooting the first call

If your first API call does not return the expected results, consider the following common issues and troubleshooting steps:

• Invalid API Key: Double-check that you have copied the API key correctly and that it is included as the key query parameter in your request URL. Ensure no extra spaces or characters are present.
• API Not Enabled: Verify that the Safe Browsing API is enabled for your Google Cloud project. Navigate to the API Library in the Google Cloud Console and confirm its status.
• Incorrect Endpoint: Confirm that you are sending the request to the correct endpoint for the Lookup API: https://safebrowsing.googleapis.com/v4/threatMatches:find.
• Improper Request Body Format: The request body must be valid JSON and adhere to the Google Safe Browsing Lookup API request body specification. Pay attention to quotation marks, commas, and bracket placement.
• Missing Content-Type Header: Ensure your request includes the Content-Type: application/json header. Without it, the API may not correctly parse your request body.
• API Key Restrictions: If you applied restrictions to your API key, ensure they permit calls from your current environment. For testing, you might temporarily remove restrictions to isolate the issue, then re-apply them carefully.
• Quota Limits: While unlikely for a first call, if you or your project have previously used the API, check the Quotas page in the Google Cloud Console to see if you have exceeded your daily limit.
• Network Issues: Confirm that your machine or server has outbound internet access and can reach googleapis.com.
• Using a Valid Test URL: Ensure you are using a URL known to trigger a threat detection, such as http://testsafebrowsing.appspot.com/s/malware.html, to confirm successful detection Official Safe Browsing test URLs.
• Client/Version Information: While not strictly an error, ensure your clientId and clientVersion are included in the request body. These are used for diagnostic purposes.