Using the Lookup API
Overview
The Lookup API lets your client applications check if a URL is included on any of the Web Risk lists.
Checking URLs
To check if a URL is on a Web Risk list, send an HTTP GET
request to
the uris.search
method:
- The Lookup API supports one URL per request. To check multiple URLs, you need to send a separate request for each URL.
You can specify multiple threat types in a single request by repeating the
threatTypes
field. For example:&threatTypes=SOCIAL_ENGINEERING&threatTypes=MALWARE
The URL must be valid (see RFC 2396) but it doesn't need to be canonicalized.
If you use the REST API, you must encode
GET
parameters, like the URI.The HTTP
GET
response returns the matching threat types, if any, along with the cache expiration.
Example: uris.search
HTTP method and URL:
GET https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY
To send your request, choose one of these options:
curl
Execute the following command:
curl -X GET \
"https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY"
PowerShell
Execute the following command:
$headers = @{ }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{ "threat": { "threatTypes": [ "MALWARE" ], "expireTime": "2019-07-17T15:01:23.045123456Z" } }
Java
Python
If no results match your request, you will get an empty JSON response of {}
.
This means that the URL you provided isn't on any threat lists.
Cache durations
The expireTime
field indicates the timestamp at which the match should be
considered expired. For details, see Caching.
What's next?
Learn about Using the Update API.