Install & Compatibility
Where this runs
tested against v1.21.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.947s · 68.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.4s · import 1.444s · 66MB
67MB installed
● package 67MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WebRiskServiceClient
✓ from google.cloud.webrisk_v1 import WebRiskServiceClient
ThreatType
✓ from google.cloud.webrisk_v1 import ThreatType
SearchUrisRequest
✓ from google.cloud.webrisk_v1 import SearchUrisRequest
✗ from google.cloud.webrisk_v1.types import SearchUrisRequest
Types are directly available under the `_v1` namespace for convenience.
This quickstart demonstrates how to instantiate the WebRiskServiceClient and use the `search_uris` method to check a URL against various threat lists (MALWARE, SOCIAL_ENGINEERING, UNWANTED_SOFTWARE). It shows examples for both a safe and a known unsafe URI. Ensure your Google Cloud credentials are set up for the client to authenticate automatically.
import os
from google.cloud import webrisk_v1
from google.cloud.webrisk_v1 import WebRiskServiceClient, ThreatType
def search_uri(uri: str, threat_types: list[ThreatType]) -> dict:
"""Checks whether a URI is on a given threatList."""
client = WebRiskServiceClient()
request = webrisk_v1.SearchUrisRequest(
uri=uri,
threat_types=threat_types,
)
response = client.search_uris(request=request)
return response.threat.to_dict() if response.threat else {"threatTypes": []}
if __name__ == "__main__":
# Ensure GOOGLE_APPLICATION_CREDENTIALS is set, e.g.:
# export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"
# or use `gcloud auth application-default login`
# The client library will automatically find credentials if set.
test_uri_safe = "http://example.com"
# This is a known test URI for malware from Google Safe Browsing.
test_uri_unsafe = "http://testsafebrowsing.appspot.com/s/malware.html"
threat_types_to_check = [
ThreatType.MALWARE,
ThreatType.SOCIAL_ENGINEERING,
ThreatType.UNWANTED_SOFTWARE,
]
print(f"Checking safe URI: {test_uri_safe}")
result_safe = search_uri(test_uri_safe, threat_types_to_check)
print(f"Result for {test_uri_safe}: {result_safe}")
print(f"\nChecking unsafe URI: {test_uri_unsafe}")
result_unsafe = search_uri(test_uri_unsafe, threat_types_to_check)
print(f"Result for {test_uri_unsafe}: {result_unsafe}")
Debug
Known issues
gotchaAuthentication is required for all Google Cloud client library operations. Ensure `GOOGLE_APPLICATION_CREDENTIALS` environment variable is set or your environment is authenticated via `gcloud auth application-default login`.fixSet `GOOGLE_APPLICATION_CREDENTIALS` to a service account key JSON file or run `gcloud auth application-default login`.
affects: All
breakingThe `submit_uri` method (for reporting suspicious URLs) is restricted to allowlisted projects only during Early Access. Attempts from non-allowlisted projects will fail.fixContact Google Cloud Sales or your customer engineer to request allowlist access for your project if you need to use `submit_uri`.
affects: All (current API behavior)
gotchaThe Web Risk API client library officially supports Python 3.9 and newer. Older Python versions (3.8 and below) are unsupported.fixUpgrade your Python environment to version 3.9 or higher.
affects: <= 3.8
gotchaInformation returned by the Web Risk API must not be redistributed. Always refer to the official documentation for usage restrictions.fixAdhere to the Web Risk API Terms of Service, specifically regarding data redistribution limitations.
affects: All
gotchaThe client library uses standard Python logging functionality, and logs may contain sensitive information. Access to these logs should be restricted.fixConfigure appropriate log handling and access controls for any stored logs to prevent exposure of sensitive data. Do not rely on log message immutability.
affects: All
Errors
Common errors & fixes
google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials. Please set GOOGLE_APPLICATION_CREDENTIALS or provide a Google Cloud project ID.
The application failed to find valid Google Cloud authentication credentials in the environment.
fixEnsure the `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to a valid service account key file, or use `gcloud auth application-default login` for local development. Alternatively, explicitly pass credentials to the client constructor.
404 Not Found: POST https://webrisk.googleapis.com/v1/projects/YOUR_PROJECT_ID/submissions:create: Method not found.
Attempted to use the `submit_uri` method without the project being allowlisted for Early Access, or incorrect API endpoint/version used.
fixVerify that your Google Cloud project has been allowlisted for the Web Risk Submission API. If not, only the `search_uris` method is generally available. Double-check the API endpoint and method signature in your code.
ImportError: cannot import name 'WebRiskServiceClient' from 'google.cloud.webrisk' (/path/to/python/site-packages/google/cloud/webrisk/__init__.py)
Attempted to import `WebRiskServiceClient` directly from `google.cloud.webrisk` instead of the versioned submodule `google.cloud.webrisk_v1`.
fixChange your import statement to `from google.cloud.webrisk_v1 import WebRiskServiceClient`.
Upgrade
Version history
1.21.0latest on PyPI · released Mar 26, 2026
Audit
Dependencies
google-api-corerequiredProvides core Google API client functionality, including authentication, retries, and API calls.
proto-plusrequiredUsed for protobuf message serialization and deserialization.