How to Integrate an IP Address Geolocation API

IP geolocation APIs enable developers to convert IP addresses into rich location data—country, city, coordinates, timezone, and more. Whether you're building content personalization, fraud detection, analytics, or compliance features, integrating a reliable geolocation API is essential. This guide walks you through integrating FreeIPAPI step by step.

What is IP Geolocation?

Why Use FreeIPAPI?

• Fast response times – Sub-50ms latency with edge caching via Cloudflare
• Global coverage – Accurate data for IPv4 and IPv6
• Simple REST API – Single endpoint, JSON response
• Free tier – 50,000 requests/month to get started
• Documentation – Full reference at freeipapi.app/docs

Step 1: Get Your API Key

All requests to FreeIPAPI require an API key. Sign up at the FreeIPAPI to create an account and generate your key. Keys use the fip_ prefix.

Step 2: Authentication

Include your API key in the Authorization header using the Bearer token format:

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual key from the dashboard.

Step 3: API Endpoint & Base URL

Base URL:

https://api.freeipapi.app

Lookup endpoint:

GET /api/v1/lookup?ip={IP_ADDRESS}

The ip parameter is optional. If omitted, the API returns geolocation for the requester's IP.

Step 4: Code Examples

Here are integration examples in popular languages. Replace YOUR_API_KEY with your key.

cURL

curl -s "https://api.freeipapi.app/api/v1/lookup?ip=8.8.8.8" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript (Fetch API)

const response = await fetch(
  'https://api.freeipapi.app/api/v1/lookup?ip=8.8.8.8',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json'
    }
  }
);
const data = await response.json();
console.log(data);

Node.js

const response = await fetch(
  'https://api.freeipapi.app/api/v1/lookup?ip=8.8.8.8',
  {
    headers: {
      'Authorization': `Bearer ${process.env.FREEIPAPI_KEY}`,
      'Accept': 'application/json'
    }
  }
);
const data = await response.json();
console.log(data.city, data.country);

Python

import requests

response = requests.get(
    'https://api.freeipapi.app/api/v1/lookup',
    params={'ip': '8.8.8.8'},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()
print(data['city'], data['country'])

PHP

$ch = curl_init('https://api.freeipapi.app/api/v1/lookup?ip=8.8.8.8');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['city'] . ', ' . $data['country'];

Go

req, _ := http.NewRequest(
    "GET",
    "https://api.freeipapi.app/api/v1/lookup?ip=8.8.8.8",
    nil,
)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Accept", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

body, _ := io.ReadAll(resp.Body)
var data map[string]interface{}
json.Unmarshal(body, &data)

Understanding the Response

A successful response returns JSON with geolocation data. Key fields include:

{
  "ip_address": "8.8.8.8",
  "ip_version": 4,
  "latitude": 37.4056,
  "longitude": -122.0775,
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "city": "Mountain View",
  "timezones": ["America/Los_Angeles"],
  "asn": 15169,
  "asn_org": "Google LLC",
  "is_proxy": false
}

For a full field reference, see the API documentation.

Error Handling

The API returns standard HTTP status codes. Handle them in your integration:

• 401 – Invalid or missing API key. Check Authorization header format.
• 400 – Invalid IP address format.
• 404 – IP not found in database.
• 429 – Rate limited or quota exceeded. Check X-RateLimit-Remaining header.

Rate Limits & Best Practices

• Hobby plan: 50 requests/10 seconds, 50,000 requests/month
• Cache results – IP geolocation rarely changes; cache by IP to reduce API calls
• Respect headers – Use X-RateLimit-Remaining and X-RateLimit-Reset to avoid limits

Common Use Cases

• Content localization – Show region-specific content or language
• Fraud detection – Flag mismatches between IP location and billing address
• Analytics – Understand where your users are located
• Compliance – Geo-restrict content where required