Using the Evaluate API
The page explains how to use the Evaluate API to let your client applications evaluate the maliciousness of a URL. This API returns a confidence score that indicates the maliciousness of a URL based on blocklists, machine learning models and heuristic rules. If you want a binary result instead of a confidence score, use the Lookup API.
Note: Any URLs submitted to the Evaluate API may undergo additional processing, including crawls.
Before you begin
Contact our sales team or your customer engineer to obtain access to this feature.
Evaluating URLs
To evaluate a URL, send an HTTP POST
request to
the evaluateUri
method. Understand the following considerations when evaluating URLs:
- The Evaluate API supports one URL per request. If you want to check multiple URLs, send a separate request for each URL.
- The URL must be valid and doesn't need to be canonicalized. For more information, see RFC 2396.
- The Evaluate API supports three threatTypes: SOCIAL_ENGINEERING, MALWARE and UNWANTED_SOFTWARE.
- Deprecated. The
allow_scan
field was used to determine whether Web Risk is allowed to scan the URL provided. This functionality can no longer be disabled in the Evaluate API. See the Lookup and Update APIs for crawl-free options. - The HTTP
POST
response returns a confidence score for the specified threatType. The confidence score represents the confidence level indicating how risky the specified URL is.
API request
Before using any of the request data, make the following replacements:
URL: a URL that needs to be evaluated.HTTP method and URL:
POST https://webrisk.googleapis.com/v1eap1:evaluateUri?key=API_KEY
Request JSON body:
{ "uri": "URL", "threatTypes": ["SOCIAL_ENGINEERING", "MALWARE", "UNWANTED_SOFTWARE"] }
To send your request, choose one of these options:
curl
Save the request body in a file named request.json
,
and execute the following command:
curl -X POST \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://webrisk.googleapis.com/v1eap1:evaluateUri?key=API_KEY"
PowerShell
Save the request body in a file named request.json
,
and execute the following command:
$headers = @{ }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://webrisk.googleapis.com/v1eap1:evaluateUri?key=API_KEY" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "scores": [ { "threatType": "MALWARE", "confidenceLevel": "EXTREMELY_HIGH" }, { "threatType": "SOCIAL_ENGINEERING", "confidenceLevel": "SAFE" }, { "threatType": "UNWANTED_SOFTWARE", "confidenceLevel": "SAFE" } ] }