{
 "openapi": "3.1.0",
 "info": {
  "title": "IPOwl API",
  "version": "1.0.0",
  "summary": "IP address lookup: location, network and VPN, proxy, Tor and hosting detection.",
  "description": "Look up any IPv4 or IPv6 address, or the address making the request. The API needs no key and no sign-up, returns JSON, and allows cross-origin requests from any site.\n\nEach client may make 100 requests per minute. A client is one IPv4 address or one IPv6 /64 network."
 },
 "servers": [
  {
   "url": "https://ipowl.dev"
  }
 ],
 "externalDocs": {
  "description": "API documentation",
  "url": "https://ipowl.dev/docs"
 },
 "tags": [
  {
   "name": "Lookup",
   "description": "Look up one address, many addresses, or the caller."
  },
  {
   "name": "Reports",
   "description": "Tell the service about a wrong result."
  },
  {
   "name": "Status",
   "description": "Check that the service is running."
  }
 ],
 "paths": {
  "/json/{query}": {
   "get": {
    "operationId": "lookupAddress",
    "tags": [
     "Lookup"
    ],
    "summary": "Look up an address",
    "description": "Returns location, network and detection data for one IP address. A domain name is resolved first and the address it resolves to is looked up.",
    "parameters": [
     {
      "name": "query",
      "in": "path",
      "required": true,
      "description": "An IPv4 address, an IPv6 address or a domain name.",
      "schema": {
       "type": "string"
      },
      "examples": {
       "ipv4": {
        "value": "8.8.8.8"
       },
       "ipv6": {
        "value": "2606:4700:4700::1111"
       },
       "domain": {
        "value": "github.com"
       }
      }
     },
     {
      "$ref": "#/components/parameters/fields"
     },
     {
      "$ref": "#/components/parameters/lang"
     },
     {
      "$ref": "#/components/parameters/fast"
     },
     {
      "$ref": "#/components/parameters/callback"
     }
    ],
    "responses": {
     "200": {
      "description": "The lookup result. A lookup that cannot be answered also returns 200, with `status` set to `fail`.",
      "headers": {
       "X-Rl": {
        "description": "Requests left in the current one-minute window.",
        "schema": {
         "type": "integer"
        }
       },
       "X-Ttl": {
        "description": "Seconds until the window resets.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Limit": {
        "description": "Requests allowed per window.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Remaining": {
        "description": "Same value as `X-Rl`.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Reset": {
        "description": "Same value as `X-Ttl`.",
        "schema": {
         "type": "integer"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "oneOf": [
          {
           "$ref": "#/components/schemas/Lookup"
          },
          {
           "$ref": "#/components/schemas/LookupFailure"
          }
         ]
        },
        "example": {
         "query": "8.8.8.8",
         "status": "success",
         "country": "United States",
         "countryCode": "US",
         "regionName": "California",
         "city": "Mountain View",
         "lat": 37.422,
         "lon": -122.085,
         "timezone": "America/Los_Angeles",
         "isp": "Google LLC",
         "as": "AS15169 Google LLC",
         "mobile": false,
         "proxy": false,
         "hosting": true
        }
       }
      }
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     }
    }
   }
  },
  "/json": {
   "get": {
    "operationId": "lookupCaller",
    "tags": [
     "Lookup"
    ],
    "summary": "Look up the caller",
    "description": "Looks up the address the request came from. Call it from a browser to learn about your visitor.",
    "parameters": [
     {
      "$ref": "#/components/parameters/fields"
     },
     {
      "$ref": "#/components/parameters/lang"
     },
     {
      "$ref": "#/components/parameters/fast"
     },
     {
      "$ref": "#/components/parameters/callback"
     }
    ],
    "responses": {
     "200": {
      "description": "The lookup result. A lookup that cannot be answered also returns 200, with `status` set to `fail`.",
      "headers": {
       "X-Rl": {
        "description": "Requests left in the current one-minute window.",
        "schema": {
         "type": "integer"
        }
       },
       "X-Ttl": {
        "description": "Seconds until the window resets.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Limit": {
        "description": "Requests allowed per window.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Remaining": {
        "description": "Same value as `X-Rl`.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Reset": {
        "description": "Same value as `X-Ttl`.",
        "schema": {
         "type": "integer"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "oneOf": [
          {
           "$ref": "#/components/schemas/Lookup"
          },
          {
           "$ref": "#/components/schemas/LookupFailure"
          }
         ]
        },
        "example": {
         "query": "8.8.8.8",
         "status": "success",
         "country": "United States",
         "countryCode": "US",
         "regionName": "California",
         "city": "Mountain View",
         "lat": 37.422,
         "lon": -122.085,
         "timezone": "America/Los_Angeles",
         "isp": "Google LLC",
         "as": "AS15169 Google LLC",
         "mobile": false,
         "proxy": false,
         "hosting": true
        }
       }
      }
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     }
    }
   }
  },
  "/ip": {
   "get": {
    "operationId": "callerIp",
    "tags": [
     "Lookup"
    ],
    "summary": "Get the caller's IP address",
    "description": "Returns the address the request came from as plain text, followed by a newline.",
    "responses": {
     "200": {
      "description": "The address.",
      "headers": {
       "X-Rl": {
        "description": "Requests left in the current one-minute window.",
        "schema": {
         "type": "integer"
        }
       },
       "X-Ttl": {
        "description": "Seconds until the window resets.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Limit": {
        "description": "Requests allowed per window.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Remaining": {
        "description": "Same value as `X-Rl`.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Reset": {
        "description": "Same value as `X-Ttl`.",
        "schema": {
         "type": "integer"
        }
       }
      },
      "content": {
       "text/plain": {
        "schema": {
         "type": "string"
        },
        "example": "203.0.113.7\n"
       }
      }
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     }
    }
   }
  },
  "/batch": {
   "post": {
    "operationId": "lookupBatch",
    "tags": [
     "Lookup"
    ],
    "summary": "Look up many addresses",
    "description": "Looks up as many as 100 addresses in one request. Results come back in the same order. Each address counts as one request towards the rate limit. Batches are answered from memory, so `reverse`, `hostname`, `org` and `whois` are filled only when already cached, and domain names are not resolved.",
    "parameters": [
     {
      "$ref": "#/components/parameters/fields"
     },
     {
      "$ref": "#/components/parameters/lang"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "array",
        "maxItems": 100,
        "items": {
         "oneOf": [
          {
           "type": "string",
           "description": "An IP address."
          },
          {
           "$ref": "#/components/schemas/BatchItem"
          }
         ]
        }
       },
       "example": [
        "8.8.8.8",
        {
         "query": "24.48.0.1",
         "fields": "query,city,isp",
         "lang": "fr"
        }
       ]
      }
     }
    },
    "responses": {
     "200": {
      "description": "One result per item, in the order sent.",
      "headers": {
       "X-Rl": {
        "description": "Requests left in the current one-minute window.",
        "schema": {
         "type": "integer"
        }
       },
       "X-Ttl": {
        "description": "Seconds until the window resets.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Limit": {
        "description": "Requests allowed per window.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Remaining": {
        "description": "Same value as `X-Rl`.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Reset": {
        "description": "Same value as `X-Ttl`.",
        "schema": {
         "type": "integer"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "array",
         "items": {
          "oneOf": [
           {
            "$ref": "#/components/schemas/Lookup"
           },
           {
            "$ref": "#/components/schemas/LookupFailure"
           }
          ]
         }
        }
       }
      }
     },
     "400": {
      "description": "The body is not valid JSON, or not an array.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "422": {
      "description": "More than 100 items.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     }
    }
   }
  },
  "/report": {
   "post": {
    "operationId": "reportAddress",
    "tags": [
     "Reports"
    ],
    "summary": "Report a wrong result",
    "description": "Reports an address that was flagged wrongly, missed, or placed in the wrong location. A report that matches what the API already says is answered at once and not stored. Counts as 10 requests, and each client may send 50 reports per day.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/Report"
       },
       "example": {
        "ip": "203.0.113.7",
        "type": "vpn",
        "provider": "ExampleVPN"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Nothing to change: the API already says what the report claims.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReportResult"
        },
        "example": {
         "status": "success",
         "outcome": "already-detected",
         "message": "this address is already flagged as vpn"
        }
       }
      }
     },
     "201": {
      "description": "The report was stored.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReportResult"
        },
        "example": {
         "status": "success",
         "outcome": "queued",
         "id": "0b6f3f0e-6f43-4a6e-9a55-6f0f6c1f6f6e"
        }
       }
      }
     },
     "400": {
      "description": "A required field is missing or not valid.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     },
     "503": {
      "description": "The report queue is full.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/report/{id}": {
   "get": {
    "operationId": "reportStatus",
    "tags": [
     "Reports"
    ],
    "summary": "Check a report",
    "description": "Where a report stands: waiting for review, confirmed or rejected, and whether it is changing lookups now. Use the `id` that sending the report returned. Counts as one request.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "The `id` returned when the report was sent.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The report.",
      "headers": {
       "X-Rl": {
        "description": "Requests left in the current one-minute window.",
        "schema": {
         "type": "integer"
        }
       },
       "X-Ttl": {
        "description": "Seconds until the window resets.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Limit": {
        "description": "Requests allowed per window.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Remaining": {
        "description": "Same value as `X-Rl`.",
        "schema": {
         "type": "integer"
        }
       },
       "RateLimit-Reset": {
        "description": "Same value as `X-Ttl`.",
        "schema": {
         "type": "integer"
        }
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ReportStatus"
        }
       }
      }
     },
     "404": {
      "description": "No report has this id. Reports are deleted 180 days after they stop having an effect.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        },
        "example": {
         "status": "fail",
         "message": "no such report"
        }
       }
      }
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     }
    }
   }
  },
  "/healthz": {
   "get": {
    "operationId": "health",
    "tags": [
     "Status"
    ],
    "summary": "Check service status",
    "description": "Returns 200 while the service is running. Does not count towards the rate limit.",
    "responses": {
     "200": {
      "description": "The service is up.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "sources": {
           "type": "integer",
           "description": "Data sources in use."
          },
          "loaded": {
           "type": "integer",
           "description": "Data sources loaded so far."
          }
         }
        },
        "example": {
         "ok": true,
         "sources": 124,
         "loaded": 124
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "parameters": {
   "fields": {
    "name": "fields",
    "in": "query",
    "description": "Fields to return: a comma-separated list of names, or the numeric form. Without it, every field is returned.",
    "schema": {
     "type": "string"
    },
    "example": "query,country,city,proxy"
   },
   "lang": {
    "name": "lang",
    "in": "query",
    "description": "Language for `country`. Unknown values fall back to English.",
    "schema": {
     "type": "string",
     "enum": [
      "en",
      "de",
      "es",
      "pt-BR",
      "fr",
      "ja",
      "zh-CN",
      "ru"
     ],
     "default": "en"
    }
   },
   "fast": {
    "name": "fast",
    "in": "query",
    "description": "Set to `1` to answer from memory only, without live reverse DNS or registry queries. Without it, the API waits up to 300 ms for those answers; what has not arrived by then is left empty and is present on the next lookup of the address.",
    "schema": {
     "type": "string",
     "enum": [
      "1"
     ]
    }
   },
   "callback": {
    "name": "callback",
    "in": "query",
    "description": "Wrap the response in a call to this function (JSONP). Letters, digits, `_`, `$` and `.`, up to 64 characters.",
    "schema": {
     "type": "string",
     "pattern": "^[\\w$.]{1,64}$"
    }
   }
  },
  "responses": {
   "RateLimited": {
    "description": "Rate limit exceeded.",
    "headers": {
     "X-Rl": {
      "description": "Requests left in the current one-minute window.",
      "schema": {
       "type": "integer"
      }
     },
     "X-Ttl": {
      "description": "Seconds until the window resets.",
      "schema": {
       "type": "integer"
      }
     },
     "RateLimit-Limit": {
      "description": "Requests allowed per window.",
      "schema": {
       "type": "integer"
      }
     },
     "RateLimit-Remaining": {
      "description": "Same value as `X-Rl`.",
      "schema": {
       "type": "integer"
      }
     },
     "RateLimit-Reset": {
      "description": "Same value as `X-Ttl`.",
      "schema": {
       "type": "integer"
      }
     },
     "Retry-After": {
      "description": "Seconds to wait before the next request.",
      "schema": {
       "type": "integer"
      }
     }
    },
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/RateLimited"
      },
      "example": {
       "status": "fail",
       "message": "rate limit exceeded",
       "limit": 100,
       "retryAfter": 37
      }
     }
    }
   }
  },
  "schemas": {
   "Lookup": {
    "type": "object",
    "description": "A successful lookup. With a `fields` parameter only the requested fields are present.",
    "properties": {
     "query": {
      "type": "string",
      "description": "The IP address that was looked up.",
      "x-group": "Request",
      "x-bit": 8192,
      "examples": [
       "8.8.8.8"
      ]
     },
     "status": {
      "type": "string",
      "description": "`success` when the address was looked up, `fail` when it could not be.",
      "x-group": "Request",
      "x-bit": 16384,
      "examples": [
       "success"
      ],
      "enum": [
       "success",
       "fail"
      ]
     },
     "continent": {
      "type": "string",
      "description": "Continent name.",
      "x-group": "Location",
      "x-bit": 1048576,
      "examples": [
       "North America"
      ]
     },
     "continentCode": {
      "type": "string",
      "description": "Two-letter continent code.",
      "x-group": "Location",
      "x-bit": 2097152,
      "examples": [
       "NA"
      ]
     },
     "country": {
      "type": "string",
      "description": "Country name, in the language set by `lang`.",
      "x-group": "Location",
      "x-bit": 1,
      "examples": [
       "United States"
      ]
     },
     "countryCode": {
      "type": "string",
      "description": "Two-letter country code (ISO 3166-1 alpha-2).",
      "x-group": "Location",
      "x-bit": 2,
      "examples": [
       "US"
      ]
     },
     "region": {
      "type": "string",
      "description": "Region or state code (ISO 3166-2, without the country prefix).",
      "x-group": "Location",
      "x-bit": 4,
      "examples": [
       "CA"
      ]
     },
     "regionName": {
      "type": "string",
      "description": "Region or state name.",
      "x-group": "Location",
      "x-bit": 8,
      "examples": [
       "California"
      ]
     },
     "city": {
      "type": "string",
      "description": "City name.",
      "x-group": "Location",
      "x-bit": 16,
      "examples": [
       "Mountain View"
      ]
     },
     "district": {
      "type": "string",
      "description": "District within the city, when the location database names one. Usually empty.",
      "x-group": "Location",
      "x-bit": 524288,
      "examples": [
       ""
      ]
     },
     "zip": {
      "type": "string",
      "description": "Postal code closest to the centre of the city.",
      "x-group": "Location",
      "x-bit": 32,
      "examples": [
       "94043"
      ]
     },
     "lat": {
      "type": [
       "number",
       "null"
      ],
      "description": "Latitude of the centre of the city. `null` when the city is unknown.",
      "x-group": "Location",
      "x-bit": 64,
      "examples": [
       37.422
      ]
     },
     "lon": {
      "type": [
       "number",
       "null"
      ],
      "description": "Longitude of the centre of the city. `null` when the city is unknown.",
      "x-group": "Location",
      "x-bit": 128,
      "examples": [
       -122.085
      ]
     },
     "timezone": {
      "type": "string",
      "description": "IANA time zone name.",
      "x-group": "Location",
      "x-bit": 256,
      "examples": [
       "America/Los_Angeles"
      ]
     },
     "offset": {
      "type": [
       "integer",
       "null"
      ],
      "description": "Current UTC offset in seconds, including daylight saving time.",
      "x-group": "Location",
      "x-bit": 33554432,
      "examples": [
       -25200
      ]
     },
     "currency": {
      "type": "string",
      "description": "Currency of the country (ISO 4217).",
      "x-group": "Location",
      "x-bit": 8388608,
      "examples": [
       "USD"
      ]
     },
     "isp": {
      "type": "string",
      "description": "Name of the network that announces the address.",
      "x-group": "Network",
      "x-bit": 512,
      "examples": [
       "Google LLC"
      ]
     },
     "org": {
      "type": "string",
      "description": "Organisation the address block is registered to. Same as `isp` when the registry has no record.",
      "x-group": "Network",
      "x-bit": 1024,
      "examples": [
       "Google LLC"
      ]
     },
     "as": {
      "type": "string",
      "description": "AS number and network name, separated by a space. Empty when the address is not announced.",
      "x-group": "Network",
      "x-bit": 2048,
      "examples": [
       "AS15169 Google LLC"
      ]
     },
     "asname": {
      "type": "string",
      "description": "Short name of the AS from the registry.",
      "x-group": "Network",
      "x-bit": 4194304,
      "examples": [
       "GOOGLE"
      ]
     },
     "reverse": {
      "type": "string",
      "description": "Reverse DNS name of the address. Empty when it has none, or when `fast=1` is set and the name is not cached.",
      "x-group": "Network",
      "x-bit": 4096,
      "examples": [
       "dns.google"
      ]
     },
     "mobile": {
      "type": "boolean",
      "description": "`true` when the address belongs to a mobile carrier network.",
      "x-group": "Detection",
      "x-bit": 65536,
      "examples": [
       false
      ]
     },
     "proxy": {
      "type": "boolean",
      "description": "`true` when the address belongs to a VPN, public proxy, Tor exit, privacy relay or residential proxy.",
      "x-group": "Detection",
      "x-bit": 131072,
      "examples": [
       false
      ]
     },
     "hosting": {
      "type": "boolean",
      "description": "`true` when the address belongs to a hosting provider, cloud or data centre.",
      "x-group": "Detection",
      "x-bit": 16777216,
      "examples": [
       true
      ]
     },
     "proxyType": {
      "type": [
       "string",
       "null"
      ],
      "description": "Kind of anonymizer: `vpn`, `public`, `tor`, `relay` or `residential`. `null` when `proxy` is `false`.",
      "x-group": "Detection",
      "examples": [
       null
      ],
      "enum": [
       "vpn",
       "public",
       "tor",
       "relay",
       "residential",
       null
      ]
     },
     "provider": {
      "type": [
       "string",
       "null"
      ],
      "description": "Name of the VPN, relay or hosting provider, when known.",
      "x-group": "Detection",
      "examples": [
       "Google"
      ]
     },
     "lastSeen": {
      "type": [
       "string",
       "null"
      ],
      "description": "When the address was last seen on the list that flagged it (ISO 8601). `null` when no dated list matched.",
      "x-group": "Detection",
      "examples": [
       null
      ]
     },
     "services": {
      "type": "array",
      "description": "Plain-language labels for everything detected, such as `VPN Server`.",
      "x-group": "Detection",
      "examples": [
       [
        "Data Center/Web Hosting/Transit"
       ]
      ],
      "items": {
       "type": "string"
      }
     },
     "risk": {
      "type": "integer",
      "description": "Anonymizer score from 0 to 100: the highest of the VPN, proxy, Tor, relay and residential scores.",
      "x-group": "Detection",
      "examples": [
       0
      ],
      "minimum": 0,
      "maximum": 100
     },
     "crawler": {
      "type": [
       "string",
       "boolean"
      ],
      "description": "Name of the search or AI crawler the address belongs to, or `false`.",
      "x-group": "Detection",
      "examples": [
       false
      ]
     },
     "threat": {
      "type": "array",
      "description": "Names of the abuse lists the address appears on. Empty when there are none.",
      "x-group": "Detection",
      "examples": [
       []
      ],
      "items": {
       "type": "string"
      }
     },
     "asn": {
      "type": [
       "integer",
       "null"
      ],
      "description": "AS number as an integer. `null` when the address is not announced.",
      "x-group": "Network",
      "examples": [
       15169
      ]
     },
     "asDomain": {
      "type": "string",
      "description": "Domain name of the network operator, when known.",
      "x-group": "Network",
      "examples": [
       "google.com"
      ]
     },
     "networkClass": {
      "type": [
       "string",
       "null"
      ],
      "description": "Type of network, from several sources joined with ` · `: the OpenASN category (such as `isp` or `hosting`) and what the network calls itself on PeeringDB (such as `Cable/DSL/ISP`, `Content`, `NSP` or `Educational/Research`).",
      "x-group": "Network",
      "examples": [
       "hosting · Content"
      ]
     },
     "hostname": {
      "type": "string",
      "description": "Same value as `reverse`.",
      "x-group": "Network",
      "examples": [
       "dns.google"
      ]
     },
     "hostnameVerified": {
      "type": "boolean",
      "description": "`true` when the reverse DNS name resolves back to the same address.",
      "x-group": "Network",
      "examples": [
       true
      ]
     },
     "resolvedFrom": {
      "type": [
       "string",
       "null"
      ],
      "description": "The domain name you sent, when the query was a domain. Otherwise `null`.",
      "x-group": "Request",
      "examples": [
       null
      ]
     },
     "ipVersion": {
      "type": "integer",
      "description": "`4` or `6`.",
      "x-group": "Address",
      "examples": [
       4
      ],
      "enum": [
       4,
       6
      ]
     },
     "decimal": {
      "type": [
       "integer",
       "string"
      ],
      "description": "The address as a decimal number. A string for IPv6, because the number is too large for a JSON number.",
      "x-group": "Address",
      "examples": [
       134744072
      ]
     },
     "expanded": {
      "type": [
       "string",
       "null"
      ],
      "description": "Full IPv6 form with all eight groups. `null` for IPv4.",
      "x-group": "Address",
      "examples": [
       null
      ]
     },
     "accuracyRadius": {
      "type": [
       "integer",
       "null"
      ],
      "description": "Radius in kilometres around `lat` and `lon` that the address is likely to be within, when known.",
      "x-group": "Location",
      "examples": [
       null
      ]
     },
     "whois": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/Whois"
       },
       {
        "type": "null"
       }
      ],
      "description": "Registry record for the address block: `netname`, `org`, `range`, `type`, `country`, `registry` and `abuseEmail`. `null` when not available.",
      "x-group": "Network",
      "examples": [
       {
        "netname": "GOGL",
        "org": "Google LLC",
        "range": "8.8.8.0 - 8.8.8.255",
        "type": "DIRECT ALLOCATION",
        "country": null,
        "registry": "arin",
        "abuseEmail": "network-abuse@google.com"
       }
      ]
     },
     "geoSource": {
      "type": [
       "string",
       "null"
      ],
      "description": "Where the location came from: a database name, or `report` after a confirmed location report.",
      "x-group": "Sources",
      "examples": [
       "dbip-city"
      ]
     },
     "asnSource": {
      "type": [
       "string",
       "null"
      ],
      "description": "Dataset the AS number came from.",
      "x-group": "Sources",
      "examples": [
       "iptoasn"
      ]
     },
     "geoAlt": {
      "oneOf": [
       {
        "$ref": "#/components/schemas/GeoAlt"
       },
       {
        "type": "null"
       }
      ],
      "description": "Location according to a second source, when there is one: `source`, `countryCode`, `regionName`, `city`, `lat` and `lon`.",
      "x-group": "Sources",
      "examples": [
       null
      ]
     },
     "scores": {
      "type": "object",
      "description": "Score from 0 to 1 for each label that has evidence. A flag turns on at 0.60.",
      "x-group": "Detection",
      "examples": [
       {
        "hosting": 1
       }
      ],
      "additionalProperties": {
       "type": "number",
       "minimum": 0,
       "maximum": 1
      }
     },
     "signals": {
      "type": "array",
      "description": "Every list or rule that matched the address, strongest first.",
      "x-group": "Detection",
      "examples": [
       [
        {
         "label": "hosting",
         "source": "google-all",
         "name": "Google (all services)",
         "provider": "Google",
         "weight": 0.9,
         "match": "8.8.8.0/24",
         "firstSeen": null,
         "lastSeen": null
        }
       ]
      ],
      "items": {
       "$ref": "#/components/schemas/Signal"
      }
     }
    }
   },
   "LookupFailure": {
    "type": "object",
    "description": "A lookup that could not be answered.",
    "properties": {
     "status": {
      "type": "string",
      "enum": [
       "fail"
      ]
     },
     "message": {
      "type": "string",
      "enum": [
       "invalid query",
       "private range",
       "reserved range",
       "live lookup limit reached"
      ],
      "description": "Why the lookup failed.",
      "x-bit": 32768
     },
     "query": {
      "type": "string",
      "description": "The query as it was understood."
     }
    },
    "example": {
     "status": "fail",
     "message": "private range",
     "query": "192.168.1.1"
    }
   },
   "Signal": {
    "type": "object",
    "description": "One list or rule that matched the address.",
    "properties": {
     "label": {
      "type": "string",
      "description": "What the signal says about the address: `vpn`, `proxy`, `tor`, `relay`, `residential`, `hosting`, `mobile`, `crawler`, `abuse`, `not-proxy` or `not-hosting`."
     },
     "source": {
      "type": "string",
      "description": "Identifier of the list or rule."
     },
     "name": {
      "type": "string",
      "description": "Name of the list or rule."
     },
     "provider": {
      "type": [
       "string",
       "null"
      ],
      "description": "Provider the list names for this address, when it names one."
     },
     "weight": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "How much the signal counts, from 0 to 1."
     },
     "match": {
      "type": [
       "string",
       "null"
      ],
      "description": "The range, address, AS number or keyword that matched."
     },
     "firstSeen": {
      "type": [
       "string",
       "null"
      ],
      "description": "When the address first appeared on the list (ISO 8601), for lists that are tracked over time."
     },
     "lastSeen": {
      "type": [
       "string",
       "null"
      ],
      "description": "When the address last appeared on the list (ISO 8601)."
     },
     "reduced": {
      "type": "string",
      "description": "Present when the weight was lowered, with the reason."
     }
    }
   },
   "Whois": {
    "type": "object",
    "properties": {
     "netname": {
      "type": [
       "string",
       "null"
      ]
     },
     "org": {
      "type": [
       "string",
       "null"
      ]
     },
     "range": {
      "type": [
       "string",
       "null"
      ]
     },
     "type": {
      "type": [
       "string",
       "null"
      ]
     },
     "country": {
      "type": [
       "string",
       "null"
      ]
     },
     "registry": {
      "type": [
       "string",
       "null"
      ],
      "description": "`arin`, `ripe`, `apnic`, `lacnic` or `afrinic`."
     },
     "abuseEmail": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   },
   "GeoAlt": {
    "type": "object",
    "properties": {
     "source": {
      "type": "string"
     },
     "countryCode": {
      "type": [
       "string",
       "null"
      ]
     },
     "regionName": {
      "type": [
       "string",
       "null"
      ]
     },
     "city": {
      "type": [
       "string",
       "null"
      ]
     },
     "lat": {
      "type": [
       "number",
       "null"
      ]
     },
     "lon": {
      "type": [
       "number",
       "null"
      ]
     }
    }
   },
   "BatchItem": {
    "type": "object",
    "required": [
     "query"
    ],
    "properties": {
     "query": {
      "type": "string",
      "description": "An IP address."
     },
     "fields": {
      "type": [
       "string",
       "integer"
      ],
      "description": "Fields for this item. Overrides `fields` in the URL."
     },
     "lang": {
      "type": "string",
      "enum": [
       "en",
       "de",
       "es",
       "pt-BR",
       "fr",
       "ja",
       "zh-CN",
       "ru"
      ],
      "description": "Language for this item. Overrides `lang` in the URL."
     }
    }
   },
   "Report": {
    "type": "object",
    "required": [
     "ip",
     "type"
    ],
    "properties": {
     "ip": {
      "type": "string",
      "description": "The address the report is about."
     },
     "type": {
      "type": "string",
      "enum": [
       "vpn",
       "proxy",
       "tor",
       "relay",
       "hosting",
       "mobile",
       "residential",
       "not-proxy",
       "not-hosting",
       "wrong-location",
       "other"
      ],
      "description": "What the address is, or what is wrong with the result."
     },
     "provider": {
      "type": "string",
      "maxLength": 80,
      "description": "Name of the VPN or proxy service, when known."
     },
     "note": {
      "type": "string",
      "maxLength": 500,
      "description": "Anything that helps to check the report."
     },
     "country": {
      "type": "string",
      "description": "For `wrong-location`: two-letter code of the correct country."
     },
     "city": {
      "type": "string",
      "maxLength": 80,
      "description": "For `wrong-location`: name of the correct city."
     },
     "lat": {
      "type": "number",
      "description": "For `wrong-location`: latitude of the correct place. Optional when `city` is given."
     },
     "lon": {
      "type": "number",
      "description": "For `wrong-location`: longitude of the correct place."
     }
    }
   },
   "ReportResult": {
    "type": "object",
    "properties": {
     "status": {
      "type": "string",
      "enum": [
       "success"
      ]
     },
     "outcome": {
      "type": "string",
      "enum": [
       "queued",
       "confirmed",
       "already-detected"
      ],
      "description": "`queued`: waiting for review. `confirmed`: applied. `already-detected`: nothing to change."
     },
     "id": {
      "type": "string",
      "description": "Identifier of the stored report. Absent when the outcome is `already-detected`."
     },
     "message": {
      "type": "string",
      "description": "Present when the outcome is `already-detected`."
     }
    }
   },
   "ReportStatus": {
    "type": "object",
    "properties": {
     "status": {
      "type": "string",
      "enum": [
       "success"
      ]
     },
     "id": {
      "type": "string"
     },
     "ip": {
      "type": "string",
      "description": "The address the report is about."
     },
     "type": {
      "type": "string",
      "enum": [
       "vpn",
       "proxy",
       "tor",
       "relay",
       "hosting",
       "mobile",
       "residential",
       "not-proxy",
       "not-hosting",
       "wrong-location",
       "other"
      ]
     },
     "review": {
      "type": "string",
      "enum": [
       "waiting",
       "confirmed",
       "rejected"
      ],
      "description": "What the reviewer decided."
     },
     "sentAt": {
      "type": "string",
      "format": "date-time"
     },
     "decidedAt": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time",
      "description": "`null` while the report is waiting."
     },
     "effect": {
      "type": "string",
      "enum": [
       "pending",
       "active",
       "expired",
       "none"
      ],
      "description": "`active`: lookups reflect the report now. `pending`: waiting for review. `expired`: it did, and no longer does. `none`: it changes nothing, because it was rejected or is a note."
     },
     "effectUntil": {
      "type": [
       "string",
       "null"
      ],
      "format": "date-time",
      "description": "When the effect ends."
     }
    },
    "example": {
     "status": "success",
     "id": "0b6f3f0e-6f43-4a6e-9a55-6f0f6c1f6f6e",
     "ip": "203.0.113.7",
     "type": "not-hosting",
     "review": "confirmed",
     "sentAt": "2026-10-05T09:12:44.000Z",
     "decidedAt": "2026-10-05T11:30:02.000Z",
     "effect": "active",
     "effectUntil": "2027-10-05T11:30:02.000Z"
    }
   },
   "Error": {
    "type": "object",
    "properties": {
     "status": {
      "type": "string",
      "enum": [
       "fail"
      ]
     },
     "message": {
      "type": "string"
     }
    },
    "example": {
     "status": "fail",
     "message": "body must be a JSON array of IPs"
    }
   },
   "RateLimited": {
    "type": "object",
    "properties": {
     "status": {
      "type": "string",
      "enum": [
       "fail"
      ]
     },
     "message": {
      "type": "string",
      "enum": [
       "rate limit exceeded",
       "daily report limit reached"
      ]
     },
     "limit": {
      "type": "integer"
     },
     "retryAfter": {
      "type": "integer",
      "description": "Seconds to wait."
     }
    }
   }
  }
 },
 "x-presets": [
  {
   "id": "all",
   "name": "Everything",
   "fields": []
  },
  {
   "id": "location",
   "name": "Location",
   "fields": [
    "query",
    "status",
    "message",
    "country",
    "countryCode",
    "regionName",
    "city",
    "zip",
    "lat",
    "lon",
    "timezone"
   ]
  },
  {
   "id": "network",
   "name": "Network",
   "fields": [
    "query",
    "status",
    "message",
    "isp",
    "org",
    "as",
    "asn",
    "asname",
    "reverse"
   ]
  },
  {
   "id": "security",
   "name": "Security",
   "fields": [
    "query",
    "status",
    "message",
    "proxy",
    "proxyType",
    "provider",
    "hosting",
    "mobile",
    "risk"
   ]
  },
  {
   "id": "minimal",
   "name": "Minimal",
   "fields": [
    "status",
    "message",
    "countryCode",
    "proxy"
   ]
  }
 ],
 "x-field-groups": [
  "Request",
  "Location",
  "Network",
  "Detection",
  "Address",
  "Sources"
 ]
}