API Documentation

Complete guide to integrating the IP Geolocation API into your applications

Contents

Getting Started

Welcome to the AEU GeoIP! This self-hosted service provides fast and accurate IP geolocation data using MaxMind GeoLite2 databases.

Quick Start: To get started, you'll need an API key. Contact your administrator to obtain one with appropriate access permissions and rate limits.

Base URL

http://ip.aeu-app.com

Authentication

All API endpoints (except /health) require authentication using an API key. You can provide your API key in two ways:

Method 1: Query Parameter

Include the API key as a query parameter in the URL.

GET /api/ipaddress?apikey=YOUR_API_KEY

Method 2: Request Header

Include the API key in the request headers (recommended for security).

X-API-Key: YOUR_API_KEY

Security Note: Never expose your API key in client-side code. Always use it from your backend server to prevent unauthorized access.

API Endpoints

GET /api/ipaddress

Get geolocation for the client's IP address.
Returns geolocation information for the requesting client automatically.

Parameters
Parameter Type Required Description
apikey string Required Your API authentication key
Example Request
curl -X GET "http://ip.aeu-app.com/api/ipaddress?apikey=YOUR_KEY" \
  -H "Accept: application/json"
GET /api/ipaddress/{ip}

Get geolocation for a specific IP address.
Returns geolocation information for any valid IPv4 or IPv6 address.

Parameters
Parameter Type Required Description
ip string Required IPv4 or IPv6 address to lookup
apikey string Required Your API authentication key
Example Request
curl -X GET "http://ip.aeu-app.com/api/ipaddress/8.8.8.8?apikey=YOUR_KEY" \
  -H "Accept: application/json"
GET /health

Health check endpoint.
Returns service status and database availability. No authentication required.

Example Request
curl -X GET "http://ip.aeu-app.com/health"

Response Format

All successful responses return JSON data with comprehensive geolocation information.

Success Response (200 OK)

{
  "query": "8.8.8.8",
  "status": "success",
  "continent": "North America",
  "continentCode": "NA",
  "country": "United States",
  "countryCode": "US",
  "region": "CA",
  "regionName": "California",
  "city": "Mountain View",
  "district": "",
  "zip": "94035",
  "lat": 37.386,
  "lon": -122.0838,
  "timezone": "America/Los_Angeles",
  "offset": 0,
  "currency": "",
  "isp": "Google LLC",
  "org": "Google LLC",
  "as": "AS15169 Google LLC",
  "asname": "Google LLC",
  "mobile": false,
  "proxy": false,
  "hosting": false,
  "dns": {
    "geo": "DNS resolved - Google",
    "ip": "8.8.8.8"
  }
}

Error Response (4xx/5xx)

{
  "status": "error",
  "message": "Invalid or expired API key",
  "help": "Check your API key or contact administrator"
}

Rate Limiting

API keys have configurable rate limits to ensure fair usage. When you make a request, the response includes rate limit headers: 

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9950
X-RateLimit-Used: 50

If you exceed your rate limit, you'll receive a 429 Too Many Requests response. Monitor your usage and upgrade your plan if needed.

CORS Support

Cross-Origin Resource Sharing (CORS) is enabled for all endpoints, allowing you to make requests from web browsers.

Domain Restrictions: API keys can be restricted to specific domains for added security. Configure allowed domains in your account settings.

Integration Examples

JavaScript
Python
PHP
cURL

JavaScript (Fetch API)

const apiKey = 'YOUR_API_KEY';
const apiUrl = 'http://ip.aeu-app.com/api/ipaddress';

async function getGeolocation() {
  try {
    const response = await fetch(`${apiUrl}?apikey=${apiKey}`, {
      method: 'GET',
      headers: {
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Location:', data.city, data.country);
    console.log('Coordinates:', data.lat, data.lon);
    return data;
  } catch (error) {
    console.error('Error fetching geolocation:', error);
  }
}

getGeolocation();

Python (Requests)

import requests

API_KEY = 'YOUR_API_KEY'
API_URL = 'http://ip.aeu-app.com/api/ipaddress'

def get_geolocation(ip_address=None):
    """Get geolocation data for an IP address."""
    url = f"{API_URL}/{ip_address}" if ip_address else API_URL

    headers = {
        'Accept': 'application/json',
        'X-API-Key': API_KEY
    }

    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        data = response.json()

        print(f"Location: {data['city']}, {data['country']}")
        print(f"Coordinates: {data['lat']}, {data['lon']}")
        return data
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        return None

# Example usage
result = get_geolocation()  # Get your own IP
result = get_geolocation('8.8.8.8')  # Get specific IP

PHP (cURL)

<?php

$apiKey = 'YOUR_API_KEY';
$apiUrl = 'http://ip.aeu-app.com/api/ipaddress';

function getGeolocation($ip = null) {
    global $apiKey, $apiUrl;

    $url = $ip ? "$apiUrl/$ip" : $apiUrl;
    $url .= "?apikey=$apiKey";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Accept: application/json'
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 200) {
        $data = json_decode($response, true);
        echo "Location: {$data['city']}, {$data['country']}\n";
        echo "Coordinates: {$data['lat']}, {$data['lon']}\n";
        return $data;
    } else {
        echo "Error: HTTP $httpCode\n";
        return null;
    }
}

// Example usage
$result = getGeolocation();  // Get your own IP
$result = getGeolocation('8.8.8.8');  // Get specific IP

?>

cURL Command Line

# Get your own IP geolocation
curl -X GET "http://ip.aeu-app.com/api/ipaddress?apikey=YOUR_KEY" \
  -H "Accept: application/json"

# Get specific IP geolocation
curl -X GET "http://ip.aeu-app.com/api/ipaddress/8.8.8.8?apikey=YOUR_KEY" \
  -H "Accept: application/json"

# Using header authentication (recommended)
curl -X GET "http://ip.aeu-app.com/api/ipaddress" \
  -H "Accept: application/json" \
  -H "X-API-Key: YOUR_KEY"

# Pretty print JSON response
curl -X GET "http://ip.aeu-app.com/api/ipaddress?apikey=YOUR_KEY" \
  -H "Accept: application/json" | jq

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Status Code Meaning Description
200 OK Request successful, data returned
400 Bad Request Invalid IP address format
401 Unauthorized Missing or invalid API key
403 Forbidden Domain not allowed for this API key
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error, please try again

Ready to Get Started?

Try our interactive API tester to make live requests and see the responses in real-time

Try API Tester View Pricing