GEO IP Geolocation

Get geolocation information for IP addresses including country codes and geographical data

Overview

This endpoint provides geolocation information for IP addresses. You can query your own IP address or specify a target IP to retrieve its geographical location data.

The endpoint returns:

  • Country code (ISO 3166-1 alpha-2) for the IP address
  • Automatic client IP detection
  • Support for custom IP address queries

Pricing

📊 1 Credit per Request

Each request costs 1 data credit and counts as a billable request.

Endpoint

GET /geo/ip
GET /geo/ip?ip={ip_address}

Query Parameters

ParameterTypeRequiredDescription
ipstringNoIPv4 or IPv6 address to lookup. If not provided, returns geolocation for the client's IP address

Response Format

{
  "ip": "8.8.8.8",
  "c2": "US"
}

Response Fields

FieldTypeDescription
ipstringThe IP address that was queried
c2stringISO 3166-1 alpha-2 country code (e.g., "US", "GB", "DE")

Example Requests

Get Your Own IP Location

curl -X GET "https://api.boxapi.com/geo/ip" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Lookup Specific IP Address

# IPv4 lookup
curl -X GET "https://api.boxapi.com/geo/ip?ip=8.8.8.8" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# IPv6 lookup
curl -X GET "https://api.boxapi.com/geo/ip?ip=2001:4860:4860::8888" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Usage Examples

JavaScript/Node.js

// Get your own IP location
const response = await fetch('/geo/ip', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const geoData = await response.json();
console.log(`Your IP ${geoData.ip} is from country: ${geoData.c2}`);

// Lookup specific IPv4
const ipv4Response = await fetch('/geo/ip?ip=8.8.8.8', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
const ipv4Geo = await ipv4Response.json();
console.log(`IPv4 ${ipv4Geo.ip} is located in: ${ipv4Geo.c2}`);

// Lookup specific IPv6
const ipv6Response = await fetch('/geo/ip?ip=2001:4860:4860::8888', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
const ipv6Geo = await ipv6Response.json();
console.log(`IPv6 ${ipv6Geo.ip} is located in: ${ipv6Geo.c2}`);

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Get your own IP location
response = requests.get('https://api.boxapi.com/geo/ip', headers=headers)
geo_data = response.json()
print(f"Your IP {geo_data['ip']} is from country: {geo_data['c2']}")

# Lookup specific IP
target_response = requests.get('https://api.boxapi.com/geo/ip?ip=8.8.8.8', headers=headers)
target_geo = target_response.json()
print(f"IP {target_geo['ip']} is located in: {target_geo['c2']}")

PHP

<?php
$apiKey = 'YOUR_API_KEY';

// Get your own IP location
$ch = curl_init('https://api.boxapi.com/geo/ip');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$geoData = json_decode($response, true);

echo "Your IP {$geoData['ip']} is from country: {$geoData['c2']}\n";

// Lookup specific IP
$ch = curl_init('https://api.boxapi.com/geo/ip?ip=8.8.8.8');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$targetGeo = json_decode($response, true);

echo "IP {$targetGeo['ip']} is located in: {$targetGeo['c2']}\n";
?>

Error Responses

Invalid IP Format

{
  "error": "Invalid IP address format"
}

HTTP Status: 400 Bad Request

Authentication Error

{
  "error": "Unauthorized"
}

HTTP Status: 401 Unauthorized

Rate Limit Exceeded

{
  "error": "IP blocked",
  "statusCode": 429
}

HTTP Status: 429 Too Many Requests

Rate Limits

The following rate limits apply per IP address:

  • 10,000 requests per minute for successful responses (2xx status codes)
  • 60 requests per minute for client errors (4xx status codes)
  • 60 requests per minute for server errors (5xx status codes)

⚠️ If you exceed these limits, your IP will be temporarily blocked and you'll receive a 429 status code.

Important Notes

  • Full IPv4 and IPv6 support via query parameter
  • Supports all standard IPv6 notations (full, compressed, IPv6-mapped IPv4)
  • Client IP detection automatically handles both IPv4 and IPv6
  • The endpoint handles IPv6-mapped IPv4 addresses (e.g., ::ffff:192.168.1.1)
  • X-Forwarded-For header is respected for proxied requests
  • Geolocation data is cached for optimal performance
  • Uses MaxMind GeoIP2 Country Database for accurate geolocation

Supported IP Formats

IPv4

  • Standard dotted decimal notation: 192.168.1.1, 8.8.8.8

IPv6

  • Full notation: 2001:0db8:0000:0000:0000:0000:0000:0001
  • Compressed notation: 2001:db8::1, 2001:4860:4860::8888
  • IPv6-mapped IPv4: ::ffff:192.168.1.1
  • Link-local addresses: fe80::1%eth0

Additional Endpoint

GET /geo/ip/info

Get detailed information about the IP geolocation endpoint capabilities.

Response:

{
  "description": "This endpoint provides IP geolocation services...",
  "features": [
    "Support for both IPv4 and IPv6 addresses",
    "Automatic client IP detection",
    "ISO 3166-1 alpha-2 country codes",
    "High-performance in-memory caching"
  ],
  "params": {
    "ip": {
      "type": "string",
      "required": false,
      "description": "Target IP address to geolocate (IPv4 or IPv6)",
      "examples": ["8.8.8.8", "2001:4860:4860::8888"]
    }
  },
  "supportedFormats": {
    "IPv4": "Standard dotted decimal notation",
    "IPv6": "Full and compressed notation"
  },
  "creditCost": 1,
  "dataSource": "MaxMind GeoIP2 Country Database"
}

Credit Cost: 1 credit per request