Get IP info API Documentation

API Overview

The IP Info API provides comprehensive information about IP addresses including geolocation, ISP details, timezone, and network information. Perfect for analytics, security, and user experience enhancement.

Base URL: https://hisham-zahid.online/api/v1/ip

Features

Automatic IP Detection: Detects visitor's real IP behind proxies and CDNs
IPv4 & IPv6 Support: Handles both IP versions seamlessly
Geolocation Data: Country, region, city, coordinates, and timezone
ISP Information: Internet service provider and organization details
Network Details: AS number and network information
Header Analysis: Relevant HTTP headers for debugging
Batch Lookup: Look up multiple IP addresses at once
Caching: Optimized performance with intelligent caching

Endpoints

1. Get Current Visitor IP Info

GET

/api/v1/ip

GET

/api/v1/ip/info

2. Batch IP Lookup

POST

/api/v1/ip/lookup

Parameters (for POST endpoint)

Parameter	Type	Required	Description
`ips`	array	Yes	Array of IP addresses to lookup (both IPv4 and IPv6 supported)

Response Format

{
  "ip": "203.0.113.1",
  "ipv4": "203.0.113.1",
  "ipv6": null,
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
  "timestamp": "2025-07-16T10:30:00.000Z",
  "headers": {
    "accept-language": "en-US,en;q=0.9",
    "cf-ipcountry": "US",
    "x-forwarded-for": "203.0.113.1"
  },
  "location": {
    "country": "United States",
    "country_code": "US",
    "region": "California",
    "city": "Los Angeles",
    "latitude": 34.0522,
    "longitude": -118.2437,
    "timezone": "America/Los_Angeles",
    "isp": "Example ISP Inc",
    "organization": "Example Organization",
    "as": "AS12345 Example AS Network",
    "query": "203.0.113.1"
  },
  "source": "ip-api.com"
}

Usage Examples

1. Get Current Visitor's IP Info

GET https://hisham-zahid.online/api/v1/ip

2. Alternative Endpoint

GET https://hisham-zahid.online/api/v1/ip/info

3. Batch IP Lookup

POST https://hisham-zahid.online/api/v1/ip/lookup
Content-Type: application/json

{
  "ips": ["8.8.8.8", "1.1.1.1", "2001:4860:4860::8888"]
}

4. JavaScript Example

// Get current visitor IP info
fetch('https://hisham-zahid.online/api/v1/ip')
  .then(response => response.json())
  .then(data => {
    console.log('IP:', data.ip);
    console.log('Location:', data.location.city, data.location.country);
    console.log('ISP:', data.location.isp);
  });

// Batch lookup
fetch('https://hisham-zahid.online/api/v1/ip/lookup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ips: ['8.8.8.8', '1.1.1.1']
  })
})
.then(response => response.json())
.then(data => console.log(data));

5. cURL Examples

# Get your IP info
curl https://hisham-zahid.online/api/v1/ip

# Batch lookup
curl -X POST https://hisham-zahid.online/api/v1/ip/lookup \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"]}'

Response Codes

200 Success

Request successful, IP information returned

400 Bad Request

Invalid request format or missing required parameters

{"error": "Please provide an array of IP addresses"}

422 Unprocessable Entity

Invalid IP address provided

{
  "ip": "invalid.ip.address",
  "error": "Invalid IP address"
}

500 Internal Server Error

Server error occurred while processing request

{"error": "Internal server error"}

Additional Information

IP Detection Priority

The API checks headers in the following order to find the real client IP:

CF-Connecting-IP: Cloudflare real IP
X-Forwarded-For: Load balancer/proxy IP
X-Real-IP: Nginx real IP
Client-IP: General proxy IP
Remote-Addr: Standard server IP

Response Fields

ip: The detected IP address
ipv4/ipv6: Separated IP versions (null if not applicable)
user_agent: Browser/client user agent string
timestamp: Request timestamp in ISO format
headers: Relevant HTTP headers for debugging
location: Comprehensive geolocation data
source: Data source provider

Supported IP Types

IPv4: Standard IPv4 addresses (e.g., 192.168.1.1)
IPv6: Full IPv6 addresses (e.g., 2001:4860:4860::8888)
Public IPs: Only public IP addresses return location data
Private IPs: Local/private IPs return "Unknown" for location fields

Data Sources

Location data is sourced from reliable IP geolocation providers:

Primary: ip-api.com (free tier with high accuracy)
Fallback: Graceful degradation with "Unknown" values
Caching: Results cached for 1 hour for performance

Privacy & Security

No Logging: IP addresses are not permanently stored
Rate Limiting: Recommended to implement on your end
HTTPS Only: All requests should use HTTPS
CORS Enabled: Can be called from browser applications

IP Info API Documentation