Download the PHP package ipwhois/ipwhois-php without Composer
On this page you can find all versions of the php package ipwhois/ipwhois-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download ipwhois/ipwhois-php
More information about ipwhois/ipwhois-php
Files in ipwhois/ipwhois-php
Package ipwhois-php
Short Description Official PHP client for the ipwhois.io IP Geolocation API. Simple, dependency-free, supports single and bulk IP lookups.
License MIT
Homepage https://ipwhois.io
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package ipwhois-php
ipwhois-php
Official, dependency-free PHP client for the ipwhois.io IP Geolocation API.
- ✅ Single and bulk IP lookups (IPv4 and IPv6)
- ✅ Works with both the Free and Paid plans
- ✅ HTTPS by default
- ✅ Localisation, field selection, threat detection, rate info
- ✅ Never throws — all errors returned as
success: falsearrays - ✅ No external dependencies — only the cURL extension
- ✅ PHP 8.0+
Installation
Free vs Paid plan
The same IPWhois class is used for both plans. The only difference is whether
you pass an API key:
- Free plan — create the client without arguments. No API key, no signup required. Suitable for low-traffic and non-commercial use.
- Paid plan — create the client with your API key from https://ipwhois.io. Higher limits, plus access to bulk lookups and threat-detection data.
Everything else (lookup(), options, error handling) is identical.
Quick start — Free plan (no API key)
Quick start — Paid plan (with API key)
Get an API key at https://ipwhois.io and pass it to the constructor:
ℹ️ Pass nothing to look up your own public IP:
$ipwhois->lookup();— works on both plans.
Lookup options
Every option below can be passed per call, or set once on the client as a default.
| Option | Type | Plans needed | Description |
|---|---|---|---|
lang |
string | Free + Paid | One of: en, ru, de, es, pt-BR, fr, zh-CN, ja |
fields |
array | Free + Paid | Restrict the response to specific fields (e.g. ['country', 'city']) |
rate |
bool | Basic and above | Include the rate block (limit, remaining) |
security |
bool | Business and above | Include the security block (proxy/vpn/tor/hosting) |
Setting defaults once
Every option can be passed two ways: per call (as the second argument to
lookup() / bulkLookup()) or once as a default on the client. Per-call
options always override the defaults, so it's safe to set sensible defaults
and only override what differs for a specific call.
Defaults are set with fluent setters — setLanguage(), setFields(),
setSecurity(), setRate(), setTimeout(), setConnectTimeout(),
setUserAgent() — and can be chained:
Either client behaves the same way at call time — per-call options always win over the defaults:
⚠️ When you restrict fields with
setFields()(or the per-call'fields'option), the API only returns the fields you ask for. Always include'success'in the list if you rely on$info['success']for error checking — otherwise the field will be missing on responses.ℹ️
setSecurity(true)requires Business+ andsetRate(true)requires Basic+. See the table above for what's available where.
HTTPS Encryption
By default, all requests are sent over HTTPS. If you need to disable it (for
example, in environments without an up-to-date CA bundle), pass 'ssl' => false
to the constructor:
ℹ️ HTTPS is strongly recommended for production traffic — your API key is sent in the query string and would otherwise travel in clear text.
Bulk lookup (Paid plan only)
The bulk endpoint sends up to 100 IPs in a single GET request. Each address counts as one credit. Available on the Business and Unlimited plans.
ℹ️ Bulk requires an API key. Calling
bulkLookup()without one will fail at the API level.
Error handling
The library never throws. Every failure — invalid IP, bad API key, rate
limit, network outage, missing extension, bad options — comes back inside
the response array with success => false and a message. Just check
$info['success'] after every call:
This means an outage of the ipwhois.io API (or of your server's DNS, connection, etc.) will never surface as a fatal error in your application — you decide how to react.
Error response fields
Every error response contains success: false, a human-readable message,
and an error_type so you can branch on the category of the failure. Some
errors include extra fields you can branch on:
| Field | When it's present |
|---|---|
success |
Always — false for error responses (true for successful responses) |
message |
Always — human-readable description of what went wrong |
error_type |
Always — one of 'api', 'network', 'environment', or 'invalid_argument' |
http_status |
On HTTP 4xx / 5xx responses |
retry_after |
On HTTP 429 — free plan only (the paid endpoint does not send a Retry-After header) |
Response shape
A successful response includes (depending on your plan and selected options):
For the full field reference, see the official documentation.
An error response looks like:
Requirements
- PHP 8.0 or newer
- ext-curl
- ext-json
Contributing
Issues and pull requests are welcome on GitHub.
License
MIT © ipwhois.io
All versions of ipwhois-php with dependencies
ext-curl Version *
ext-json Version *