WhoisFreaks Docs

IP Reputation

Section: API Solutions

IP threat intelligence

4 endpoints. Requests need your API key unless noted otherwise. See Authentication.

IP Reputation Lookup

GET https://api.whoisfreaks.com/v1.0/security

Threat intel for IP: VPN, proxy, Tor, bots. 1 credit.

Parameters

Parameter In Required Type Default Description
ip query yes string    

Response (IpReputationResponse)

Field Type Description
ip string  
location IpLocation  
network IpSecurityNetwork  
asn IpSecurityAsn  
security IpSecurity  
IpLocation object | Field | Type | Description | |-------|------|-------------| | `continent_code` | string | | | `continent_name` | string | | | `country_code2` | string | | | `country_code3` | string | | | `country_name` | string | | | `country_name_official` | string | | | `country_capital` | string | | | `state_prov` | string | | | `state_code` | string | | | `district` | string | | | `city` | string | | | `locality` | string | | | `accuracy_radius` | string | | | `confidence` | string | | | `zipcode` | string | | | `latitude` | string | | | `longitude` | string | | | `is_eu` | boolean | | | `geoname_id` | string | | | `country_emoji` | string | |
IpSecurityNetwork object | Field | Type | Description | |-------|------|-------------| | `connection_type` | string | | | `route` | string | | | `is_anycast` | boolean | | | `is_cdn` | boolean | | | `cdn_provider_name` | string | |
IpSecurityAsn object | Field | Type | Description | |-------|------|-------------| | `as_number` | string | | | `organization` | string | | | `country` | string | | | `type` | string | | | `domain` | string | | | `date_allocated` | string | | | `rir` | string | |
IpSecurity object | Field | Type | Description | |-------|------|-------------| | `threat_score` | integer | | | `is_tor` | boolean | | | `is_proxy` | boolean | | | `proxy_provider_names` | array | | | `proxy_confidence_score` | integer | | | `proxy_last_seen` | string | | | `is_residential_proxy` | boolean | | | `is_vpn` | boolean | | | `vpn_provider_names` | array | | | `vpn_confidence_score` | integer | | | `vpn_last_seen` | string | | | `is_relay` | boolean | | | `relay_provider_name` | string | | | `is_anonymous` | boolean | | | `is_known_attacker` | boolean | | | `is_bot` | boolean | | | `is_spam` | boolean | | | `is_cloud_provider` | boolean | | | `cloud_provider_name` | string | | </details> **Usage**
Python ```python """IP Reputation Lookup: GET https://api.whoisfreaks.com/v1.0/security Run it with your API key in the environment: WHOISFREAKS_API_KEY=your_api_key python IpReputation.py """ import json import os import whoisfreaks config = whoisfreaks.Configuration() config.api_key["ApiKeyAuth"] = os.environ["WHOISFREAKS_API_KEY"] # set once for every request with whoisfreaks.ApiClient(config) as client: api = whoisfreaks.IPReputationApi(client) # ip_reputation parameters: # ip (str, required) result = api.ip_reputation("8.8.8.8") print(json.dumps(result.to_dict(), indent=2)) ```
TypeScript ```typescript // IP Reputation Lookup: GET https://api.whoisfreaks.com/v1.0/security // Run: WHOISFREAKS_API_KEY=your_api_key npx tsx IpReputation.ts import { Configuration, IPReputationApi, ResponseError } from "whoisfreaks"; // Set the API key once; the client adds it to every request. const config = new Configuration({ apiKey: process.env.WHOISFREAKS_API_KEY }); const api = new IPReputationApi(config); // ipReputation({ ip }) // ip (string, required) async function main(): Promise { const result = await api.ipReputation({ ip: "8.8.8.8" }); console.log(JSON.stringify(result, null, 2)); } main().catch(async (err: unknown) => { // API errors carry the HTTP response if (err instanceof ResponseError) { console.error(`HTTP ${err.response.status}: ${await err.response.text()}`); } else { console.error(err); } process.exitCode = 1; }); ``` </details>
Go ```go // Runnable example: IP Reputation Lookup (GET /v1.0/security) // Run it from the Getting Started module: save it as main.go, then `go run .` // Parameters for ipReputation (GET /v1.0/security): // - ip (string, required) package main import ( "context" "encoding/json" "fmt" "log" "os" whoisfreaks "github.com/WhoisFreaks/whoisfreaks-go" ) func main() { // Set the API key once on the context; every call made with ctx sends it. ctx := context.WithValue(context.Background(), whoisfreaks.ContextAPIKeys, map[string]whoisfreaks.APIKey{"ApiKeyAuth": {Key: os.Getenv("WHOISFREAKS_API_KEY")}}) client := whoisfreaks.NewAPIClient(whoisfreaks.NewConfiguration()) result, _, err := client.IPReputationAPI.IpReputation(ctx).Ip("8.8.8.8").Execute() if err != nil { log.Fatal(err) } out, _ := json.MarshalIndent(result, "", " ") fmt.Println(string(out)) } ```
--- ## Bulk IP Reputation `POST https://api.whoisfreaks.com/v1.0/security` Up to 100 IPs. **Parameters** None. The API key is set once on the client. **Request body** (`application/json`, model `BulkGeolocationRequest`) | Field | Type | Required | Description | |-------|------|----------|-------------| | `ips` | array | yes | Up to 100 items. | Example: `{"ips": ["8.8.8.8", "1.1.1.1"]}` **Response** (array of `IpReputationResponse`) | Field | Type | Description | |-------|------|-------------| | `ip` | string | | | `location` | IpLocation | | | `network` | IpSecurityNetwork | | | `asn` | IpSecurityAsn | | | `security` | IpSecurity | |
IpLocation object | Field | Type | Description | |-------|------|-------------| | `continent_code` | string | | | `continent_name` | string | | | `country_code2` | string | | | `country_code3` | string | | | `country_name` | string | | | `country_name_official` | string | | | `country_capital` | string | | | `state_prov` | string | | | `state_code` | string | | | `district` | string | | | `city` | string | | | `locality` | string | | | `accuracy_radius` | string | | | `confidence` | string | | | `zipcode` | string | | | `latitude` | string | | | `longitude` | string | | | `is_eu` | boolean | | | `geoname_id` | string | | | `country_emoji` | string | |
IpSecurityNetwork object | Field | Type | Description | |-------|------|-------------| | `connection_type` | string | | | `route` | string | | | `is_anycast` | boolean | | | `is_cdn` | boolean | | | `cdn_provider_name` | string | |
IpSecurityAsn object | Field | Type | Description | |-------|------|-------------| | `as_number` | string | | | `organization` | string | | | `country` | string | | | `type` | string | | | `domain` | string | | | `date_allocated` | string | | | `rir` | string | |
IpSecurity object | Field | Type | Description | |-------|------|-------------| | `threat_score` | integer | | | `is_tor` | boolean | | | `is_proxy` | boolean | | | `proxy_provider_names` | array | | | `proxy_confidence_score` | integer | | | `proxy_last_seen` | string | | | `is_residential_proxy` | boolean | | | `is_vpn` | boolean | | | `vpn_provider_names` | array | | | `vpn_confidence_score` | integer | | | `vpn_last_seen` | string | | | `is_relay` | boolean | | | `relay_provider_name` | string | | | `is_anonymous` | boolean | | | `is_known_attacker` | boolean | | | `is_bot` | boolean | | | `is_spam` | boolean | | | `is_cloud_provider` | boolean | | | `cloud_provider_name` | string | | </details> **Usage**
Python ```python """Bulk IP Reputation: POST https://api.whoisfreaks.com/v1.0/security Run it with your API key in the environment: WHOISFREAKS_API_KEY=your_api_key python BulkIpReputation.py """ import json import os import whoisfreaks config = whoisfreaks.Configuration() config.api_key["ApiKeyAuth"] = os.environ["WHOISFREAKS_API_KEY"] # set once for every request with whoisfreaks.ApiClient(config) as client: api = whoisfreaks.IPReputationApi(client) # bulk_ip_reputation parameters: # bulk_geolocation_request (BulkGeolocationRequest, required): request body body = whoisfreaks.BulkGeolocationRequest(ips=["8.8.8.8", "1.1.1.1"]) results = api.bulk_ip_reputation(body) print(json.dumps([item.to_dict() for item in results], indent=2)) ```
TypeScript ```typescript // Bulk IP Reputation: POST https://api.whoisfreaks.com/v1.0/security // Run: WHOISFREAKS_API_KEY=your_api_key npx tsx BulkIpReputation.ts import { Configuration, IPReputationApi, ResponseError, type BulkGeolocationRequest } from "whoisfreaks"; // Set the API key once; the client adds it to every request. const config = new Configuration({ apiKey: process.env.WHOISFREAKS_API_KEY }); const api = new IPReputationApi(config); // bulkIpReputation({ bulkGeolocationRequest }) // bulkGeolocationRequest (BulkGeolocationRequest, required): request body async function main(): Promise { const body: BulkGeolocationRequest = { ips: ["8.8.8.8", "1.1.1.1"] }; const results = await api.bulkIpReputation({ bulkGeolocationRequest: body }); console.log(JSON.stringify(results, null, 2)); } main().catch(async (err: unknown) => { // API errors carry the HTTP response if (err instanceof ResponseError) { console.error(`HTTP ${err.response.status}: ${await err.response.text()}`); } else { console.error(err); } process.exitCode = 1; }); ``` </details>
Go ```go // Runnable example: Bulk IP Reputation (POST /v1.0/security) // Run it from the Getting Started module: save it as main.go, then `go run .` // Parameters for bulkIpReputation (POST /v1.0/security): // - body: BulkGeolocationRequest (required): request body object package main import ( "context" "encoding/json" "fmt" "log" "os" whoisfreaks "github.com/WhoisFreaks/whoisfreaks-go" ) func main() { // Set the API key once on the context; every call made with ctx sends it. ctx := context.WithValue(context.Background(), whoisfreaks.ContextAPIKeys, map[string]whoisfreaks.APIKey{"ApiKeyAuth": {Key: os.Getenv("WHOISFREAKS_API_KEY")}}) client := whoisfreaks.NewAPIClient(whoisfreaks.NewConfiguration()) body := whoisfreaks.NewBulkGeolocationRequest([]string{"8.8.8.8", "1.1.1.1"}) result, _, err := client.IPReputationAPI.BulkIpReputation(ctx). BulkGeolocationRequest(*body).Execute() if err != nil { log.Fatal(err) } out, _ := json.MarshalIndent(result, "", " ") fmt.Println(string(out)) } ```
--- ## IP Reputation Lookup (v2.0) `GET https://api.whoisfreaks.com/v2.0/security` Same lookup as /v1.0/security on a restructured response. The ASN block moves to the top level as asn, network gains the announced route prefix with the anycast and CDN flags, and the security block uses the newer field names with the added VPN, relay, residential proxy, bot and corporate gateway signals. Note that asn_name, allocation_status, num_of_ipv4_routes, num_of_ipv6_routes and network.company are only in v1.0. 1 credit. **Parameters** | Parameter | In | Required | Type | Default | Description | |-----------|----|----------|------|---------|-------------| | `ip` | query | yes | string | | | **Response** (`IpReputationResponse`) | Field | Type | Description | |-------|------|-------------| | `ip` | string | | | `location` | IpLocation | | | `network` | IpSecurityNetwork | | | `asn` | IpSecurityAsn | | | `security` | IpSecurity | |
IpLocation object | Field | Type | Description | |-------|------|-------------| | `continent_code` | string | | | `continent_name` | string | | | `country_code2` | string | | | `country_code3` | string | | | `country_name` | string | | | `country_name_official` | string | | | `country_capital` | string | | | `state_prov` | string | | | `state_code` | string | | | `district` | string | | | `city` | string | | | `locality` | string | | | `accuracy_radius` | string | | | `confidence` | string | | | `zipcode` | string | | | `latitude` | string | | | `longitude` | string | | | `is_eu` | boolean | | | `geoname_id` | string | | | `country_emoji` | string | |
IpSecurityNetwork object | Field | Type | Description | |-------|------|-------------| | `connection_type` | string | | | `route` | string | | | `is_anycast` | boolean | | | `is_cdn` | boolean | | | `cdn_provider_name` | string | |
IpSecurityAsn object | Field | Type | Description | |-------|------|-------------| | `as_number` | string | | | `organization` | string | | | `country` | string | | | `type` | string | | | `domain` | string | | | `date_allocated` | string | | | `rir` | string | |
IpSecurity object | Field | Type | Description | |-------|------|-------------| | `threat_score` | integer | | | `is_tor` | boolean | | | `is_proxy` | boolean | | | `proxy_provider_names` | array | | | `proxy_confidence_score` | integer | | | `proxy_last_seen` | string | | | `is_residential_proxy` | boolean | | | `is_vpn` | boolean | | | `vpn_provider_names` | array | | | `vpn_confidence_score` | integer | | | `vpn_last_seen` | string | | | `is_relay` | boolean | | | `relay_provider_name` | string | | | `is_anonymous` | boolean | | | `is_known_attacker` | boolean | | | `is_bot` | boolean | | | `is_spam` | boolean | | | `is_cloud_provider` | boolean | | | `cloud_provider_name` | string | | </details> **Usage**
Python ```python """IP Reputation Lookup (v2.0): GET https://api.whoisfreaks.com/v2.0/security Run it with your API key in the environment: WHOISFREAKS_API_KEY=your_api_key python IpReputationV2.py """ import json import os import whoisfreaks config = whoisfreaks.Configuration() config.api_key["ApiKeyAuth"] = os.environ["WHOISFREAKS_API_KEY"] # set once for every request with whoisfreaks.ApiClient(config) as client: api = whoisfreaks.IPReputationApi(client) # ip_reputation_v2 parameters: # ip (str, required) result = api.ip_reputation_v2("8.8.8.8") print(json.dumps(result.to_dict(), indent=2)) ```
TypeScript ```typescript // IP Reputation Lookup (v2.0): GET https://api.whoisfreaks.com/v2.0/security // Run: WHOISFREAKS_API_KEY=your_api_key npx tsx IpReputationV2.ts import { Configuration, IPReputationApi, ResponseError } from "whoisfreaks"; // Set the API key once; the client adds it to every request. const config = new Configuration({ apiKey: process.env.WHOISFREAKS_API_KEY }); const api = new IPReputationApi(config); // ipReputationV2({ ip }) // ip (string, required) async function main(): Promise { const result = await api.ipReputationV2({ ip: "8.8.8.8" }); console.log(JSON.stringify(result, null, 2)); } main().catch(async (err: unknown) => { // API errors carry the HTTP response if (err instanceof ResponseError) { console.error(`HTTP ${err.response.status}: ${await err.response.text()}`); } else { console.error(err); } process.exitCode = 1; }); ``` </details>
Go ```go // Runnable example: IP Reputation Lookup (v2.0) (GET /v2.0/security) // Run it from the Getting Started module: save it as main.go, then `go run .` // Parameters for ipReputationV2 (GET /v2.0/security): // - ip (string, required) package main import ( "context" "encoding/json" "fmt" "log" "os" whoisfreaks "github.com/WhoisFreaks/whoisfreaks-go" ) func main() { // Set the API key once on the context; every call made with ctx sends it. ctx := context.WithValue(context.Background(), whoisfreaks.ContextAPIKeys, map[string]whoisfreaks.APIKey{"ApiKeyAuth": {Key: os.Getenv("WHOISFREAKS_API_KEY")}}) client := whoisfreaks.NewAPIClient(whoisfreaks.NewConfiguration()) result, _, err := client.IPReputationAPI.IpReputationV2(ctx).Ip("8.8.8.8").Execute() if err != nil { log.Fatal(err) } out, _ := json.MarshalIndent(result, "", " ") fmt.Println(string(out)) } ```
--- ## Bulk IP Reputation (v2.0) `POST https://api.whoisfreaks.com/v2.0/security` Up to 100 IPs, returning the same entry as GET /v2.0/security for each one. An invalid IP returns an error object for that entry only; the rest are still returned. 1 credit per IP. **Parameters** None. The API key is set once on the client. **Request body** (`application/json`, model `BulkGeolocationRequest`) | Field | Type | Required | Description | |-------|------|----------|-------------| | `ips` | array | yes | Up to 100 items. | Example: `{"ips": ["1.1.1.1", "2.2.2.2", "8.8.8.8"]}` **Response** (array of `IpReputationResponse`) | Field | Type | Description | |-------|------|-------------| | `ip` | string | | | `location` | IpLocation | | | `network` | IpSecurityNetwork | | | `asn` | IpSecurityAsn | | | `security` | IpSecurity | |
IpLocation object | Field | Type | Description | |-------|------|-------------| | `continent_code` | string | | | `continent_name` | string | | | `country_code2` | string | | | `country_code3` | string | | | `country_name` | string | | | `country_name_official` | string | | | `country_capital` | string | | | `state_prov` | string | | | `state_code` | string | | | `district` | string | | | `city` | string | | | `locality` | string | | | `accuracy_radius` | string | | | `confidence` | string | | | `zipcode` | string | | | `latitude` | string | | | `longitude` | string | | | `is_eu` | boolean | | | `geoname_id` | string | | | `country_emoji` | string | |
IpSecurityNetwork object | Field | Type | Description | |-------|------|-------------| | `connection_type` | string | | | `route` | string | | | `is_anycast` | boolean | | | `is_cdn` | boolean | | | `cdn_provider_name` | string | |
IpSecurityAsn object | Field | Type | Description | |-------|------|-------------| | `as_number` | string | | | `organization` | string | | | `country` | string | | | `type` | string | | | `domain` | string | | | `date_allocated` | string | | | `rir` | string | |
IpSecurity object | Field | Type | Description | |-------|------|-------------| | `threat_score` | integer | | | `is_tor` | boolean | | | `is_proxy` | boolean | | | `proxy_provider_names` | array | | | `proxy_confidence_score` | integer | | | `proxy_last_seen` | string | | | `is_residential_proxy` | boolean | | | `is_vpn` | boolean | | | `vpn_provider_names` | array | | | `vpn_confidence_score` | integer | | | `vpn_last_seen` | string | | | `is_relay` | boolean | | | `relay_provider_name` | string | | | `is_anonymous` | boolean | | | `is_known_attacker` | boolean | | | `is_bot` | boolean | | | `is_spam` | boolean | | | `is_cloud_provider` | boolean | | | `cloud_provider_name` | string | | </details> **Usage**
Python ```python """Bulk IP Reputation (v2.0): POST https://api.whoisfreaks.com/v2.0/security Run it with your API key in the environment: WHOISFREAKS_API_KEY=your_api_key python BulkIpReputationV2.py """ import json import os import whoisfreaks config = whoisfreaks.Configuration() config.api_key["ApiKeyAuth"] = os.environ["WHOISFREAKS_API_KEY"] # set once for every request with whoisfreaks.ApiClient(config) as client: api = whoisfreaks.IPReputationApi(client) # bulk_ip_reputation_v2 parameters: # bulk_geolocation_request (BulkGeolocationRequest, required): request body body = whoisfreaks.BulkGeolocationRequest(ips=["1.1.1.1", "2.2.2.2", "8.8.8.8"]) results = api.bulk_ip_reputation_v2(body) print(json.dumps([item.to_dict() for item in results], indent=2)) ```
TypeScript ```typescript // Bulk IP Reputation (v2.0): POST https://api.whoisfreaks.com/v2.0/security // Run: WHOISFREAKS_API_KEY=your_api_key npx tsx BulkIpReputationV2.ts import { Configuration, IPReputationApi, ResponseError, type BulkGeolocationRequest } from "whoisfreaks"; // Set the API key once; the client adds it to every request. const config = new Configuration({ apiKey: process.env.WHOISFREAKS_API_KEY }); const api = new IPReputationApi(config); // bulkIpReputationV2({ bulkGeolocationRequest }) // bulkGeolocationRequest (BulkGeolocationRequest, required): request body async function main(): Promise { const body: BulkGeolocationRequest = { ips: ["1.1.1.1", "2.2.2.2", "8.8.8.8"] }; const results = await api.bulkIpReputationV2({ bulkGeolocationRequest: body }); console.log(JSON.stringify(results, null, 2)); } main().catch(async (err: unknown) => { // API errors carry the HTTP response if (err instanceof ResponseError) { console.error(`HTTP ${err.response.status}: ${await err.response.text()}`); } else { console.error(err); } process.exitCode = 1; }); ``` </details>
Go ```go // Runnable example: Bulk IP Reputation (v2.0) (POST /v2.0/security) // Run it from the Getting Started module: save it as main.go, then `go run .` // Parameters for bulkIpReputationV2 (POST /v2.0/security): // - body: BulkGeolocationRequest (required): request body object package main import ( "context" "encoding/json" "fmt" "log" "os" whoisfreaks "github.com/WhoisFreaks/whoisfreaks-go" ) func main() { // Set the API key once on the context; every call made with ctx sends it. ctx := context.WithValue(context.Background(), whoisfreaks.ContextAPIKeys, map[string]whoisfreaks.APIKey{"ApiKeyAuth": {Key: os.Getenv("WHOISFREAKS_API_KEY")}}) client := whoisfreaks.NewAPIClient(whoisfreaks.NewConfiguration()) body := whoisfreaks.NewBulkGeolocationRequest([]string{"1.1.1.1", "2.2.2.2", "8.8.8.8"}) result, _, err := client.IPReputationAPI.BulkIpReputationV2(ctx). BulkGeolocationRequest(*body).Execute() if err != nil { log.Fatal(err) } out, _ := json.MarshalIndent(result, "", " ") fmt.Println(string(out)) } ```
---