IP Geolocation API — /api/v1/ip/lookup

Multi-source aggregation: MaxMind GeoIP2, ASN registry, and an in-house risk score. Returns city/country, lat/lng, ISP, hosting provider classification, and VPN/Proxy/Tor flags.

• Method GET
• Path /api/v1/ip/lookup
• Stability STABLE
• Version v2026-05-15
• Summary Geo, ASN, ISP, and risk-score lookup for any IPv4 / IPv6 address.

Pass these as query-string parameters (or, where indicated, in the request headers). Required params marked required.

• ip (required) — string Target IPv4 or IPv6 address.

All successful responses follow the standard `{ success: true, data: {...} }` envelope. Notable fields on the data object for this endpoint:

• data.ip — string Echo of the queried IP.
• data.location.continent — string Continent name.
• data.location.country — object `{code, name}`.
• data.location.state — string Region / state.
• data.location.city — string City name.
• data.location.postalCode — string Postal code (may be `N/A`).
• data.location.location.latitude — number Decimal lat.
• data.location.location.longitude — number Decimal lng.
• data.location.location.timeZone — string IANA timezone (e.g. `America/Chicago`).
• data.location.security — object `isAnonymous`, `isVPN`, `isProxy`, `isTorExitNode`, `isHostingProvider` flags.

Truncated but representative example for a real lookup:

{
  "success": true,
  "data": {
    "ip": "8.8.8.8",
    "location": {
      "continent": "North America",
      "country": {
        "code": "US",
        "name": "United States"
      },
      "city": "Unknown City",
      "state": "Unknown State",
      "location": {
        "latitude": 37.751,
        "longitude": -97.822,
        "timeZone": "America/Chicago"
      },
      "security": {
        "isAnonymous": false,
        "isVPN": false,
        "isProxy": false,
        "isTorExitNode": false,
        "isHostingProvider": false
      }
    }
  }
}

Errors return HTTP status codes paired with stable machine-readable codes. Match on the code field rather than the human-readable message.

• 400 INVALID_IP Not a valid IPv4 / IPv6 address.

Patterns we recommend when integrating this endpoint:

• Cache by IP for ~24h — assignments change but rarely within a session.
• Treat `isVPN || isProxy || isTorExitNode` as a risk signal, not a hard block.

• How accurate is city-level data? ~70% within 50km for residential IPs; corporate / mobile ranges are less precise.