{
    "openapi": "3.0.3",
    "info": {
        "title": "TRONG.PRO IP Intelligence & Geolocation API",
        "description": "High-speed IP intelligence, accurate geolocation, network ASN/ISP details, and technical network attributes with Hybrid multi-source telemetry.\n\nDesigned for AI Agents (OpenAI GPTs, Anthropic Claude Tools, LangChain, Gemini, AutoGen) and automated systems.",
        "version": "1.0.0",
        "contact": {
            "name": "TRONG.PRO Support",
            "url": "https://ip.trong.pro"
        },
        "license": {
            "name": "MaxMind CC BY-SA 4.0 / Proprietary",
            "url": "https://ip.trong.pro/terms"
        }
    },
    "servers": [
        {
            "url": "https://ip.trong.pro",
            "description": "Current Environment Server"
        },
        {
            "url": "https://ip.trong.pro",
            "description": "Production Edge Server"
        }
    ],
    "paths": {
        "/api/ip": {
            "get": {
                "summary": "Get Client Public IP Address",
                "description": "Quickly retrieves the public IP address of the incoming client connection. Returns raw plain text by default, or JSON when requested. Ideal for lightweight scripts, IoT devices, and connection diagnostics.",
                "operationId": "getClientIP",
                "tags": [
                    "Client IP"
                ],
                "parameters": [
                    {
                        "name": "format",
                        "in": "query",
                        "description": "Desired output format. Options: text (raw IP string), json (JSON object {\"ip\":\"...\"}).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "text",
                                "json"
                            ],
                            "default": "text"
                        }
                    },
                    {
                        "name": "v",
                        "in": "query",
                        "description": "Force IPv4 unwrap (set to 4 to convert IPv4-mapped IPv6 address to pure IPv4).",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "enum": [
                                4
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful IP response",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "type": "string",
                                    "example": "118.69.141.62"
                                }
                            },
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ip": {
                                            "type": "string",
                                            "example": "118.69.141.62"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/json": {
            "get": {
                "summary": "Lookup Comprehensive IP Intelligence & Geolocation",
                "description": "Resolves full geolocation details (city, region, country, coordinates), network intelligence (ASN, ISP, domain, CIDR, reverse DNS), and binary/hex/int technical metrics. Supports querying caller's IP or any custom IPv4/IPv6 address. Features Hybrid multi-source telemetry for city-level accuracy in Vietnam and worldwide.",
                "operationId": "getIPDetails",
                "tags": [
                    "IP Intelligence"
                ],
                "parameters": [
                    {
                        "name": "ip",
                        "in": "query",
                        "description": "Target IPv4 or IPv6 address to analyze. If omitted or empty, the API inspects the caller's public IP address.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "118.69.141.62"
                        }
                    },
                    {
                        "name": "fields",
                        "in": "query",
                        "description": "Comma-separated list of specific fields to return (e.g. 'ip,city,country,asn,domain,latitude,longitude'). Omits unneeded fields to save bandwidth.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "ip,city,region,country,asn,domain,latitude,longitude"
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "description": "Output serialization format: 'json' (default) or 'ini' (standard INI configuration format).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "json",
                                "ini"
                            ],
                            "default": "json"
                        }
                    },
                    {
                        "name": "callback",
                        "in": "query",
                        "description": "JSONP callback function name for cross-origin browser scripts.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Comprehensive IP intelligence response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/IPDetails"
                                }
                            },
                            "text/plain": {
                                "schema": {
                                    "type": "string",
                                    "description": "Rendered when format=ini is requested."
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid IP address provided",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "invalid_ip"
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "\"invalid_ip\" is not a valid IP address."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (120 requests/minute for API)"
                    }
                }
            }
        },
        "/api/ini": {
            "get": {
                "summary": "Export IP Information as INI Configuration",
                "description": "Convenience alias for '/api/json?format=ini'. Returns IP intelligence formatted as standard INI sections ([ip], [location], [network], [technical]), directly parseable by Python configparser, PHP parse_ini_string, C#, etc.",
                "operationId": "getIPIni",
                "tags": [
                    "Configuration Export"
                ],
                "parameters": [
                    {
                        "name": "ip",
                        "in": "query",
                        "description": "Target IPv4 or IPv6 address. Defaults to caller IP if omitted.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "INI formatted text configuration",
                        "content": {
                            "text/plain": {
                                "schema": {
                                    "type": "string",
                                    "example": "[ip]\nip = \"118.69.141.62\"\nversion = 4\n\n[location]\ncity = \"Haiphong\"\nregion = \"Hai Phong\"\ncountry = \"Vietnam\"\nlatitude = 20.8648\nlongitude = 106.6834\n\n[network]\nasn = \"AS18403\"\norg = \"FPT Telecom Company\"\ndomain = \"fpt.vn\""
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/openapi.json": {
            "get": {
                "summary": "OpenAPI 3.0 Specification (This Document)",
                "description": "Returns the machine-readable OpenAPI 3.0 specification for AI agents, Swagger UI, and developer tool chains.",
                "operationId": "getOpenAPISpec",
                "tags": [
                    "Documentation & AI"
                ],
                "responses": {
                    "200": {
                        "description": "OpenAPI 3.0 specification JSON",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "IPDetails": {
                "type": "object",
                "description": "Full IP Intelligence details object",
                "properties": {
                    "ip": {
                        "type": "string",
                        "description": "Resolved IP address (IPv4 or IPv6)",
                        "example": "118.69.141.62"
                    },
                    "ip_version": {
                        "type": "integer",
                        "description": "IP protocol version: 4 or 6",
                        "example": 4
                    },
                    "is_private": {
                        "type": "boolean",
                        "description": "True if IP belongs to private/loopback/reserved address space (RFC 1918, RFC 4193)",
                        "example": false
                    },
                    "ip_int": {
                        "type": "string",
                        "description": "Integer numeric representation of IP",
                        "example": "1984269630"
                    },
                    "ip_hex": {
                        "type": "string",
                        "description": "Hexadecimal representation of IP",
                        "example": "0x76458D3E"
                    },
                    "ip_binary": {
                        "type": "string",
                        "description": "Dotted binary string representation",
                        "example": "01110110.01000101.10001101.00111110"
                    },
                    "hostname": {
                        "type": "string",
                        "nullable": true,
                        "description": "Reverse DNS (PTR record) hostname",
                        "example": "dns.google"
                    },
                    "asn": {
                        "type": "string",
                        "nullable": true,
                        "description": "Autonomous System Number (e.g. AS18403)",
                        "example": "AS18403"
                    },
                    "org": {
                        "type": "string",
                        "nullable": true,
                        "description": "Autonomous System Organization / ISP name",
                        "example": "FPT Telecom Company"
                    },
                    "domain": {
                        "type": "string",
                        "nullable": true,
                        "description": "Official network domain associated with ASN/ISP",
                        "example": "fpt.vn"
                    },
                    "network": {
                        "type": "string",
                        "nullable": true,
                        "description": "CIDR route prefix containing this IP",
                        "example": "118.69.0.0/16"
                    },
                    "city": {
                        "type": "string",
                        "nullable": true,
                        "description": "City name (refined via Hybrid multi-source telemetry)",
                        "example": "Haiphong"
                    },
                    "region": {
                        "type": "string",
                        "nullable": true,
                        "description": "Region, province, or state name",
                        "example": "Hai Phong"
                    },
                    "region_code": {
                        "type": "string",
                        "nullable": true,
                        "description": "ISO subdivision code",
                        "example": "SG"
                    },
                    "country": {
                        "type": "string",
                        "nullable": true,
                        "description": "Full country name",
                        "example": "Vietnam"
                    },
                    "country_code": {
                        "type": "string",
                        "nullable": true,
                        "description": "ISO 3166-1 alpha-2 two-letter country code",
                        "example": "VN"
                    },
                    "continent": {
                        "type": "string",
                        "nullable": true,
                        "description": "Continent name",
                        "example": "Asia"
                    },
                    "continent_code": {
                        "type": "string",
                        "nullable": true,
                        "description": "Two-letter continent code",
                        "example": "AS"
                    },
                    "postal": {
                        "type": "string",
                        "nullable": true,
                        "description": "Postal / ZIP code",
                        "example": "04000"
                    },
                    "latitude": {
                        "type": "number",
                        "format": "float",
                        "nullable": true,
                        "description": "Estimated latitude coordinate",
                        "example": 20.8648
                    },
                    "longitude": {
                        "type": "number",
                        "format": "float",
                        "nullable": true,
                        "description": "Estimated longitude coordinate",
                        "example": 106.6834
                    },
                    "timezone": {
                        "type": "string",
                        "nullable": true,
                        "description": "IANA timezone identifier",
                        "example": "Asia/Bangkok"
                    },
                    "accuracy_radius": {
                        "type": "integer",
                        "nullable": true,
                        "description": "Approximate accuracy radius in kilometers",
                        "example": 5
                    },
                    "geo_source": {
                        "type": "string",
                        "description": "Engine source providing the geolocation data (e.g. hybrid_cache, hybrid_live, offline_geolite2)",
                        "example": "hybrid_cache (ipinfo.io)"
                    },
                    "db_city_build": {
                        "type": "string",
                        "nullable": true,
                        "description": "Build release date of City database",
                        "example": "2026-10-20"
                    },
                    "db_asn_build": {
                        "type": "string",
                        "nullable": true,
                        "description": "Build release date of ASN database",
                        "example": "2024-07-29"
                    },
                    "query_time_ms": {
                        "type": "number",
                        "description": "Execution and lookup processing time in milliseconds",
                        "example": 5.18
                    }
                }
            }
        }
    }
}