IP2Location.io provides various APIs to look up geolocation, network, mobile, proxy and WHOIS data for IP addresses and domain names.
This repository contains the API definitions in the OpenAPI Specification format, one definition per API, in both JSON and YAML.
| API | Endpoint | Definition |
|---|---|---|
| IP Geolocation | https://api.ip2location.io |
IPGeolocation |
| Bulk IP Geolocation | https://bulk.ip2location.io |
BulkIPGeolocation |
| Domain WHOIS | https://api.ip2whois.com/v2 |
DomainWHOIS |
| Hosted Domain | https://domains.ip2whois.com/domains |
HostedDomain |
Each definition covers the full request surface: authentication, every query parameter with its allowed values, request and response examples for each plan, the complete response schema with field descriptions, and the documented error responses.
API definitions in this repository are organized into two sub-folders:
/json – Definition files in the json format.
/yaml – Definition files in the yaml format.
Both folders contain the same four definitions. The JSON files are the source of truth; the YAML files mirror them, and CI checks that the two stay in sync. Use whichever format your tooling prefers.
Send your API key as a Bearer token in the Authorization header:
curl -H "Authorization: Bearer {YOUR_API_KEY}" "https://api.ip2location.io/?ip=8.8.8.8"
The key query parameter is also supported as an alternative:
curl "https://api.ip2location.io/?key={YOUR_API_KEY}&ip=8.8.8.8"
The IP Geolocation API can be called without a key, limited to 1,000 queries per day per client IP. The Domain WHOIS and Hosted Domain APIs require a key, and the Bulk IP Geolocation API requires a paid plan. Sign up for a free key at ip2location.io.
The IP Geolocation, Domain WHOIS and Hosted Domain APIs return JSON by default and also support XML with format=xml. The Bulk IP Geolocation API returns JSON by default and supports CSV with format=csv.
Responses are plan-dependent: the Free, Starter, Plus and Security plans return progressively more fields. Every response field is therefore optional in the schemas, except the fields that identify the result, such as ip or domain. The IP Geolocation definition includes one example response per plan.
Failed requests return an error object with a numeric code and a message:
{
"error": {
"error_code": 10001,
"error_message": "Invalid IP address."
}
}Each definition lists the error codes it can return, mapped to their HTTP status codes and grouped as response examples. An exhausted query allowance returns HTTP 401 with error code 10000; the API does not use 429 or rate-limit headers.
Postman supports importing OpenAPI definitions to create an API collection.
- Open Postman and select Import.
- Choose File and upload a definition from this repository's
json/oryaml/directory. - Review the imported requests and configure the required API key and parameters.
- Select an operation and send a test request.
See the Postman guide to importing API specifications for more information.
You can also use Swagger Editor to inspect an OpenAPI definition:
- Open Swagger Editor.
- Paste or import the contents of a JSON or YAML definition file.
- Review the operations, parameters, schemas, and any validation messages.
Swagger Editor is useful for exploring a definition before integrating it into an application. Its displayed operations and authentication requirements are determined by the imported file.
Redocly provides tools for viewing, validating, and publishing OpenAPI reference documentation.
- Choose a definition from the
json/oryaml/directory. - Open the file using a Redocly tool that supports the specification version.
- Browse the endpoints, request parameters, authentication requirements, response schemas, and examples.
Compatibility: These repository definitions use OpenAPI 3.2.0. Check that your Redocly tool or version supports OpenAPI 3.2 before importing them.
OpenAPI-compatible tools may support generating client code, producing reference documentation, or validating specifications. Download the appropriate definition and follow the instructions for your chosen tool.
Note: Generated clients and documentation depend on the capabilities of the tool and the contents of the selected specification. Review and test generated code before using it in production.
IP2Location.io offers IP intelligence services with features and query limits that vary by API and subscription plan.
- API key: Configure credentials as required by the operation or imported specification. Do not commit real keys to source control.
- Keyless access: Certain IP geolocation REST requests may support keyless access; this does not imply that every operation in the repository works without authentication.
- Plan-dependent fields: Not all response fields are available on every subscription plan or for every IP address.
- Rate limits and quotas: Check the current API pricing and plans before building high-volume workflows.
See the official API documentation for current authentication parameters and service behavior.
| Use case | How the definitions help |
|---|---|
| API testing | Import operations into Postman and test requests and responses. |
| API exploration | Inspect parameters and response schemas before writing integration code. |
| Client development | Use compatible OpenAPI tools as a starting point for generated clients. |
| API documentation | Render supported definitions in an OpenAPI documentation viewer. |
| Integration review | Compare application requests against the documented API contract. |
| Issue | Suggested action |
|---|---|
| A definition fails to import | Try the alternate JSON/YAML representation and inspect the tool's validation message. |
| An operation is missing | Confirm that you imported the definition for the intended API. |
| Authentication fails | Check the API key and the authentication configuration for that operation. |
| The response contains fewer fields than expected | Confirm your API plan and whether the queried IP has data for those fields. |
| A generated client fails | Check the generator's OpenAPI support and review the generated request and authentication handling. |
If you believe a specification is incorrect, open an issue with the filename, operation, expected behavior, and observed behavior.
| Product | Purpose |
|---|---|
| IP2Location.io | Hosted IP geolocation, ASN, and network intelligence APIs. |
| IP2Location LITE | Free downloadable IP geolocation and ASN databases for offline use. |
| IP2Location Database | Commercial offline IP geolocation databases. |
| IP2Proxy | IP proxy, VPN, TOR and anonymizer intelligence. |
| IP2WHOIS | Domain WHOIS lookup services. |
Licensed under the MIT License. See LICENSE.