Country by IP API: The Complete Guide

Need to determine where your users are located? This guide covers everything you need to know about IP-to-country lookup via API, including geolocation accuracy, use cases, and implementation examples.

What is IP Geolocation?

IP geolocation is the process of determining the geographic location of an internet-connected device using its IP address. At the country level, this is highly accurate (95-99%) and useful for localization, compliance, and security.

For example, an IP address like 8.8.8.8 can be resolved to "United States" with high confidence.

How It Works

IP geolocation databases are built from several sources:

• Regional Internet Registries: ARIN, RIPE, APNIC assign IP blocks to regions
• ISP Data: Internet service providers register their IP ranges
• Routing Data: Network routing tables indicate geographic paths
• User Contributions: Crowdsourced location data

Using the Country by IP API

TinyFn provides an endpoint to look up country from IP:

GET https://api.tinyfn.io/v1/geo/country?ip=8.8.8.8
Headers: X-API-Key: your-api-key

{
  "ip": "8.8.8.8",
  "country": {
    "code": "US",
    "name": "United States",
    "flag": "us"
  },
  "continent": {
    "code": "NA",
    "name": "North America"
  },
  "is_eu": false,
  "currency": "USD"
}

Parameters

Auto-detect Caller IP

GET https://api.tinyfn.io/v1/geo/country
# Uses the caller's IP address automatically

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/geo/country?ip=203.0.113.50',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const data = await response.json();

console.log(`Country: ${data.country.name}`);
console.log(`Code: ${data.country.code}`);
console.log(`EU Member: ${data.is_eu}`);

// Set locale based on country
const locale = data.country.code === 'DE' ? 'de-DE' : 'en-US';

Python

import requests

def get_country(ip_address=None):
    url = 'https://api.tinyfn.io/v1/geo/country'
    params = {'ip': ip_address} if ip_address else {}

    response = requests.get(
        url,
        params=params,
        headers={'X-API-Key': 'your-api-key'}
    )
    return response.json()

# Get country for specific IP
result = get_country("192.0.2.1")
print(f"Country: {result['country']['name']}")

# Get country for current request
visitor = get_country()  # Uses caller's IP

cURL

# Specific IP
curl "https://api.tinyfn.io/v1/geo/country?ip=8.8.8.8" \
  -H "X-API-Key: your-api-key"

# Auto-detect (your IP)
curl "https://api.tinyfn.io/v1/geo/country" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Localization: Show content in the user's language
• Compliance: Enforce GDPR, regional restrictions
• Currency: Display prices in local currency
• Fraud Prevention: Detect suspicious geographic patterns
• Content Delivery: Route to nearest CDN or server

Best Practices

1. Cache results: IP-to-country mappings change slowly; cache appropriately
2. Handle VPNs: Some users use VPNs; consider fallbacks
3. Allow override: Let users select their preferred region
4. Privacy compliance: IP addresses may be personal data under GDPR

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-geo": {
      "url": "https://api.tinyfn.io/mcp/geo/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all geolocation tools available via MCP in our Geolocation MCP Tools for AI Agents guide.