# Geolocation IP Tracker API

**Advanced IP geolocation tracking and detailed location information retrieval**

Developed by [RSK World](https://rskworld.in) | © 2026

---

## 📍 Overview

The Geolocation IP Tracker API is a sophisticated RESTful service that provides comprehensive location information based on IP addresses. This API offers detailed geolocation data including country, region, city, ISP, timezone, and more with high accuracy.

## ✨ Features

- 🌍 **IP-based geolocation** - Track any valid IP address worldwide
- 🏙️ **Country and city data** - Get detailed location information
- 🌐 **ISP information** - Identify Internet Service Providers
- ⏰ **Timezone detection** - Get timezone and offset data
- 📱 **Mobile detection** - Identify mobile connections
- 🔒 **Proxy detection** - Detect proxy and VPN usage
- 📊 **Bulk lookup** - Process multiple IPs in a single request
- 💾 **Built-in caching** - Optimized performance with smart caching
- 🔧 **CORS support** - Ready for web applications
- 📖 **Comprehensive documentation** - Detailed API documentation

## 🚀 Quick Start

### Prerequisites

- PHP 7.4 or higher
- cURL extension enabled
- Web server (Apache, Nginx, or PHP built-in server)

### Installation

1. Clone or download the project files to your web server directory
2. Ensure the `cache/` directory is writable by the web server
3. Access the API through your web browser or API client

### Basic Usage

```bash
# Get location for current IP
curl "http://your-domain.com/geolocation-ip-tracker/index.php"

# Get location for specific IP
curl "http://your-domain.com/geolocation-ip-tracker/index.php?ip=8.8.8.8"

# Bulk lookup
curl -X POST "http://your-domain.com/geolocation-ip-tracker/index.php/bulk" \
     -H "Content-Type: application/json" \
     -d '{"ips": ["8.8.8.8", "1.1.1.1"]}'
```

## 📚 API Documentation

### Endpoints

#### Get IP Location
```
GET /index.php?ip={ip_address}
```

**Parameters:**
- `ip` (optional): IP address to lookup. If not provided, uses client's IP.

**Response:**
```json
{
    "success": true,
    "data": {
        "status": "success",
        "country": "United States",
        "countryCode": "US",
        "region": "CA",
        "regionName": "California",
        "city": "Mountain View",
        "district": null,
        "zip": "94043",
        "lat": 37.4056,
        "lon": -122.0775,
        "timezone": "America/Los_Angeles",
        "offset": -25200,
        "isp": "Google LLC",
        "org": "Google LLC",
        "as": "AS15169 Google LLC",
        "asname": "GOOGLE",
        "mobile": false,
        "proxy": false,
        "hosting": true,
        "query": "8.8.8.8"
    },
    "timestamp": "2026-03-08 17:30:45",
    "api_info": {
        "provider": "ip-api.com",
        "version": "1.0",
        "developer": "RSK World",
        "website": "https://rskworld.in",
        "year": "2026"
    }
}
```

#### Bulk IP Lookup
```
POST /index.php/bulk
```

**Request Body:**
```json
{
    "ips": ["8.8.8.8", "1.1.1.1", "208.67.222.222"]
}
```

## 🛠️ Technologies Used

- **Backend**: PHP 7.4+
- **API Style**: RESTful
- **Data Format**: JSON
- **External Service**: ip-api.com
- **Caching**: File-based caching system
- **Frontend**: HTML5, CSS3, JavaScript, Bootstrap 5
- **Icons**: Font Awesome 6

## 📱 Demo

A fully functional demo is available at:
```
http://your-domain.com/geolocation-ip-tracker/demo.php
```

The demo includes:
- Interactive IP lookup interface
- Real-time location display
- API endpoint examples
- Responsive design for all devices

## 📖 Documentation

Comprehensive API documentation is available at:
```
http://your-domain.com/geolocation-ip-tracker/index.php/docs
```

The documentation includes:
- Detailed endpoint descriptions
- Code examples in multiple languages
- Error handling guide
- Rate limiting information

## 🔧 Configuration

### Cache Settings

Cache duration can be modified in `index.php`:
```php
private $cacheExpiry = 3600; // 1 hour in seconds
```

### Rate Limiting

Current rate limits:
- **Free Tier**: 100 requests per minute
- **Bulk Requests**: Maximum 50 IP addresses per request
- **Cache Duration**: 1 hour

## 📊 Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `query` | string | The IP address that was looked up |
| `country` | string | Country name |
| `countryCode` | string | ISO 3166-1 alpha-2 country code |
| `region` | string | Region/state code |
| `regionName` | string | Region/state name |
| `city` | string | City name |
| `district` | string | District name (if available) |
| `zip` | string | ZIP/postal code |
| `lat` | float | Latitude |
| `lon` | float | Longitude |
| `timezone` | string | Timezone identifier |
| `offset` | integer | UTC offset in seconds |
| `isp` | string | Internet Service Provider name |
| `org` | string | Organization name |
| `as` | string | AS number and organization |
| `asname` | string | AS organization name |
| `mobile` | boolean | Mobile connection detected |
| `proxy` | boolean | Proxy/VPN detected |
| `hosting` | boolean | Hosting/datacenter detected |

## 🚨 Error Handling

The API returns appropriate HTTP status codes and error messages:

| Status Code | Error Message | Description |
|-------------|---------------|-------------|
| 400 | Invalid IP address provided | The IP address format is invalid |
| 404 | Endpoint not found | The requested API endpoint doesn't exist |
| 405 | Method not allowed | HTTP method is not supported |
| 500 | Failed to fetch geolocation data | External service error |

## 🔒 Security Features

- Input validation for IP addresses
- Private IP address filtering
- CORS headers for web applications
- Error message sanitization
- Rate limiting protection

## 🌐 Browser Support

The demo interface supports all modern browsers:
- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## 📝 Code Examples

### JavaScript
```javascript
// Get location for specific IP
fetch('/index.php?ip=8.8.8.8')
    .then(response => response.json())
    .then(data => {
        if (data.success) {
            console.log('Location:', data.data);
        } else {
            console.error('Error:', data.error);
        }
    });
```

### PHP
```php
<?php
$ip = '8.8.8.8';
$response = file_get_contents("/index.php?ip=$ip");
$data = json_decode($response, true);

if ($data['success']) {
    echo "Country: " . $data['data']['country'];
} else {
    echo "Error: " . $data['error'];
}
?>
```

### Python
```python
import requests

response = requests.get('/index.php?ip=8.8.8.8')
data = response.json()

if data['success']:
    print(f"Country: {data['data']['country']}")
    print(f"City: {data['data']['city']}")
else:
    print(f"Error: {data['error']}")
```

## 🤝 Contributing

This project is developed and maintained by RSK World. For contributions, suggestions, or bug reports:

📧 **Email**: help@rskworld.in  
📞 **Phone**: +91 93305 39277  
🌐 **Website**: https://rskworld.in

## 📄 License

This project is part of RSK World's educational resources. Content is used for educational purposes only.

## 👥 Team

- **Founder**: Molla Samser
- **Designer & Tester**: Rima Khatun
- **Development**: RSK World Team

## 📍 Contact

**RSK World**  
Nutanhat, Mongolkote  
Purba Burdwan, West Bengal  
India, 713147  

📧 **Email**: help@rskworld.in, support@rskworld.in  
📞 **Phone**: +91 93305 39277  
🌐 **Website**: https://rskworld.in

---

© 2026 RSK World. All rights reserved. | Content for educational purposes only.
