# IPOwl API reference > IP address lookup API. Returns the location, network owner, and VPN, proxy, Tor, relay and hosting detection for any IPv4 or IPv6 address. - Base URL: `https://ipowl.dev` - Authentication: none. There is no API key and no sign-up. - Format: JSON over HTTPS. Cross-origin requests (CORS) are allowed from any site. - Rate limit: 100 requests per minute per client. - OpenAPI 3.1: https://ipowl.dev/openapi.json ## Quick start ```bash curl "https://ipowl.dev/json/8.8.8.8?fields=query,country,city,isp,proxy,hosting" ``` ```json { "query": "8.8.8.8", "country": "United States", "city": "Mountain View", "isp": "Google LLC", "proxy": false, "hosting": true } ``` ## Endpoints ### GET /json/{query} Looks up one address. `{query}` is an IPv4 address, an IPv6 address or a domain name. A domain name is resolved first and the address it resolves to is looked up; `resolvedFrom` then holds the domain. ```bash curl "https://ipowl.dev/json/8.8.8.8" curl "https://ipowl.dev/json/2606:4700:4700::1111" curl "https://ipowl.dev/json/github.com" ``` ### GET /json Looks up the address the request came from. Call it from a browser to learn about your visitor. ```javascript const response = await fetch("https://ipowl.dev/json?fields=status,countryCode,proxy"); const visitor = await response.json(); ``` ### GET /ip Returns the caller's IP address as plain text, followed by a newline. ```bash curl https://ipowl.dev/ip ``` ### POST /batch Looks up as many as 100 addresses in one request. The body is a JSON array. Each item is an address string, or an object with `query` and optionally its own `fields` and `lang`. Results come back as an array in the same order. - Each address counts as one request towards the rate limit. - Batches are answered from memory: `reverse`, `hostname`, `org` and `whois` are filled only when already cached, and domain names are not resolved. - More than 100 items returns HTTP 422. A body that is not a JSON array returns HTTP 400. ```bash curl -X POST "https://ipowl.dev/batch?fields=query,country,proxy" \ -H "Content-Type: application/json" \ -d '["8.8.8.8", {"query": "24.48.0.1", "fields": "query,city,isp", "lang": "fr"}]' ``` ```json [ { "query": "8.8.8.8", "country": "United States", "proxy": false }, { "query": "24.48.0.1", "city": "Montréal", "isp": "Videotron Ltee" } ] ``` ### POST /report Reports a wrong result. The body is a JSON object. | Field | Type | Required | Description | |---|---|---|---| | `ip` | string | yes | The address the report is about. | | `type` | string | yes | One of: `vpn`, `proxy`, `tor`, `relay`, `hosting`, `mobile`, `residential`, `not-proxy`, `not-hosting`, `wrong-location`, `other`. | | `provider` | string | no | Name of the VPN or proxy service, when known. | | `note` | string | no | Anything that helps to check the report, up to 500 characters. | | `country` | string | no | For `wrong-location`: two-letter code of the correct country. | | `city` | string | no | For `wrong-location`: name of the correct city. | The response has an `outcome`: - `queued` (HTTP 201): stored and waiting for review. - `confirmed` (HTTP 201): applied. Lookups of the address now reflect it. - `already-detected` (HTTP 200): the API already says what the report claims, so nothing was stored. A report counts as 10 requests, and each client may send 50 reports per day. ```bash curl -X POST "https://ipowl.dev/report" \ -H "Content-Type: application/json" \ -d '{"ip": "203.0.113.7", "type": "vpn", "provider": "ExampleVPN"}' ``` ### GET /report/{id} Where a report stands. Use the `id` that `POST /report` returned. Counts as one request. ```json { "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" } ``` - `review`: `waiting`, `confirmed` or `rejected`. - `effect`: `active` (lookups reflect it now), `pending` (waiting), `expired`, or `none` (rejected, or a note). - An unknown id answers HTTP 404. ### GET /healthz Returns HTTP 200 and `{"ok": true, "sources": 124, "loaded": 124}` while the service is running. Does not count towards the rate limit. ## Parameters Query parameters for `/json`, `/json/{query}` and `/batch`. All are optional. | Parameter | Description | Example | |---|---|---| | `fields` | Fields to return, as a comma-separated list of names. Without it, every field is returned. | `fields=query,country,proxy` | | `lang` | Language for `country`: `en` (English), `de` (German), `es` (Spanish), `pt-BR` (Portuguese (Brazil)), `fr` (French), `ja` (Japanese), `zh-CN` (Chinese (Simplified)), `ru` (Russian). Default `en`. | `lang=fr` | | `fast` | Set to `1` to answer from memory only. Skips live reverse DNS and registry queries, so `reverse`, `hostname`, `org` and `whois` may be empty. Without it the API waits up to 300 ms for them; what is late is left empty and is present on the next lookup. | `fast=1` | | `callback` | Wraps the response in a call to this function (JSONP). | `callback=handle` | `fields` also accepts a number: the sum of the numeric values of the fields you want. Only these fields have a numeric value: `query` 8192, `status` 16384, `continent` 1048576, `continentCode` 2097152, `country` 1, `countryCode` 2, `region` 4, `regionName` 8, `city` 16, `district` 524288, `zip` 32, `lat` 64, `lon` 128, `timezone` 256, `offset` 33554432, `currency` 8388608, `isp` 512, `org` 1024, `as` 2048, `asname` 4194304, `reverse` 4096, `mobile` 65536, `proxy` 131072, `hosting` 16777216, `message` 32768. ## Response fields A successful lookup returns the fields below. With `fields`, only the requested ones are returned. ### Request | Field | Type | Description | Example | |---|---|---|---| | `query` | string | The IP address that was looked up. | `8.8.8.8` | | `status` | string | `success` when the address was looked up, `fail` when it could not be. | `success` | | `resolvedFrom` | string or null | The domain name you sent, when the query was a domain. Otherwise `null`. | `null` | ### Location | Field | Type | Description | Example | |---|---|---|---| | `continent` | string | Continent name. | `North America` | | `continentCode` | string | Two-letter continent code. | `NA` | | `country` | string | Country name, in the language set by `lang`. | `United States` | | `countryCode` | string | Two-letter country code (ISO 3166-1 alpha-2). | `US` | | `region` | string | Region or state code (ISO 3166-2, without the country prefix). | `CA` | | `regionName` | string | Region or state name. | `California` | | `city` | string | City name. | `Mountain View` | | `district` | string | District within the city, when the location database names one. Usually empty. | (empty) | | `zip` | string | Postal code closest to the centre of the city. | `94043` | | `lat` | number or null | Latitude of the centre of the city. `null` when the city is unknown. | `37.422` | | `lon` | number or null | Longitude of the centre of the city. `null` when the city is unknown. | `-122.085` | | `timezone` | string | IANA time zone name. | `America/Los_Angeles` | | `offset` | integer or null | Current UTC offset in seconds, including daylight saving time. | `-25200` | | `currency` | string | Currency of the country (ISO 4217). | `USD` | | `accuracyRadius` | integer or null | Radius in kilometres around `lat` and `lon` that the address is likely to be within, when known. | `null` | ### Network | Field | Type | Description | Example | |---|---|---|---| | `isp` | string | Name of the network that announces the address. | `Google LLC` | | `org` | string | Organisation the address block is registered to. Same as `isp` when the registry has no record. | `Google LLC` | | `as` | string | AS number and network name, separated by a space. Empty when the address is not announced. | `AS15169 Google LLC` | | `asname` | string | Short name of the AS from the registry. | `GOOGLE` | | `reverse` | string | Reverse DNS name of the address. Empty when it has none, or when `fast=1` is set and the name is not cached. | `dns.google` | | `asn` | integer or null | AS number as an integer. `null` when the address is not announced. | `15169` | | `asDomain` | string | Domain name of the network operator, when known. | `google.com` | | `networkClass` | string or null | 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`). | `hosting · Content` | | `hostname` | string | Same value as `reverse`. | `dns.google` | | `hostnameVerified` | boolean | `true` when the reverse DNS name resolves back to the same address. | `true` | | `whois` | object or null | Registry record for the address block: `netname`, `org`, `range`, `type`, `country`, `registry` and `abuseEmail`. `null` when not available. | `{"netname":"GOGL","org":"Google LLC","range":"8.8.8.0 - 8.8.8.255","type":"DIREC` | ### Detection | Field | Type | Description | Example | |---|---|---|---| | `mobile` | boolean | `true` when the address belongs to a mobile carrier network. | `false` | | `proxy` | boolean | `true` when the address belongs to a VPN, public proxy, Tor exit, privacy relay or residential proxy. | `false` | | `hosting` | boolean | `true` when the address belongs to a hosting provider, cloud or data centre. | `true` | | `proxyType` | string or null | Kind of anonymizer: `vpn`, `public`, `tor`, `relay` or `residential`. `null` when `proxy` is `false`. | `null` | | `provider` | string or null | Name of the VPN, relay or hosting provider, when known. | `Google` | | `lastSeen` | string or null | When the address was last seen on the list that flagged it (ISO 8601). `null` when no dated list matched. | `null` | | `services` | array | Plain-language labels for everything detected, such as `VPN Server`. | `["Data Center/Web Hosting/Transit"]` | | `risk` | integer | Anonymizer score from 0 to 100: the highest of the VPN, proxy, Tor, relay and residential scores. | `0` | | `crawler` | string or boolean | Name of the search or AI crawler the address belongs to, or `false`. | `false` | | `threat` | array | Names of the abuse lists the address appears on. Empty when there are none. | `[]` | | `scores` | object | Score from 0 to 1 for each label that has evidence. A flag turns on at 0.60. | `{"hosting":1}` | | `signals` | array | Every list or rule that matched the address, strongest first. | `[{"label":"hosting","source":"google-all","name":"Google (all services)","provid` | ### Address | Field | Type | Description | Example | |---|---|---|---| | `ipVersion` | integer | `4` or `6`. | `4` | | `decimal` | integer or string | The address as a decimal number. A string for IPv6, because the number is too large for a JSON number. | `134744072` | | `expanded` | string or null | Full IPv6 form with all eight groups. `null` for IPv4. | `null` | ### Sources | Field | Type | Description | Example | |---|---|---|---| | `geoSource` | string or null | Where the location came from: a database name, or `report` after a confirmed location report. | `dbip-city` | | `asnSource` | string or null | Dataset the AS number came from. | `iptoasn` | | `geoAlt` | object or null | Location according to a second source, when there is one: `source`, `countryCode`, `regionName`, `city`, `lat` and `lon`. | `null` | ## How detection works Each list or rule that matches an address is a signal with a weight from 0 to 1. Signals with the same label are combined into a score for that label: `score = 1 - (1 - w1) * (1 - w2) * ...`. A flag turns on when its score reaches 0.60. - `proxy` is `true` when any of the `vpn`, `proxy`, `tor`, `relay` or `residential` scores reaches 0.60. `proxyType` names the strongest one. - `hosting` and `mobile` each have their own score. - `scores` holds every score, so you can apply a stricter or looser threshold of your own. - `signals` lists the evidence: `label`, `source`, `name`, `provider`, `weight`, `match`, `firstSeen`, `lastSeen`. ## Errors A lookup that cannot be answered returns HTTP 200 with `status` set to `fail` and a `message`: | message | Meaning | |---|---| | `invalid query` | The query is not an IP address, and not a domain name that resolves. | | `private range` | A private or link-local address, such as 10.0.0.1, 192.168.1.1 or fe80::1. | | `reserved range` | Loopback, multicast, documentation or other reserved address space. | | `live lookup limit reached` | A domain name needs a live DNS query and the live lookup allowance is used up. Send the IP address, or try again in a minute. | ```json { "status": "fail", "message": "private range", "query": "192.168.1.1" } ``` HTTP error statuses are used for requests the API cannot process: | Status | Meaning | |---|---| | 400 | The request body is not valid JSON, a batch body is not an array, or a report is missing a required field. | | 404 | No such path. | | 405 | The path exists but does not accept this method. | | 413 | The request body is larger than 256 kB. | | 422 | A batch has more than 100 items. | | 429 | Rate limit exceeded. Wait the number of seconds in `Retry-After`. | | 503 | The report queue is full. Try again later. | ## Rate limits - 100 requests per minute per client. A client is one IPv4 address or one IPv6 /64 network. - Every call to `/json`, `/ip` and `/batch` counts. Each address in a batch counts as one request. A report counts as 10. - Live lookups (reverse DNS and registry data for an address not seen recently) are limited to 30 per minute per client. Past that, lookups still succeed and those fields come from cache only. - There is no daily cap. Every API response carries these headers: | Header | Meaning | |---|---| | `X-Rl` | Requests left in the current window. | | `X-Ttl` | Seconds until the window resets. | | `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` | The same information under the standard header names. | | `Retry-After` | Sent with HTTP 429: seconds to wait before the next request. | Over the limit, the API answers HTTP 429: ```json { "status": "fail", "message": "rate limit exceeded", "limit": 100, "retryAfter": 37 } ``` To stay inside the limit: request only the fields you need, cache results for at least a few hours, use `/batch` for lists, and wait `Retry-After` seconds after a 429. ## Examples ### Flag sign-ups that come through an anonymizer (Python) ```python import requests def check(ip): r = requests.get(f"https://ipowl.dev/json/{ip}", params={"fields": "status,proxy,proxyType,provider,hosting"}, timeout=5).json() if r["status"] != "success": return "unknown" if r["proxy"]: return f"anonymizer ({r['proxyType']})" return "datacenter" if r["hosting"] else "ok" ``` ### Send visitors to a country page (browser JavaScript) ```javascript const response = await fetch("https://ipowl.dev/json?fields=status,countryCode"); const visitor = await response.json(); if (visitor.status === "success" && visitor.countryCode === "CA") location.replace("/ca/"); ``` ### Retry after a 429 (JavaScript) ```javascript async function lookup(ip) { for (;;) { const response = await fetch(`https://ipowl.dev/json/${ip}`); if (response.status !== 429) return response.json(); await new Promise((r) => setTimeout(r, Number(response.headers.get("Retry-After")) * 1000)); } } ```