API documentation

Look up any IP address with one HTTP request. The API returns JSON, needs no key and no sign-up, and can be called from a server or straight from a browser.

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

  1. Send a request

    Put the address after /json/. Any HTTP client works, and there is nothing to install.

  2. Check the status

    Every lookup has a status. Use the result when it is success. When it is fail, message says why.

  3. Ask only for what you use

    Add fields with 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.

Try
Fields

Loading fields

GET
Response
GET/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 1 to 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.

GET/json

Look 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.

GET/ip

Get 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.

POST/batch

Look 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 fields in the URL.
langstringOptional
Language for this item. Takes the place of lang in 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, org and whois are 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.

POST/report

Report 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.
typeMeaning
vpnA VPN server.
proxyA public proxy.
torA Tor exit.
relayA privacy relay, such as iCloud Private Relay.
residentialA residential proxy.
hostingA hosting or data centre address.
mobileA mobile carrier address.
not-proxyFlagged as a proxy, but it is not one.
not-hostingFlagged as hosting, but it is a home, office or mobile connection. Applies to the address's /24, or /48 for IPv6.
wrong-locationThe location is wrong. Send country and city with it.
otherAnything 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.

GET/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, confirmed or rejected.
effectstring
active: lookups reflect the report now, until effectUntil. pending: waiting for review. expired: it did, and no longer does. none: rejected, or a note that changes nothing.
sentAtdecidedAtstring
ISO 8601 times. decidedAt is null while the report is waiting.

An unknown id answers HTTP 404. The report's sender and note are never returned.

GET/healthz

Check 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

fields also 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. regionName and city are always in English. A value the API does not know falls back to English.
faststring
Set to 1 to answer from memory only. The API then skips live reverse DNS and registry queries and replies in a few milliseconds. reverse, hostname and whois are filled only when already cached, and org falls back to isp. Without fast, 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 null when 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
true when the vpn, proxy, tor, relay or residential score reaches 0.60. proxyType names 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, crawler or abuse.
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

MeasureResult
Country correct98.4%
Reported location within 25 km of the device58.8%
Within 50 km65.9%
Within 100 km72.5%
Within 250 km83.0%
Median distance from the device12 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

MeasureResult
Home connections wrongly flagged as a proxy or VPN0.1%
Home connections wrongly flagged as hosting2.3%
Office connections wrongly flagged as hosting5.1%
Data centre addresses recognised as hosting38.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.

messageMeaning
invalid queryThe query is not an IP address, and not a domain name that resolves.
private rangeA private or link-local address, such as 10.0.0.1, 192.168.1.1 or fe80::1.
reserved rangeLoopback, multicast, documentation or other reserved address space.
live lookup limit reachedA 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:

StatusMeaning
400The body is not valid JSON, a batch body is not an array, or a report is missing a required field.
404No such path.
405The path exists but does not accept this method. The Allow header lists the ones it does.
413The request body is larger than 256 kB.
422A batch has more than 100 items.
429Rate limit exceeded. See rate limits.
503The 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.

WhatLimitNotes
Requests100 a minuteEvery call to /json, /ip and /batch counts.
Batch1 per addressA batch of 40 addresses uses 40 of the 100.
Live lookups30 a minuteReverse 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.
Reports50 a dayEach 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.

Guide

Screen sign-ups

Hold an account for review when it is created through an anonymizer or from a data centre.

  1. Take the client's address from your own server. Never trust an address sent by the browser.
  2. Ask for the detection fields only.
  3. 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.

Guide

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.

Guide

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.

Guide

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.