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. If you want a binary result instead of a confidence score, use the Lookup API.

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.
  • Only the SOCIAL_ENGINEERING threatType is supported for this API.
  • The allow_scan option determines whether Web Risk is allowed to scan the URL provided.
  • 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"

Request JSON body:

{
  "uri": "URL",
  "threatTypes": "SOCIAL_ENGINEERING",
  "allowScan": "true"
}

To send your request, choose one of these options:

curl

Save the request body in a file called request.json, and execute the following command:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
""https://webrisk.googleapis.com/v1eap1:evaluateUri""

PowerShell

Save the request body in a file called request.json, and execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri ""https://webrisk.googleapis.com/v1eap1:evaluateUri"" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "scores": [
    {
      "threatType": "SOCIAL_ENGINEERING",
      "confidenceLevel": "SAFE"
    }
  ]
}