Response Types

TypeScript interfaces and type definitions for IPSwamp API responses.

IPDetails

Threat intelligence information for an IP address.

interface IPDetails {
	/** Threat score ranging from 0-10 (higher values indicate greater threat) */
	score: number;

	/** The queried IP address */
	ip: string;

	/** ISO 8601 timestamp of the last detected attack from this IP */
	last_attack: string;

	ip_rep: string;

	/** Total number of malicious hits recorded for this IP */
	total_hits: number;

	/** Whitelist information if the IP is whitelisted, null otherwise */
	whitelist?: {
		value?: string;
		description?: string;
		note?: string;
		reason?: string;
		range?: string;
		ip?: string;
	} | null;
}

Usage Example

const response = await fetch("https://ipswamp.com/api/v1/checkIP?ip=8.8.8.8", {
	headers: { Authorization: `Bearer ${apiKey}` },
});

const data = await response.json();
const details: IPDetails = data.details;

if (details.score > 70) {
	console.log(`High threat detected: ${details.ip_rep}`);
}

---

IPInfo

Extended geographic and network information for an IP address. Only included when detailed=true.

interface IPInfo {
	/** The IP address */
	ip: string;

	/** Autonomous System Number (e.g., "AS15169") */
	asn?: string;

	/** Name of the AS organization (e.g., "Google LLC") */
	as_name?: string;

	/** Domain associated with the AS */
	as_domain?: string;

	/** ISO 3166-1 alpha-2 country code (e.g., "US", "DE", "JP") */
	country_code?: string;

	/** Full country name */
	country?: string;

	/** Two-letter continent code (e.g., "NA", "EU", "AS") */
	continent_code?: string;

	/** Full continent name */
	continent?: string;

	/** Internet Service Provider name */
	isp?: string;
}

Usage Example

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

const data = await response.json();
const ipInfo: IPInfo = data.ipInfo;

console.log(`Country: ${ipInfo.country} (${ipInfo.country_code})`);
console.log(`ISP: ${ipInfo.isp}`);
console.log(`ASN: ${ipInfo.asn} - ${ipInfo.as_name}`);

---

ApiKeyInfo

Information about an API key returned by the test-key endpoint.

interface ApiKeyInfo {
	/** Unique identifier for the API key */
	uid: string;

	/** User-defined name for the API key */
	name: string;

	/** Current number of API requests made in this billing period */
	current_usage: number;

	/** Maximum allowed API requests per billing period */
	max_api_requests: number;

	/** ISO 8601 timestamp when the API key was created */
	created_at: string;
}

Usage Example

const response = await fetch("https://ipswamp.com/api/v1/test-key", {
	headers: { Authorization: `Bearer ${apiKey}` },
});

const data = await response.json();
const keyInfo: ApiKeyInfo = data.api_key_info;

const usagePercent = (keyInfo.current_usage / keyInfo.max_api_requests) * 100;
console.log(`API Key: ${keyInfo.name}`);
console.log(
	`Usage: ${keyInfo.current_usage} / ${
		keyInfo.max_api_requests
	} (${usagePercent.toFixed(1)}%)`
);

---

CheckIPResponse

Complete response structure for the /checkIP endpoint.

interface CheckIPResponse {
	/** Response message */
	message: string;

	/** Human-readable description of the IP status */
	description: string;

	/** Detailed threat intelligence */
	details: IPDetails;

	/** Extended IP information (only present when detailed=true) */
	ipInfo?: IPInfo;
}

Usage Example

async function checkIP(
	ip: string,
	detailed: boolean = false
): Promise<CheckIPResponse> {
	const url = new URL("https://ipswamp.com/api/v1/checkIP");
	url.searchParams.set("ip", ip);
	if (detailed) url.searchParams.set("detailed", "true");

	const response = await fetch(url.toString(), {
		headers: { Authorization: `Bearer ${apiKey}` },
	});

	if (!response.ok) {
		throw new Error(`API error: ${response.status}`);
	}

	return response.json() as Promise<CheckIPResponse>;
}

// Usage
const result = await checkIP("8.8.8.8", true);
console.log(`Threat Score: ${result.details.score}`);
if (result.ipInfo) {
	console.log(`Location: ${result.ipInfo.country}`);
}

---

TestKeyResponse

Complete response structure for the /test-key endpoint.

interface TestKeyResponse {
	/** Whether the API key validation was successful */
	success: boolean;

	/** Validation status message */
	message: string;

	/** ISO 8601 timestamp of when the validation occurred */
	timestamp: string;

	/** Unique identifier for the organization */
	organization_id: string;

	/** Detailed information about the API key */
	api_key_info: ApiKeyInfo;
}

Usage Example

async function validateKey(): Promise<TestKeyResponse> {
	const response = await fetch("https://ipswamp.com/api/v1/test-key", {
		headers: { Authorization: `Bearer ${apiKey}` },
	});

	if (!response.ok) {
		throw new Error("Invalid API key");
	}

	return response.json() as Promise<TestKeyResponse>;
}

// Usage
const result = await validateKey();
if (result.success) {
	console.log(`✓ Validated: ${result.api_key_info.name}`);
	console.log(`Organization: ${result.organization_id}`);
}

---

ErrorResponse

Standard error response structure for all API endpoints.

interface ErrorResponse {
	/** Indicates this is an error response */
	error: true;

	/** HTTP status code */
	statusCode: number;

	/** Error message describing what went wrong */
	message: string;

	/** Optional additional error details */
	statusMessage?: string;
}

Usage Example

async function safeAPICall<T>(url: string): Promise<T> {
	const response = await fetch(url, {
		headers: { Authorization: `Bearer ${apiKey}` },
	});

	if (!response.ok) {
		const error: ErrorResponse = await response.json();
		throw new Error(`${error.statusCode}: ${error.message}`);
	}

	return response.json() as Promise<T>;
}

// Usage with error handling
try {
	const data = await safeAPICall<CheckIPResponse>(
		"https://ipswamp.com/api/v1/checkIP?ip=8.8.8.8"
	);
	console.log(data);
} catch (error) {
	console.error("API Error:", error.message);
}

---

Complete Type Definitions File

You can copy this complete TypeScript definitions file for your project:

// ipswamp-api.d.ts

export interface IPDetails {
	score: number;
	ip: string;
	last_attack: string;
	ip_rep: string;
	total_hits: number;
	whitelist?: {
		value?: string;
		description?: string;
		note?: string;
		reason?: string;
		range?: string;
		ip?: string;
	} | null;
}

export interface IPInfo {
	ip: string;
	asn?: string;
	as_name?: string;
	as_domain?: string;
	country_code?: string;
	country?: string;
	continent_code?: string;
	continent?: string;
	isp?: string;
}

export interface ApiKeyInfo {
	uid: string;
	name: string;
	current_usage: number;
	max_api_requests: number;
	created_at: string;
}

export interface CheckIPResponse {
	message: string;
	description: string;
	details: IPDetails;
	ipInfo?: IPInfo;
}

export interface TestKeyResponse {
	success: boolean;
	message: string;
	timestamp: string;
	organization_id: string;
	api_key_info: ApiKeyInfo;
}

export interface ErrorResponse {
	error: true;
	statusCode: number;
	message: string;
	statusMessage?: string;
}

See Also

• Check IP Endpoint - IP checking endpoint documentation
• Test Key Endpoint - API key validation endpoint
• Authentication - Authentication methods