{"openapi": "3.0.3", "info": {"title": "Waltsoft IPPulse IP Geolocation and Threat Intelligence API", "description": "Real-time IP geolocation and threat intelligence. Returns country, region, city, ASN, ISP, and a threat score (0-100) with flags for Tor exit nodes, VPNs, and datacenter ranges. Designed for security AI agents, fraud detection pipelines, and access-control automation. Billed at $0.005 per API call via AWS Marketplace.\n", "version": "1.0.0"}, "servers": [{"url": "https://ippulse.waltsoft.net/v1", "description": "IPPulse production endpoint"}], "paths": {"/lookup/{ip}": {"get": {"summary": "Look up geolocation and threat intelligence for a single IP", "description": "Returns full geolocation data (country, region, city, coordinates, ASN, org, ISP, hostname) plus a threat score (0-100) and boolean threat flags (Tor, VPN, datacenter) for the given IPv4 or IPv6 address.\n", "operationId": "lookupIp", "tags": ["Geolocation", "Threat Intelligence"], "parameters": [{"name": "ip", "in": "path", "required": true, "description": "IPv4 or IPv6 address to look up", "schema": {"type": "string", "example": "8.8.8.8"}}], "responses": {"200": {"description": "Geolocation and threat intelligence result", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IpLookupResult"}}}}, "400": {"description": "Bad request - invalid IP address format", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "401": {"description": "Unauthorized - invalid or missing API key", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "404": {"description": "IP address not found in database", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "429": {"description": "Rate limit exceeded", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "500": {"description": "Internal server error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}}}}, "/lookup/bulk": {"post": {"summary": "Bulk look up geolocation and threat intelligence for up to 50 IPs", "description": "Accepts a list of up to 50 IPv4 or IPv6 addresses and returns the same geolocation and threat intelligence fields as the single-IP endpoint for each address. Results are returned in the same order as the input list.\n", "operationId": "bulkLookupIps", "tags": ["Geolocation", "Threat Intelligence"], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["ips"], "properties": {"ips": {"type": "array", "description": "List of IPv4 or IPv6 addresses to look up (max 50)", "minItems": 1, "maxItems": 50, "items": {"type": "string"}, "example": ["8.8.8.8", "1.1.1.1", "104.21.0.1"]}}}}}}, "responses": {"200": {"description": "Bulk geolocation and threat intelligence results", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "description": "Results in the same order as the input IP list", "items": {"$ref": "#/components/schemas/IpLookupResult"}}}}}}}, "400": {"description": "Bad request - missing ips array, empty list, or list exceeds 50", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "401": {"description": "Unauthorized - invalid or missing API key", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "429": {"description": "Rate limit exceeded", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "500": {"description": "Internal server error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}}}}}, "components": {"schemas": {"IpLookupResult": {"type": "object", "properties": {"ip": {"type": "string", "description": "The queried IP address", "example": "8.8.8.8"}, "country": {"type": "string", "description": "Full country name", "example": "United States"}, "country_code": {"type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US"}, "region": {"type": "string", "description": "Region or state name", "example": "California"}, "city": {"type": "string", "description": "City name", "example": "Mountain View"}, "lat": {"type": "number", "format": "double", "description": "Latitude coordinate", "example": 37.3861}, "lon": {"type": "number", "format": "double", "description": "Longitude coordinate", "example": -122.0839}, "asn": {"type": "string", "description": "Autonomous System Number", "example": "AS15169"}, "org": {"type": "string", "description": "Organization name associated with the ASN", "example": "Google LLC"}, "isp": {"type": "string", "description": "Internet Service Provider name", "example": "Google"}, "hostname": {"type": "string", "description": "Reverse DNS hostname (empty string if none)", "example": "dns.google"}, "threat_flags": {"type": "array", "description": "List of active threat flags for this IP", "items": {"type": "string", "enum": ["tor", "vpn", "datacenter", "proxy", "spam", "botnet", "scanner", "abuser"]}, "example": []}, "threat_score": {"type": "number", "format": "integer", "minimum": 0, "maximum": 100, "description": "Composite threat score from 0 (clean) to 100 (high risk)", "example": 5}, "is_tor": {"type": "boolean", "description": "True if this IP is a known Tor exit node", "example": false}, "is_vpn": {"type": "boolean", "description": "True if this IP belongs to a known VPN provider", "example": false}, "is_datacenter": {"type": "boolean", "description": "True if this IP belongs to a cloud or datacenter range", "example": true}}}, "ErrorResponse": {"type": "object", "properties": {"error": {"type": "string", "description": "Machine-readable error code", "example": "invalid_ip"}, "message": {"type": "string", "description": "Human-readable error description", "example": "The provided IP address is not a valid IPv4 or IPv6 address."}}}}, "securitySchemes": {"ApiKeyAuth": {"type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key delivered via AWS Secrets Manager on Marketplace subscription"}}}, "security": [{"ApiKeyAuth": []}]}