{
  "openapi": "3.0.3",
  "info": {
    "title": "IP Geolocation",
    "description": "Geolocate any IP — country, city, coordinates, timezone — plus IP-to-IP distance. Fast, free GeoLite2 data.",
    "version": "1.0.0"
  },
  "components": {
    "schemas": {}
  },
  "paths": {
    "/lookup": {
      "get": {
        "summary": "Geolocate a single IP address",
        "tags": [
          "IP"
        ],
        "description": "Returns country, city, coordinates, timezone, and accuracy for an IPv4/IPv6 address.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "example": "8.8.8.8",
            "in": "query",
            "name": "ip",
            "required": true,
            "description": "IPv4 or IPv6 address"
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ip": {
                      "type": "string"
                    },
                    "found": {
                      "type": "boolean"
                    },
                    "country": {
                      "type": "string",
                      "nullable": true
                    },
                    "countryName": {
                      "type": "string",
                      "nullable": true
                    },
                    "region": {
                      "type": "string",
                      "nullable": true
                    },
                    "city": {
                      "type": "string",
                      "nullable": true
                    },
                    "latitude": {
                      "type": "number",
                      "nullable": true
                    },
                    "longitude": {
                      "type": "number",
                      "nullable": true
                    },
                    "timezone": {
                      "type": "string",
                      "nullable": true
                    },
                    "eu": {
                      "type": "boolean"
                    },
                    "accuracyRadiusKm": {
                      "type": "number",
                      "nullable": true
                    },
                    "range": {
                      "type": "array",
                      "nullable": true,
                      "items": {
                        "type": "number"
                      }
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Bad request",
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/batch": {
      "post": {
        "summary": "Geolocate up to 100 IP addresses",
        "tags": [
          "IP"
        ],
        "description": "Runs the lookup on each IP in the array (max 100).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ips"
                ],
                "properties": {
                  "ips": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 100
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "number"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ip": {
                            "type": "string"
                          },
                          "found": {
                            "type": "boolean"
                          },
                          "country": {
                            "type": "string",
                            "nullable": true
                          },
                          "countryName": {
                            "type": "string",
                            "nullable": true
                          },
                          "region": {
                            "type": "string",
                            "nullable": true
                          },
                          "city": {
                            "type": "string",
                            "nullable": true
                          },
                          "latitude": {
                            "type": "number",
                            "nullable": true
                          },
                          "longitude": {
                            "type": "number",
                            "nullable": true
                          },
                          "timezone": {
                            "type": "string",
                            "nullable": true
                          },
                          "eu": {
                            "type": "boolean"
                          },
                          "accuracyRadiusKm": {
                            "type": "number",
                            "nullable": true
                          },
                          "range": {
                            "type": "array",
                            "nullable": true,
                            "items": {
                              "type": "number"
                            }
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Bad request",
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/distance": {
      "get": {
        "summary": "Distance (km) between two IP addresses",
        "tags": [
          "IP"
        ],
        "description": "Geolocates both IPs and returns the great-circle distance between them.",
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "example": "8.8.8.8",
            "in": "query",
            "name": "ip1",
            "required": true
          },
          {
            "schema": {
              "type": "string"
            },
            "example": "1.1.1.1",
            "in": "query",
            "name": "ip2",
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ip1": {
                      "type": "string"
                    },
                    "ip2": {
                      "type": "string"
                    },
                    "location1": {
                      "type": "object",
                      "properties": {
                        "country": {
                          "type": "string",
                          "nullable": true
                        },
                        "city": {
                          "type": "string",
                          "nullable": true
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "longitude": {
                          "type": "number"
                        }
                      }
                    },
                    "location2": {
                      "type": "object",
                      "properties": {
                        "country": {
                          "type": "string",
                          "nullable": true
                        },
                        "city": {
                          "type": "string",
                          "nullable": true
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "longitude": {
                          "type": "number"
                        }
                      }
                    },
                    "distanceKm": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Bad request",
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://web-toolbox-api-production.up.railway.app/ip",
      "description": "Production"
    }
  ]
}