Check IP Address

Retrieves threat intelligence and reputation details for a given IP address.

Endpoint

GET /api/v1/checkIP

Request

Headers

Header	Required	Description
Authorization	Yes*	Bearer <api-key>
X-API-Key	Yes*	Alternative to Authorization header

INFO

One of Authorization or X-API-Key is required.

Query Parameters

Parameter	Type	Required	Default	Description
ip	string	Yes	-	The IP address to check (IPv4 or IPv6)
detailed	string	No	"false"	Set to "true" for extended IP info (ASN, ISP, country, etc.)

Response

Success (200)

Returns threat intelligence data for the requested IP address.

Basic Response (detailed=false)

{
	"message": "IP found in database",
	"description": "This IP has been flagged as malicious",
	"details": {
		"score": 85,
		"ip": "192.168.1.1",
		"last_attack": "2025-12-10T12:00:00Z",
		"ip_rep": "malicious",
		"total_hits": 42,
		"whitelist": null,
		"whitelist_description": null,
		"whitelist_note": null,
		"whitelist_value": null
	}
}

Detailed Response (detailed=true)

When detailed=true, the response includes additional ipInfo field:

{
	"message": "IP found in database",
	"description": "This IP has been flagged as malicious",
	"details": {
		"score": 85,
		"ip": "192.168.1.1",
		"last_attack": "2025-12-10T12:00:00Z",
		"ip_rep": "malicious",
		"total_hits": 42,
		"whitelist": null,
		"whitelist_description": null,
		"whitelist_note": null,
		"whitelist_value": null
	},
	"ipInfo": {
		"ip": "192.168.1.1",
		"asn": "AS12345",
		"as_name": "Example ISP",
		"as_domain": "example.com",
		"country_code": "US",
		"country": "United States",
		"continent_code": "NA",
		"continent": "North America",
		"isp": "Example Internet Services"
	}
}

TIP

The ipInfo field is only included when detailed=true.

Response Fields

Details Object

Field	Type	Description
score	number	Threat score (0-100, higher is more dangerous)
ip	string	The queried IP address
last_attack	string	ISO timestamp of last detected attack
ip_rep	string	Reputation classification (malicious, suspicious, clean)
total_hits	number	Total number of malicious hits recorded
whitelist	object | null	Whitelist information if IP is whitelisted

IPInfo Object (when detailed=true)

Field	Type	Description
ip	string	The IP address
asn	string	Autonomous System Number
as_name	string	AS organization name
as_domain	string	AS domain
country_code	string	ISO country code (e.g., "US")
country	string	Full country name
continent_code	string	Continent code (e.g., "NA")
continent	string	Full continent name
isp	string	Internet Service Provider name

Error Responses

Status	Response	Description
400	{ "error": true, "statusCode": 400, "message": "IP address is required" }	Missing IP parameter
401	{ "error": true, "statusCode": 401, "message": "API key required..." }	No API key provided
403	{ "error": true, "statusCode": 403, "message": "Invalid API key" }	Invalid or expired API key
500	{ "error": true, "statusCode": 500, "message": "Failed to fetch IP details" }	Internal server error

Examples

Basic IP Check

curl -X GET "https://ipswamp.com/api/v1/checkIP?ip=8.8.8.8" \
  -H "Authorization: Bearer your-api-key-here"

Detailed IP Check

curl -X GET "https://ipswamp.com/api/v1/checkIP?ip=8.8.8.8&detailed=true" \
  -H "Authorization: Bearer your-api-key-here"

Using X-API-Key Header

curl -X GET "https://ipswamp.com/api/v1/checkIP?ip=1.1.1.1&detailed=true" \
  -H "X-API-Key: your-api-key-here"

JavaScript/TypeScript

const response = await fetch(
	"https://ipswamp.com/api/v1/checkIP?ip=8.8.8.8&detailed=true",
	{
		headers: {
			Authorization: "Bearer your-api-key-here",
		},
	}
);

const data = await response.json();
console.log(data);

Python

import requests

url = "https://ipswamp.com/api/v1/checkIP"
params = {
    "ip": "8.8.8.8",
    "detailed": "true"
}
headers = {
    "Authorization": "Bearer your-api-key-here"
}

response = requests.get(url, params=params, headers=headers)
data = response.json()
print(data)

Use Cases

• Security Monitoring: Check incoming connections against threat intelligence
• Access Control: Block or flag IPs with high threat scores
• Log Analysis: Enrich security logs with reputation data
• Incident Response: Investigate suspicious IP addresses
• Compliance: Maintain audit trails with geographic information

Rate Limiting

WARNING

Each API call increments your usage counter. Monitor your usage via the test-key endpoint.

See Authentication for more information about rate limits and usage.