Introduction
The IPOwl API tells you where an IP address is, which network runs it, and whether it belongs to a VPN, proxy, Tor exit or data centre.
Every endpoint is a plain URL. Send a request, read the JSON that comes back, and add query parameters to choose the fields you get.
- Base URL
- Authentication
- None. There is no API key and no sign-up.
- Format
- JSON, encoded as UTF-8.
- Browsers
- Cross-origin requests are allowed from any site.
- Rate limit
- 100 requests per minute for each client. See rate limits.
Quickstart
-
Send a request
Put the address after
/json/. Any HTTP client works, and there is nothing to install. -
Check the status
Every lookup has a
status. Use the result when it issuccess. When it isfail,messagesays why. -
Ask only for what you use
Add
fieldswith the names you need. The response is smaller and quicker to parse. The request builder writes the URL for you.
To look up the person visiting your site, call /json without an address from their browser. See look up the caller.
Request builder
Choose an address and the fields you need, then send a real request. The URL and the code update as you choose.
/json/{query}Look up an address
Returns location, network and detection data for one address.
Path parameters
- querystringRequired
- 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. The response then includes
resolvedFrom.
Query parameters
- fieldsstringOptional
- The fields to return. Without it, every field is returned.
- langstringOptional
- Language for the country name.
- faststringOptional
- Set to
1to answer from memory only.
Each one is explained under parameters.
Returns
A lookup object. If the address cannot be looked up, the response still has HTTP status 200, with status set to fail. See errors.
/jsonLook up the caller
Looks up the address the request came from. Call it from a browser to learn about your visitor without knowing their address first.
From a server, it returns your server's own address. To look up a user from your backend, pass their address to /json/{query}.
Query parameters
The same as for look up an address: fields, lang and fast.
Returns
A lookup object for the caller's address.
/ipGet the caller's IP address
Returns the address the request came from as plain text, followed by a newline. Handy in shell scripts, or when the address is all you need.
Returns
The address, with the content type text/plain.
/batchLook up many addresses
Looks up as many as 100 addresses in one request. Results come back as an array, in the order you sent them.
Request body
A JSON array. Each item is an address as a string, or an object with these properties:
- querystringRequired
- The address to look up.
- fieldsstringOptional
- Fields for this item. Takes the place of
fieldsin the URL. - langstringOptional
- Language for this item. Takes the place of
langin the URL.
Query parameters
fields and lang in the URL apply to every item that does not set its own.
Good to know
- Each address counts as one request towards the rate limit. A batch of 40 uses 40.
- Batches are answered from memory, as with
fast=1.reverse,hostname,organdwhoisare filled only when already cached. - Send IP addresses. A domain name needs a live DNS query, which a batch makes only while your live lookup allowance lasts.
- More than 100 items returns HTTP 422. A body that is not a JSON array returns HTTP 400.
Returns
An array with one lookup object for each item.
/reportReport a wrong result
Tells the service that an address was missed, flagged by mistake, or placed in the wrong location. A confirmed report changes the answer everyone gets for that address.
Request body
A JSON object with these properties:
- ipstringRequired
- The address the report is about.
- typestringRequired
- What the address is, or what is wrong with the result. One of the values in the table below.
- providerstringOptional
- Name of the VPN or proxy service, when you know it.
- notestringOptional
- Anything that helps to check the report, up to 500 characters.
- countrycitystringOptional
- For
wrong-location: the two-letter code of the correct country, and the name of the correct city.
| type | Meaning |
|---|---|
| vpn | A VPN server. |
| proxy | A public proxy. |
| tor | A Tor exit. |
| relay | A privacy relay, such as iCloud Private Relay. |
| residential | A residential proxy. |
| hosting | A hosting or data centre address. |
| mobile | A mobile carrier address. |
| not-proxy | Flagged as a proxy, but it is not one. |
| not-hosting | Flagged as hosting, but it is a home, office or mobile connection. Applies to the address's /24, or /48 for IPv6. |
| wrong-location | The location is wrong. Send country and city with it. |
| other | Anything else. Explain in note. |
Returns
An object with an outcome:
- queuedHTTP 201
- The report is stored and waits for review.
- confirmedHTTP 201
- The report is applied. Lookups of the address now reflect it.
- already-detectedHTTP 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 a day.
/report/{id}Check a report
Where a report stands: waiting for review, confirmed or rejected, and whether lookups reflect it now. Use the id that sending the report returned. Counts as one request.
A site that lets its users dispute a result can send the report for them, keep the id, and show them the outcome later.
Returns
- reviewstring
waiting,confirmedorrejected.- effectstring
active: lookups reflect the report now, untileffectUntil.pending: waiting for review.expired: it did, and no longer does.none: rejected, or a note that changes nothing.- sentAtdecidedAtstring
- ISO 8601 times.
decidedAtisnullwhile the report is waiting.
An unknown id answers HTTP 404. The report's sender and note are never returned.
/healthzCheck service status
Returns HTTP 200 while the service is running. Point an uptime monitor at it. It does not count towards the rate limit.
Returns
sources is the number of data sources in use and loaded is how many are loaded. The two differ only for a few minutes after the service starts.
Parameters
Add these to the URL of /json, /json/{query} or /batch. All of them are optional.
- fieldsstring
-
The fields to return, as a comma-separated list of names from the field reference. Without it, every field is returned. Names the API does not know are ignored.
Numeric form
fieldsalso accepts a number: add up the values of the fields you want. Only these fields have a value, so use names for anything else. - langstring
-
Language for
country.regionNameandcityare always in English. A value the API does not know falls back to English. - faststring
- Set to
1to answer from memory only. The API then skips live reverse DNS and registry queries and replies in a few milliseconds.reverse,hostnameandwhoisare filled only when already cached, andorgfalls back toisp. Withoutfast, the API waits up to 300 ms for those live answers. Anything that has not arrived by then is left empty and is there on the next lookup of the same address. - callbackstring
- Wraps the response in a call to the function you name and serves it as JavaScript (JSONP). The name may contain letters, digits,
_,$and., up to 64 characters. You need this only for clients that cannot make cross-origin requests.
The lookup object
A successful lookup returns one JSON object. Every field is always present, unless you ask for a subset with fields.
- Text fields with no value are empty strings.
- Some fields are
nullwhen there is nothing to report. The field reference says which. - New fields may be added over time. Ignore fields you do not recognise.
The fields fall into six groups:
- Request
- The address that was looked up, and whether the lookup succeeded.
- Location
- Country, region, city, coordinates, time zone and currency.
- Network
- The network that runs the address, its AS number, reverse DNS and registry record.
- Detection
- VPN, proxy, Tor, hosting and mobile flags, with the evidence behind them.
- Address
- The address in other notations.
- Sources
- Which dataset each part of the answer came from.
Response fields
Every field of a successful lookup. Use the names in the fields parameter.
| Loading fields |
How detection works
Each list or rule that matches an address is a signal. A signal has a label, such as vpn or hosting, and a weight from 0 to 1.
Signals with the same label are combined into one score. A flag turns on when its score reaches 0.60.
score = 1 − (1 − w1) × (1 − w2) × …
- proxy
truewhen thevpn,proxy,tor,relayorresidentialscore reaches 0.60.proxyTypenames the strongest of them.- hostingmobile
- Each has its own score and turns on at 0.60.
- risk
- The highest anonymizer score, from 0 to 100.
- scores
- Every score. Read it to apply a stricter or looser threshold of your own.
The signal object
Each item in signals is one piece of evidence:
- labelstring
- What the signal says about the address:
vpn,proxy,tor,relay,residential,hosting,mobile,crawlerorabuse. - sourcenamestring
- The identifier and the name of the list or rule.
- providerstring or null
- The provider the list names for this address.
- weightnumber
- How much the signal counts, from 0 to 1. Lists that are tracked over time lose weight as their last sighting gets older.
- matchstring
- The range, address, AS number or keyword that matched.
- firstSeenlastSeenstring or null
- When the address first and last appeared on the list, as ISO 8601 timestamps.
Measured accuracy
These figures come from a test against ground truth, not from comparing one database with another. The test set is the RIPE Atlas network: measurement devices at known locations, whose hosts state whether each one sits in a home or a data centre. On 5 October 2026 the API was asked about 22,509 of their addresses.
Location
| Measure | Result |
|---|---|
| Country correct | 98.4% |
| Reported location within 25 km of the device | 58.8% |
| Within 50 km | 65.9% |
| Within 100 km | 72.5% |
| Within 250 km | 83.0% |
| Median distance from the device | 12 km |
Treat the country as reliable and the city as an estimate. For one address in ten, the reported location was more than 378 km from the device.
Detection
| Measure | Result |
|---|---|
| Home connections wrongly flagged as a proxy or VPN | 0.1% |
| Home connections wrongly flagged as hosting | 2.3% |
| Office connections wrongly flagged as hosting | 5.1% |
| Data centre addresses recognised as hosting | 38.6% |
The proxy flag very rarely fires on an ordinary home connection. The home figure leaves out four devices that really were connecting through Cloudflare WARP, which the API correctly reported as a relay.
The hosting flag is tuned to avoid marking people's connections: it rarely fires on a home or office, and it is set for hosting companies, clouds and CDNs. It misses data centres run by ISPs, carriers, businesses and universities, because nothing in public data tells their servers apart from those networks' customers. Do not block on hosting alone.
Not measured
How many VPN and proxy servers are caught. No independent list of them exists to test against, so there is no honest figure to give.
Errors
A lookup that cannot be answered still returns HTTP 200. Check status: when it is fail, message says why.
| 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 your live lookup allowance is used up. Send the IP address, or try again in a minute. |
HTTP error statuses are used when the request itself cannot be processed:
| Status | Meaning |
|---|---|
| 400 | The 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. The Allow header lists the ones it does. |
| 413 | The request body is larger than 256 kB. |
| 422 | A batch has more than 100 items. |
| 429 | Rate limit exceeded. See rate limits. |
| 503 | The report queue is full. Try again later. |
Error bodies are JSON too, with status set to fail and a message.
Rate limits
Each client may make 100 requests per minute. A client is one IPv4 address, or one IPv6 /64 network. There is no daily cap.
| What | Limit | Notes |
|---|---|---|
| Requests | 100 a minute | Every call to /json, /ip and /batch counts. |
| Batch | 1 per address | A batch of 40 addresses uses 40 of the 100. |
| Live lookups | 30 a minute | Reverse DNS and registry data for an address not seen recently need a live query. Past 30, lookups still succeed and those fields come from cache only. |
| Reports | 50 a day | Each one also counts as 10 requests. |
Response headers
Every API response says how much of the allowance is left.
- X-Rl
- Requests left in the current window.
- X-Ttl
- Seconds until the window resets.
- RateLimit-LimitRateLimit-RemainingRateLimit-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 until the window resets. Wait the number of seconds in Retry-After, then carry on. See handle rate limits for code.
Screen sign-ups
Hold an account for review when it is created through an anonymizer or from a data centre.
- Take the client's address from your own server. Never trust an address sent by the browser.
- Ask for the detection fields only.
- Decide what each result means for you. Blocking every flagged address will turn away some real users, so a review step is usually the better choice.
If the lookup fails or times out, let the sign-up through and check it later. The API should never be the reason a user cannot register.
Personalize by country
Pick a language, currency or regional page before the visitor has clicked anything.
Call /json from the browser. The request comes from the visitor, so the API looks up their address and you never handle it yourself.
Each visitor spends their own allowance, not yours. Save the answer in sessionStorage so one visit makes one request.
Enrich a list of addresses
Turn a column of addresses from a log or a spreadsheet into countries and networks.
Send them to /batch in groups of 100. One client can look up 100 addresses a minute, so pause between groups, or wait for X-Ttl when X-Rl reaches 0.
Handle rate limits
When a response has status 429, wait for the number of seconds in Retry-After and send the request again.
To avoid the 429 altogether, read X-Rl after each response. When it reaches 0, wait X-Ttl seconds before the next request.
Good practice
Ask for less
Use fields. A short response is faster to send and to parse.
Cache what you get
An address rarely changes within a day. Keep results for a few hours instead of asking again.
Batch lists
For more than a few addresses, one /batch call is quicker than many single ones.
Decide on your server
A browser can be tampered with. For sign-ups, orders and access, look the address up from your backend.
Plan for failure
Set a timeout, check status, and choose what happens when there is no answer.
Treat location as an estimate
The city is usually the centre of a city or postal area. It never identifies a household.
OpenAPI and llms.txt
The same reference in formats that tools and AI assistants can read.