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))
}
```
---