Introduction

Welcome to the iii.vg API documentation. This document provides details for various public APIs offered, primarily focusing on GeoIP lookup services.

Please review the "General Notes" for important information applicable to all APIs listed here, followed by details for specific endpoints.

General Notes

  • Authentication: All APIs listed here currently do not require authentication.
  • HTTPS Required: All API requests must be made over HTTPS. Requests made over plain HTTP will likely fail or be redirected.
  • Data Freshness: The GeoIP APIs (MaxMind, IP2Location) use the latest available data by default and are automatically updated when new database versions are released by their respective providers.
  • Rate Limiting: APIs may be subject to rate limiting to ensure fair usage and stability. See the "Rate Limiting" section for more details.

Rate Limiting

To ensure fair usage and stability of our services, API requests may be rate-limited. The specific limits can vary per API and are subject to change.

If you exceed the rate limit, you will likely receive an HTTP 429 Too Many Requests response. Response headers may include:

  • X-RateLimit-Limit: The total number of requests allowed in the current window.
  • X-RateLimit-Remaining: The number of requests remaining in the current window.
  • Retry-After or X-RateLimit-Reset: Information on when you can retry.

Please implement proper error handling in your application to manage rate limits gracefully.

Error Codes

Standard HTTP status codes are used. Common ones include:

Status Code Meaning
200 OKRequest successful.
400 Bad RequestInvalid request parameters or format.
404 Not FoundRequested resource or API path not found.
429 Too Many RequestsRate limit exceeded.
500 Internal Server ErrorServer-side error.

Error responses are typically in JSON format and include an "error" field with a descriptive message.

API Endpoints

GET maxmind.ip.api.iii.vg/

Provides GeoIP information for an IP address using MaxMind GeoLite2 databases. This service is automatically updated when new database drops occur.

Latest Database Set Details

The "Latest" option refers to the most current data (e.g., 2025-05-30 or newer).

Databases Included: GeoLite2-Country.mmdb, GeoLite2-ASN.mmdb, GeoLite2-City.mmdb

Query Parameters:

  • ip (string, required): The IP address to look up (e.g., 8.8.8.8).
  • database (string, optional): Specifies a database version.
    • Use latest for the most recent version. This is also the default behavior if the parameter is omitted.
    • Use YYYY-MM-DD format for an archived version. Select from dropdown below.

API Usage Examples:

Example API Call:

https://maxmind.ip.api.iii.vg?ip=8.8.8.8&database=latest

(Example URL will update based on dropdown selection. IP 8.8.8.8 used for demonstration.)

Response Example (200 OK for ?ip=8.8.8.8):

{
    "ip": "8.8.8.8",
    "country": { "iso_code": "US", "name": "United States" },
    "city": { "name": null, "latitude": 37.751, "longitude": -97.822 },
    "asn": { "number": 15169, "organization": "GOOGLE" },
    "error": null
}

If an error occurs, the error field will contain a description.

GET ip2locaton.api.iii.vg

Provides GeoIP information for an IP address, similar to IP2Location services. Uses latest data by default and is automatically updated.

Query Parameters:

  • ip (string, required): The IP address to look up (e.g., 1.1.1.1).

Usage Example:

https://ip2locaton.api.iii.vg?ip=1.1.1.1

Response Example (200 OK for ?ip=1.1.1.1):

{
    "ip": "1.1.1.1",
    "is_ipv6": false,
    "country": { "iso_code": "AU", "name": "Australia" },
    "region": { "name": "Queensland" },
    "city": { "name": "Brisbane", "latitude": -27.467541, "longitude": 153.028091 },
    "error": null
}

If an error occurs, the error field will describe the issue.