IPAPI.GR Documentation

Welcome to the IPAPI.GR documentation. This guide will help you understand how to use our IP address lookup service effectively.

Getting Started

Welcome to the IPAPI.GR documentation. This guide will help you understand how to use our IP address lookup service effectively.

GET /api/lookup/:input

Replace :input with either an IP address (IPv4 or IPv6) or a domain name you want to look up.

Note: All requests must include an API key. Free users can sign up to get an API key with basic features, while pro users get access to additional risk assessment data.

Authentication

All API requests require authentication using an API key. Provide your API key as a query parameter:

QUERY ?key=your_api_key_here

Note: The API key must be provided as a query parameter in all requests.

API Key Types

Free API Key: Basic IP lookup features with standard rate limits
pro API Key: Includes risk assessment data and higher rate limits

API Endpoints

IP or Domain Lookup

GET /api/lookup/:input

Examples

IP Lookup: /api/lookup/8.8.8.8?key=YOUR_API_KEY
Domain Lookup: /api/lookup/google.com?key=YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
input	string	Yes	IPv4 address, IPv6 address, or domain name to look up
key	string	Yes	Your API key (provided as ?key=YOUR_API_KEY)
dev	boolean	No	Include maintenance information in response

Response

{
    "ip": "8.8.8.8",
    "country": "United States",
    "city": "Mountain View",
    "region": "California",
    "latitude": 37.436551599813335,
    "longitude": -122.09383799087185,
    "timezone": "America/Los_Angeles",
    "isp": "Google LLC",
    "organization": "Google LLC",
    "asn": "15169",
    "zipcode": "94043",
    "timestamp": "2025-05-13T08:29:59.370Z"
}

pro Features

Pro users receive additional risk assessment data in their responses:

{
    // ... standard fields ...
    "risk": {
        "is_mobile": false,
        "is_vpn": false,
        "is_tor": false,
        "is_proxy": false,
        "is_datacenter": true,
        "risk_score": 0
    }
}

Developer Mode

Add &dev to your request URL to include maintenance information:

{
    // ... standard fields ...
    "maintenance": {
        "status": "success",
        "ip": "8.8.8.8",
        "cache_hit": true,
        "cache_expires_in": "15h 05m 53s",
        "expires_at": "2025-05-20T19:37:32.441Z",
        "time_to_resolve": "1ms"
    }
}

Note: The maintenance information is only included when the &dev parameter is present in the request URL. For uncached responses, it will also include the list of datasheets used.

API Status

GET /api/status

Check your API key status, rate limits, and usage statistics.

Parameters

Parameter	Type	Required	Description
key	string	Yes	Your API key (provided as ?key=YOUR_API_KEY)

Response

{
    "status": "success",
    "data": {
        "authenticated": true,
        "plan": "pro",
        "rateLimit": {
            "limit": 100000,
            "window": "24h",
            "remaining": 9850,
            "reset": "2025-05-10T08:13:18.601Z",
            "used": 150,
            "percentage": 1
        }
    }
}

Note: The response includes your current plan type, rate limit details, and usage statistics. Use this endpoint to monitor your API usage and plan status.

Free Plan Example

{
    "status": "success",
    "data": {
        "authenticated": true,
        "plan": "free",
        "rateLimit": {
            "limit": 1000,
            "window": "24h",
            "remaining": 850,
            "reset": "2025-05-10T08:13:18.601Z",
            "used": 150,
            "percentage": 15
        }
    }
}

Error Response

{
    "status": "error",
    "code": 401,
    "message": "Invalid API key",
    "details": "The provided API key is invalid or has expired.",
    "timestamp": "2025-05-20T08:04:52.790Z"
}

Tip: Use this endpoint to monitor your API usage and ensure you're within your rate limits. The response includes the number of requests remaining and when your limit will reset.

Developer Mode

Add &dev to your request URL to include additional debugging information:

{
    "status": "success",
    "data": {
        "authenticated": true,
        "plan": "pro",
        "rateLimit": {
            "limit": 100000,
            "window": "24h",
            "remaining": 9850,
            "reset": "2025-05-10T08:13:18.601Z",
            "used": 150,
            "percentage": 1
        },
        "maintenance": {
            "status": "success",
            "cache_hit": true,
            "time_to_resolve": "1ms"
        }
    }
}

Note: The maintenance information is only included when the &dev parameter is present in the request URL.

IP or Domain Lookup

GET /api/lookup/:input

Examples

IP Lookup: /api/lookup/8.8.8.8?key=YOUR_API_KEY
Domain Lookup: /api/lookup/google.com?key=YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
input	string	Yes	IPv4 address, IPv6 address, or domain name to look up
key	string	Yes	Your API key (provided as ?key=YOUR_API_KEY)
dev	boolean	No	Include maintenance information in response

Response

{
    "ip": "8.8.8.8",
    "country": "United States",
    "city": "Mountain View",
    "region": "California",
    "latitude": 37.436551599813335,
    "longitude": -122.09383799087185,
    "timezone": "America/Los_Angeles",
    "isp": "Google LLC",
    "organization": "Google LLC",
    "asn": "15169",
    "zipcode": "94043",
    "timestamp": "2025-05-13T08:29:59.370Z"
}

pro Features

Pro users receive additional risk assessment data in their responses:

{
    // ... standard fields ...
    "risk": {
        "is_mobile": false,
        "is_vpn": false,
        "is_tor": false,
        "is_proxy": false,
        "is_datacenter": true,
        "risk_score": 0
    }
}

Developer Mode

Add &dev to your request URL to include maintenance information:

{
    // ... standard fields ...
    "maintenance": {
        "status": "success",
        "ip": "8.8.8.8",
        "cache_hit": true,
        "cache_expires_in": "15h 05m 53s",
        "expires_at": "2025-05-20T19:37:32.441Z",
        "time_to_resolve": "1ms"
    }
}

Note: The maintenance information is only included when the &dev parameter is present in the request URL. For uncached responses, it will also include the list of datasheets used.

Rate Limiting

API requests are rate-limited to prevent abuse. The current limits are:

10,000 requests per day for pro users
1,000 requests per day for free users

Note: Rate limits are enforced per API key. Exceeding the limit will result in a 429 Too Many Requests error. The limits reset every 24 hours.

Caching

Our API implements caching to improve performance and reduce load on our servers:

IP lookup results are cached for 24 hours
Domain lookups are cached for 24 hours (both the domain and its resolved IP)
Cache hits are served instantly
Cache misses trigger a fresh lookup from multiple datasheets
Pro users receive risk data in cached responses
Free users receive cached data without risk information

Note: Cached results may not reflect recent changes in IP data. The cache expiration time is shown in the maintenance information when using the &dev parameter.

Error Handling

All errors follow a consistent format:

{
    "status": "error",
    "code": 400,
    "message": "Domain resolution failed",
    "details": "Domain \"example.com\" does not exist. Please check if the domain name is correct.",
    "timestamp": "2025-05-20T08:04:52.790Z"
}

Common Error Codes

400 - Bad Request (Invalid input or domain resolution failed)
401 - Unauthorized (Invalid API key)
429 - Too Many Requests (Rate limit exceeded)
500 - Internal Server Error

Note: All error responses include a timestamp and may include maintenance information if the &dev parameter is present.

Best Practices

Follow these best practices to get the most out of our API:

Always provide your API key as a query parameter (?key=YOUR_API_KEY)
Implement proper error handling in your application
Cache results on your end when possible
Monitor your rate limit usage
Use the &dev parameter during development to monitor cache status
Consider upgrading to pro for access to risk assessment data
Handle both IPv4 and IPv6 addresses in your application
Implement retry logic with exponential backoff for failed requests
When using domain lookups, handle cases where the domain might not resolve
Consider implementing DNS caching for frequently looked-up domains

Tip: Consider implementing a fallback mechanism for when the API is unavailable.

Support

If you need help or have questions, you can:

Visit your dashboard for usage statistics and API key management
Email us at [email protected]
Check our documentation for detailed information

Note: For urgent issues, please include your API key and relevant request details in your support email.