InternetData Python Client Library
The official Python client library for the InternetData API.
It tells you what every InternetData database says about an IP address, an AS or a domain: where it is, who runs it, whether it is a VPN, proxy, Tor node or hosting server, and what it serves. It also downloads the databases your organization is licensed for.
Getting Started
pip install internetdata
Requires Python 3.11 or newer. Type hints are included, and the package ships py.typed.
Usage
No API key needed to start. Unlimited, the free plan, answers location, asn, company, abuse and every flag but the VPN, proxy, hosting and CDN ones, limited per address per minute, with a key or without one.
from internetdata import InternetData
client = InternetData()
result = client.lookup("146.70.116.130")
print(result.location.country) # 'AT'
print(result.asn.name) # 'M247 Europe SRL'
print(result.company.name) # who uses the address
The client holds an HTTP connection pool, so use it as a context manager, or call client.close() when you are done with it:
with InternetData() as client:
print(client.lookup("146.70.116.130").asn.name)
With an API key
Every paid plan answers every field: the VPN, proxy, hosting and CDN flags, the detail behind each flag, the city, the Whois records and more. The plans differ only in how many lookups they include, and a free account tries every field, 100 lookups a day. Create a key in the console, then pass it in:
import os
client = InternetData(os.environ["INTERNETDATA_API_KEY"])
result = client.lookup("146.70.116.130")
print(result.is_vpn) # True, on a paid plan
print(result.vpn.provider) # 'mullvad', on a paid plan
print(result.location.city) # 'Vienna', on a paid plan
Async
Everything above works the same way under asyncio, with AsyncInternetData:
import asyncio
from internetdata import AsyncInternetData
async def main():
async with AsyncInternetData() as client:
result = await client.lookup("146.70.116.130")
print(result.asn.name) # 'M247 Europe SRL'
asyncio.run(main())
Your own address
result = client.my_ip()
print(result.ip) # the address we saw this call come from
Same answer lookup would give for that address, and the same cost against your allowance. It is deliberately not cached: which address you are is the whole question, and a machine that moves between networks would otherwise be told where it used to be.
Your plan and usage
acct = client.my_entitlement()
print(acct.plan.key) # starter
print(acct.plan.name) # Starter, the name to show
print(acct.usage.requests) # 580
print(acct.usage.window_end) # when the allowance resets
Usage counts against the anniversary of your subscription on a paid plan, not the calendar month and not the billing period, and against the UTC day on the free plan; it is the same number a lookup is gated on. hard_limit is None on an uncapped plan, which is not the same as zero.
Both are on the async client too: await client.my_ip() and await client.my_entitlement().
Batch lookup
Look up as many addresses as you like at once. Bogons and cached answers are handled locally, and everything else goes to the batch endpoint in chunks of up to 1000 addresses, in parallel. The batch endpoint needs a paid plan:
results = client.lookup_batch(["146.70.116.130", "8.8.8.8", "1.1.1.1"])
for ip, result in results.items():
if isinstance(result, Exception):
print(f"{ip}: {result}")
continue
print(f"{ip}: {result.is_vpn}")
Results are keyed by address, in the order you first listed each one, so duplicates in your list collapse into a single entry and one address failing never loses the rest: it carries its error as its value, with the status the API would have given that address on its own.
How many chunks are in flight at once, how many times a failed chunk is retried and how long each request may take are configurable per call:
results = client.lookup_batch(many_ips, concurrency=4, retries=4, timeout=30)
Caching
Answers are cached by default, so repeat lookups of the same address are free:
client = InternetData()
result = client.lookup("146.70.116.130")
print(result.asn.name) # API request
result2 = client.lookup("146.70.116.130")
print(result2.asn.name) # no API request, result was cached
You can change the default cache variables (max size, TTL in seconds, etc) on initialization, or even disable it:
client = InternetData(cache_max_size=50_000, cache_ttl=6 * 60 * 60)
client_no_cache = InternetData(cache=False)
An answer with trial_expired or cap_reached true is cached for a minute at most, so a new day's trial or a raised cap reaches you within a minute.
Private and reserved addresses
Private, loopback, link-local, documentation and multicast addresses (and their IPv6 equivalents, including the 6to4 and Teredo ranges) are in no database. The library answers them locally, so they cost no request and no quota:
result = client.lookup("192.168.1.1")
result.is_bogon # True
result.is_vpn # False
The answer has the shape the API gives a bogon on a paid plan, whatever your plan, so don't read your plan off it. The check is available on the client, which is handy when your inputs are addresses anyway:
client.is_bogon("10.0.0.1") # True
client.is_bogon("8.8.8.8") # False
It is also importable on its own, if you want it without a client:
from internetdata import is_bogon
is_bogon("10.0.0.1") # True
AS and domain lookups
asn = client.lookup_asn(9009)
print(asn.name, asn.registry) # M247 Europe SRL ripe
domain = client.lookup_domain("example.com")
print(domain.is_registered, domain.has_mx) # True True
On a paid plan an AS answer also carries its Whois record, its counts, every prefix it announces, its rank, Tier 1 flag, upstreams, peers and downstreams, and the domains it hosts, and a domain answer its DNS records, its organization's IP ranges and is_disposable. Neither is cached, and neither goes through the batch. lookup takes addresses alone, and refuses an AS or a domain with a bad_request before sending anything.
Errors
Failures raise an InternetDataError carrying a kind and a retryable flag:
from internetdata import InternetDataError
try:
client.lookup("1.1.1.1")
except InternetDataError as err:
print(err.kind, err.retryable, err.message)
kind is one of bad_request, unauthorized, forbidden, rate_limited, quota_exceeded, server_error or network. message is the API's own: a lookup's error message, or a database call's result code, passed through as it was sent, so you can switch on NOT_LICENSED against LICENSE_EXPIRED without reading the status.
A request that runs past its timeout fails with network, and is retried like any other network failure. The default is 30 seconds per attempt, body included, so a retried call can take longer in total. A database transfer is exempt, so download and download_bytes are never cut off part way through a large file. Set it on the client, or on a single lookup, lookup_asn, lookup_domain, my_ip, my_entitlement, lookup_batch, oauth or database call (transfers aside), in seconds:
client = InternetData(timeout=10)
result = client.lookup("146.70.116.130", timeout=2)
None means no bound on the client, and the client's own on a call. Anything else that is not a number greater than 0 raises ValueError where it is set, before any request is made.
Changed in 2.1.0: the default was 10 seconds, and it bounded each read of a response rather than the whole attempt, so a response trickling in slowly could run past it for as long as the server kept sending.
Changed in 2.2.0: a timeout of 0 or less, NaN or a string used to be accepted, and failed every call.
Note that rate_limited and quota_exceeded both arrive as HTTP 429 and are not the same thing. A rate limit carries Retry-After, and retrying after it works: Unlimited's per-minute limit is one. One without it is quota_exceeded. The library retries rate limits for you, but not quota_exceeded, and nothing else you sent either. The API itself always sends Retry-After with a 429, so that one comes from something in between, such as a proxy; a paid key past its overage cap gets cap_reached instead.
Database downloads
Every database call needs an API key carrying the db.download scope. Create one in the console, then:
import os
from internetdata import InternetData
client = InternetData(os.environ["INTERNETDATA_API_KEY"])
for family in client.database.list():
print(family.base, family.standing, [v.id for v in family.versions])
The catalog
list answers database FAMILIES. A license is held against a family, while a download names a specific version, so the IDs the other calls take come from each family's versions:
for family in client.database.list():
if family.standing != "licensed":
continue
for version in family.versions:
print(version.id, version.formats) # 'bogon_ip_v1' ('csvgz', 'mmdb')
standing is licensed, expired or unlicensed, and license_type is what your license lets you do with the data (evaluation, standard, redistribute, or None when there is no license). A family you have never bought is still listed, as unlicensed, so you can see what else exists.
A rolling license also carries renews_at, when it next renews, and notice_due_at, the last day you can give notice of non-renewal for that term. Both are None when there is no license, when it has no defined term, or when expires sets a hard stop instead. DATABASE_FORMATS, STANDINGS and LICENSE_TYPES hold the published values at runtime, for checking one that came from a flag or a form before you make a call.
What is inside a build
metadata is cheap enough to poll. It answers when the build was generated, how many rows it has, its columns and a few real rows, and the size of each format in bytes, all without moving the file:
meta = client.database.metadata("bogon_ip_v1")
print(meta.updated) # datetime.date(2026, 9, 4)
print(meta.entries) # 1234
print(meta.size["csvgz"]) # 760
print([c.name for c in meta.schema["csvgz"]])
Checking size before a download is worth the round trip: the catalog spans a few hundred bytes to several gigabytes.
Downloading
Three ways, depending on what you want to do with the bytes:
url = client.database.download_url("bogon_ip_v1", "csvgz")
raw = client.database.download_bytes("bogon_ip_v1", "csvgz")
written = client.database.download("bogon_ip_v1", "mmdb", "./bogon_ip_v1.mmdb")
download_url hands back a time-limited link straight to object storage. It carries its own signature and none of your API key, so you can pass it to curl, a job runner or anything else that speaks HTTP. The link only has to be valid when a transfer starts, so one already running isn't cut off when it lapses.
download streams to a file, so nothing larger than a chunk is ever held in memory. The bytes land in a neighboring .part file that is moved into place only once the whole transfer has arrived, so a failed refresh leaves the copy you already had untouched. download_bytes holds the whole file in memory, so reach for it only at the small end of the catalog.
Either way a short transfer fails rather than handing you a truncated file, and the key is never sent to object storage.
Each of the three downloads the build that is live unless you name one. A database.updated webhook names the build it announces and carries its sha256, so a receiver that downloads after the next publish asks for that build to get the file the hash is of:
client.database.download("vpn_ip_v1", "mmdb", "./vpn_ip_v1.mmdb", build=event["data"]["build"])
A build is kept 7 days. Past that the call raises bad_request with the message BUILD_GONE, and downloading without build fetches the live one.
Verify what you fetched against the published digests:
import hashlib
digests = client.database.checksums("bogon_ip_v1", "csvgz")
assert hashlib.sha256(raw).hexdigest() == digests["sha256"]
Download history
downloads answers your organization's recent attempts, newest first, refusals included. A denial is what answers "it stopped working", and its absence answers nothing:
for attempt in client.database.downloads(limit=20):
print(attempt.created, attempt.dataset_id, attempt.outcome, attempt.http_status)
From 2.3.0, list, metadata, checksums, downloads and download_url each take a keyword-only timeout in seconds, bounding each attempt at that one call in place of the client's; None there means the client's own rather than no bound. download and download_bytes deliberately take none and raise TypeError if handed one, rather than accepting it and quietly doing nothing: a transfer runs to gigabytes and minutes, so any bound that suits a JSON call would abandon a healthy download. download_url does take one, because minting the link is an ordinary API request - it bounds that request, not whatever you do with the link afterwards:
catalog = client.database.list(timeout=2)
InternetData's database API has no quota, so you won't see quota_exceeded from it.
Sign in with OAuth (device flow)
A program running on someone's own machine can let them sign in with a browser and pick one of their API keys, instead of asking them to paste it:
from internetdata import InternetData
with InternetData() as signin:
device = signin.oauth.device_authorization(
"your-client-id", scope="account.read apikeys.read apikeys.reveal"
)
print(f"Open {device.verification_uri} and enter {device.user_code}")
tokens = signin.oauth.poll_device_token("your-client-id", device)
if tokens.apikey is None:
raise SystemExit("No API key was picked")
client = InternetData(tokens.apikey)
A refusal raises OauthAccessDeniedError and a code that ran out raises OauthExpiredTokenError. client.oauth.revoke("your-client-id", tokens.refresh_token) signs the machine out. Only a client we registered, such as our CLI, can use the device flow: an app of your own signs people in with the authorization code flow below.
Sign in with OAuth (authorization code)
An app that can take a browser redirect signs the person in there instead, with a PKCE pair made for that one sign-in:
from internetdata import InternetData
signin = InternetData()
redirect_uri = "http://127.0.0.1:8765/callback"
pkce = signin.oauth.create_pkce()
url = signin.oauth.authorization_url(
"your-client-id", redirect_uri, pkce.challenge, scope="apikeys.use", state="your-state"
)
# Open url in the browser. Its redirect to redirect_uri carries code and state.
tokens = signin.oauth.exchange_authorization_code("your-client-id", code, pkce.verifier, redirect_uri)
Check that state came back as you sent it before you exchange code, which works once. The client ID can also be the https URL of a client metadata document your app serves, and such an app is never handed a key, so tokens.apikey stays None.
Register a client
An app with no client ID, and no client metadata document to use as one, registers itself, then signs in with the client_id it gets back as the client ID for authorization_url and exchange_authorization_code:
client = InternetData()
registration = client.oauth.register(
["http://127.0.0.1:8765/callback"], client_name="Your App"
)
Each redirect URI must be https on a public host name, or http on a loopback address, which then matches any port. Nothing is kept until a person approves the client, so an app with no client ID saved can simply register again.
Fields your plan does not include
Unlimited leaves out the VPN, proxy, hosting and CDN flags, the detail behind every flag but Tor's and relay's, the city and region, the Whois records and the hosted domains; a free-plan key's answer carries trial_expired, true once its daily trial is spent. A paid key's carries cap_reached, true once its organization's overage cap is reached, when the answer has Unlimited's fields and isn't billed. Those are None when your key does not include them, which means "not in your plan" rather than "checked, and no", inside location, asn, company and abuse too.
result.flagged("is_hosting") # False rather than None on a plan without it
result.is_hosting is None # True on Unlimited: not in your plan
result.location.city is None # True on Unlimited
result.trial_expired is True # a free-plan key's daily trial is spent
result.cap_reached is True # a paid key is past its overage cap
Other Libraries
There are official InternetData client libraries available for many languages including PHP, Python, Go, Java, and Ruby. See our GitHub at https://github.com/internetdata for more.
About InternetData
Geolocation, anonymity, ownership and network data for IP addresses, AS numbers and domains, through an API or as database files you download and query yourself.
License
This project is licensed under the MIT License.
Metadata
Release files for internetdata 2.15.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| internetdata-2.15.2.tar.gz | 225.9 kB | With provenance | Details for internetdata-2.15.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| internetdata-2.15.2-py3-none-any.whl | Python 3 | none | any | Details for internetdata-2.15.2-py3-none-any.whl |
Total release size: 427.7 kB
Release files / internetdata-2.15.2.tar.gz
| Download URL | internetdata-2.15.2.tar.gz |
|---|---|
| Size | 225.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
00e252068e5c03071e85408fcfc7987f4029d6a3187c2f6e9cc5162232870ac8
|
|
BLAKE2b-256 checksum How to use checksums |
fd51884ab16f07a0431d6b88353d0a8d4054b5e6ecf454a6f36c72c8de52a6f4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / internetdata-2.15.2-py3-none-any.whl
| Download URL | internetdata-2.15.2-py3-none-any.whl |
|---|---|
| Size | 201.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
157b996e7eed61a4d677d79519d2ab7c2949bde908ee0a7ff4a319202ea31950
|
|
BLAKE2b-256 checksum How to use checksums |
137967907fb22db344f2245d42b42bfa2e0c2e7858f8db6d1ab7508e1d35078d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for internetdata 2.15.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for internetdata-2.15.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.