Using the Evaluate API

Overview

The Evaluate API lets your client applications evaluate the maliciousness of a URL. This API differs from the Lookup API in that it returns a confidence score in the maliciousness of a URL instead of a binary result.

Before you begin

Please contact Sales or your Customer Engineer in order to obtain access to this feature.

Evaluating URLs

To evaluate a URL, send an HTTP POST request to the evaluateUri method:

  • The Evaluate API supports one URL per request. To check multiple URLs, you need to send a separate request for each URL.
  • Only the SOCIAL_ENGINEERING threatType is supported for this API.
  • The option allow_scan determines if Web Risk is allowed to scan the URL provided.
  • The URL must be valid (see RFC 2396) but it doesn't need to be canonicalized.
  • The HTTP POST response returns a score per threatType given representing the confidence level that the given URL is malicious.

Example: evaluateUri

HTTP method and URL:

POST "https://webrisk.googleapis.com/v1eap1:evaluateUri"

Request JSON body:

{
  "uri": "http://www.google.com",
  "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"
    }
  ]
}