google-transparency-report

TypeScript client for the Google Transparency Report Safe Browsing status endpoint.

Install

npm install google-transparency-report

Usage

import { getSafeBrowsingStatus } from "google-transparency-report";

const result = await getSafeBrowsingStatus("google.com");
console.log(result);

getSafeBrowsingStatus(site) returns null when there is no data, or:

{
  status: "no_unsafe_content" | "unsafe" | "some_unsafe" | "too_large" | "hosts_uncommon_downloads" | "no_data" | "unknown",
  status_description: string,
  is_safe: boolean,
  flag_harmful_redirects: boolean,
  flag_installs_malicious_software: boolean,
  flag_phishing: boolean,
  flag_hosts_malicious_software: boolean,
  flag_uncommon_downloads: boolean,
  last_updated_ms: number,
  site: string
}

Google API details

Endpoint (undocumented):

GET https://transparencyreport.google.com/transparencyreport/api/v3/safebrowsing/status?site=example.com

The server responds with an XSSI prefix line ()]}') followed by JSON. The JSON is an array, typically with a single row shaped like:

[
  [
    "sb.ssr",
    1,                 // status_code
    false,             // harmful redirects
    false,             // installs malicious/unwanted software
    false,             // phishing / social engineering
    false,             // hosts malicious/unwanted software
    false,             // uncommon downloads
    1769421466644,     // last updated (ms since epoch)
    "example.com"      // scanned site
  ]
]

Status code meaning:

• 1: No unsafe content found
• 2: This site is unsafe
• 3: Some pages on this site are unsafe
• 4: Large site with mixed content
• 5: Hosts files not commonly downloaded
• 6: No available data

Notes

• This endpoint is undocumented (see community notes here).
• This module was built in response to Jesse Jacob Nickles harassing many domains and falsely reporting them as malware and phishing sites.
• Unfortunately VirusTotal does not ingest Google Transparency Report data, so a reliable API client helps access this information.