{
    "openapi": "3.0.3",
    "info": {
        "title": "Ip2Geo Convert IP API",
        "version": "1.0.0",
        "description": "Lookup single IP address and get geolocation data."
    },
    "servers": [
        {
            "url": "https://api.ip2geo.dev",
            "description": "Production Server"
        }
    ],
    "paths": {
        "/convert": {
            "get": {
                "summary": "Ip2Geo - Convert IP",
                "parameters": [
                    {
                        "name": "ip",
                        "in": "query",
                        "description": "IPv4 or IPv6 address to lookup.",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful geolocation lookup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SingleConvertResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Plan conversion limit reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "security": [{ "ApiKeyAuth": [] }]
            },
            "post": {
                "summary": "Ip2Geo - Bulk Convert IPs",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "ips": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Array of IPv4 or IPv6 addresses to lookup.",
                                        "maxItems": 5000
                                    }
                                },
                                "required": ["ips"]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful geolocation lookup.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/MultipleConvertResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Plan conversion limit reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "security": [{ "ApiKeyAuth": [] }]
            }
        },
        "/conversions/get": {
            "get": {
                "summary": "Ip2Geo - Get Conversion",
                "description": "Retrieve a single conversion by its ID.",
                "parameters": [
                    {
                        "name": "conversionId",
                        "in": "query",
                        "description": "The unique identifier of the conversion to retrieve.",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    },
                    {
                        "name": "select",
                        "in": "query",
                        "description": "Select specific data fields to return. If not specified, all data fields are returned. See [SELECT Constants](/constants/select) for all available fields.",
                        "required": false,
                        "style": "form",
                        "explode": false,
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Conversion retrieved successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GetConversionResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request - missing conversion ID!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Plan conversion limit reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Conversion not found!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "security": [{ "ApiKeyAuth": [] }]
            },
            "post": {
                "summary": "Ip2Geo - Get Conversions",
                "description": "Retrieve multiple conversions by their IDs.",
                "parameters": [
                    {
                        "name": "select",
                        "in": "query",
                        "description": "Select specific data fields to return. If not specified, all data fields are returned. See [SELECT Constants](/constants/select) for all available fields.",
                        "required": false,
                        "style": "form",
                        "explode": false,
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "conversionIds": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "uuid"
                                        },
                                        "description": "Array of conversion IDs to retrieve.",
                                        "maxItems": 100
                                    }
                                },
                                "required": ["conversionIds"]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Conversions retrieved successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GetConversionsResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request - missing or invalid conversion IDs!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Plan conversion limit reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "security": [{ "ApiKeyAuth": [] }]
            }
        },
        "/conversions/list": {
            "get": {
                "summary": "Ip2Geo - List Conversions",
                "description": "List conversions with pagination and optional filtering.",
                "parameters": [
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Number of conversions to skip for pagination.",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 0
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Maximum number of conversions to return (max: 50).",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 50,
                            "maximum": 50
                        }
                    },
                    {
                        "name": "select",
                        "in": "query",
                        "description": "Select specific data fields to return. If not specified, all data fields are returned. See [SELECT Constants](/constants/select) for all available fields.",
                        "required": false,
                        "style": "form",
                        "explode": false,
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    },
                    {
                        "name": "ipSearch",
                        "in": "query",
                        "description": "Filter conversions by IP address.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Conversions listed successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ListConversionsResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthorized!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Plan conversion limit reached.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal server error!",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                },
                "security": [{ "ApiKeyAuth": [] }]
            }
        }
    },
    "components": {
        "schemas": {
            "Ip": {
                "type": "object",
                "properties": {
                    "ip": {
                        "type": "string",
                        "nullable": true,
                        "description": "The IP address."
                    },
                    "type": {
                        "type": "string",
                        "enum": ["ipv4", "ipv6"],
                        "nullable": true,
                        "description": "IP address type."
                    },
                    "is_eu": {
                        "type": "boolean",
                        "nullable": true,
                        "description": "Whether the IP is located in the European Union."
                    },
                    "continent": {
                        "type": "object",
                        "nullable": true,
                        "properties": {
                            "name": {
                                "type": "string",
                                "nullable": true
                            },
                            "code": {
                                "type": "string",
                                "nullable": true
                            },
                            "geoname_id": {
                                "type": "integer",
                                "nullable": true,
                                "description": "GeoNames ID for the continent."
                            },
                            "country": {
                                "type": "object",
                                "nullable": true,
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "code": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "geoname_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "description": "GeoNames ID for the country."
                                    },
                                    "phone_code": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "capital": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "tld": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "subdivision": {
                                        "type": "object",
                                        "nullable": true,
                                        "description": "State, province, or region information.",
                                        "properties": {
                                            "name": {
                                                "type": "string",
                                                "nullable": true,
                                                "description": "Name of the state/province/region."
                                            },
                                            "code": {
                                                "type": "string",
                                                "nullable": true,
                                                "description": "ISO code for the subdivision (e.g., 'CA' for California)."
                                            }
                                        }
                                    },
                                    "city": {
                                        "type": "object",
                                        "nullable": true,
                                        "properties": {
                                            "name": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "geoname_id": {
                                                "type": "integer",
                                                "nullable": true,
                                                "description": "GeoNames ID for the city."
                                            },
                                            "latitude": {
                                                "type": "number",
                                                "nullable": true
                                            },
                                            "longitude": {
                                                "type": "number",
                                                "nullable": true
                                            },
                                            "accuracy_radius": {
                                                "type": "integer",
                                                "nullable": true,
                                                "description": "Radius in kilometers around the coordinates where the IP is likely located."
                                            },
                                            "metro_code": {
                                                "type": "integer",
                                                "nullable": true,
                                                "description": "Metro area code (US only)."
                                            },
                                            "postal_code": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "timezone": {
                                                "type": "object",
                                                "nullable": true,
                                                "properties": {
                                                    "name": {
                                                        "type": "string",
                                                        "nullable": true
                                                    },
                                                    "time_now": {
                                                        "type": "string",
                                                        "nullable": true
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "flag": {
                                        "type": "object",
                                        "nullable": true,
                                        "properties": {
                                            "img": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "emoji": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "emoji_unicode": {
                                                "type": "string",
                                                "nullable": true
                                            }
                                        }
                                    },
                                    "currency": {
                                        "type": "object",
                                        "nullable": true,
                                        "properties": {
                                            "name": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "code": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "symbol": {
                                                "type": "string",
                                                "nullable": true
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "registered_country": {
                        "type": "object",
                        "nullable": true,
                        "description": "The country where the IP address is registered (may differ from location country for VPNs, proxies, etc.).",
                        "properties": {
                            "name": {
                                "type": "string",
                                "nullable": true,
                                "description": "Name of the registered country."
                            },
                            "code": {
                                "type": "string",
                                "nullable": true,
                                "description": "ISO country code of the registered country."
                            },
                            "geoname_id": {
                                "type": "integer",
                                "nullable": true,
                                "description": "GeoNames ID for the registered country."
                            }
                        }
                    },
                    "asn": {
                        "type": "object",
                        "nullable": true,
                        "properties": {
                            "number": {
                                "type": "integer",
                                "nullable": true
                            },
                            "name": {
                                "type": "string",
                                "nullable": true
                            }
                        }
                    },
                    "completion_time": {
                        "type": "object",
                        "nullable": true,
                        "properties": {
                            "miliseconds": {
                                "type": "number",
                                "nullable": true
                            },
                            "seconds": {
                                "type": "number",
                                "nullable": true
                            }
                        }
                    }
                }
            },
            "RequestMeta": {
                "type": "object",
                "properties": {
                    "reqId": {
                        "type": "string",
                        "description": "Unique request identifier."
                    },
                    "resTime": {
                        "type": "number",
                        "description": "Response time in milliseconds."
                    }
                },
                "required": ["reqId", "resTime"]
            },
            "SingleConvertResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "description": "Whether the request was successful."
                    },
                    "message": {
                        "type": "string",
                        "description": "Response message."
                    },
                    "code": {
                        "type": "integer",
                        "description": "HTTP status code."
                    },
                    "data": {
                        "$ref": "#/components/schemas/Ip"
                    },
                    "_req": {
                        "$ref": "#/components/schemas/RequestMeta"
                    }
                },
                "required": ["success", "message", "code", "_req"]
            },
            "MultipleConvertResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "description": "Whether the request was successful."
                    },
                    "message": {
                        "type": "string",
                        "description": "Response message."
                    },
                    "code": {
                        "type": "integer",
                        "description": "HTTP status code."
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "ip": {
                                    "type": "string",
                                    "description": "The IP address that was converted."
                                },
                                "conversion": {
                                    "nullable": true,
                                    "description": "Null when the address could not be converted.",
                                    "allOf": [{ "$ref": "#/components/schemas/Ip" }]
                                }
                            },
                            "required": ["ip"]
                        }
                    },
                    "_req": {
                        "$ref": "#/components/schemas/RequestMeta"
                    }
                },
                "required": ["success", "message", "code", "data", "_req"]
            },
            "ErrorResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": false
                    },
                    "message": {
                        "type": "string",
                        "description": "Error message."
                    },
                    "code": {
                        "type": "integer",
                        "description": "HTTP status code."
                    },
                    "data": {
                        "type": "object",
                        "nullable": true,
                        "description": "Null for most errors. Some validation errors return details here, such as the offending conversion ids."
                    },
                    "_req": {
                        "$ref": "#/components/schemas/RequestMeta"
                    }
                },
                "required": ["success", "message", "code", "_req"]
            },
            "Conversion": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "description": "Internal conversion ID"
                    },
                    "uniqueId": {
                        "type": "string",
                        "format": "uuid",
                        "description": "Unique identifier for the conversion."
                    },
                    "data": {
                        "$ref": "#/components/schemas/Ip"
                    },
                    "status": {
                        "type": "string",
                        "description": "Conversion status (success, failed, invalid-ip-address)."
                    },
                    "startedAt": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When the conversion started."
                    },
                    "completedAt": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true,
                        "description": "When the conversion completed."
                    },
                    "createdAt": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When the conversion was created."
                    }
                }
            },
            "GetConversionResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "description": "Whether the request was successful."
                    },
                    "message": {
                        "type": "string",
                        "description": "Response message."
                    },
                    "code": {
                        "type": "integer",
                        "description": "HTTP status code."
                    },
                    "data": {
                        "$ref": "#/components/schemas/Conversion"
                    },
                    "_req": {
                        "$ref": "#/components/schemas/RequestMeta"
                    }
                },
                "required": ["success", "message", "code", "_req"]
            },
            "GetConversionsResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "description": "Whether the request was successful."
                    },
                    "message": {
                        "type": "string",
                        "description": "Response message."
                    },
                    "code": {
                        "type": "integer",
                        "description": "HTTP status code."
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "conversions": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/Conversion"
                                },
                                "description": "Array of conversions."
                            }
                        }
                    },
                    "_req": {
                        "$ref": "#/components/schemas/RequestMeta"
                    }
                },
                "required": ["success", "message", "code", "_req"]
            },
            "ListConversionsResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "description": "Whether the request was successful."
                    },
                    "message": {
                        "type": "string",
                        "description": "Response message."
                    },
                    "code": {
                        "type": "integer",
                        "description": "HTTP status code."
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "conversions": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/Conversion"
                                },
                                "description": "Array of conversions."
                            },
                            "hasMore": {
                                "type": "boolean",
                                "description": "Whether there are more conversions to fetch."
                            },
                            "totalCount": {
                                "type": "integer",
                                "description": "Total number of conversions."
                            }
                        }
                    },
                    "_req": {
                        "$ref": "#/components/schemas/RequestMeta"
                    }
                },
                "required": ["success", "message", "code", "_req"]
            }
        },
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "x-api-key",
                "description": "Use your Ip2Geo secret key (`i2g_sk_...`) for server-side requests, or public key (`i2g_pk_...`) for client-side requests. Example: `x-api-key: i2g_sk_abc123`."
            }
        }
    }
}