FreeIPAPI Documentation

Fast, reliable IP geolocation API with Redis + Cloudflare edge caching. Get location data for any IP address in milliseconds.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header using the Bearer token format.

Authorization: Bearer YOUR_API_KEY

Base URL

All API requests should be made to the following base URL:

IP Lookup Endpoint

Retrieve geolocation data for any IPv4 or IPv6 address.

Parameters

Request Format

Required Headers

Response Format

Successful responses return a JSON object with geolocation data. The attribution field appears only for free tier plans.

{
  "ip_address": "8.8.8.8",
  "ip_version": 4,
  "is_valid": true,
  "latitude": 37.4056,
  "longitude": -122.0775,
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "city": "Mountain View",
  "postal_code": "94043",
  "continent": "North America",
  "continent_code": "NA",
  "capital": "Washington D.C.",
  "phone_codes": [1],
  "timezones": ["America/Los_Angeles"],
  "languages": ["en"],
  "currencies": ["USD"],
  "asn": 15169,
  "asn_org": "Google LLC",
  "is_proxy": false
}

Error Codes

When an error occurs, the API returns an appropriate HTTP status code along with an error code and message.

{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly request limit reached. Please upgrade your plan.",
  "code": 429
}

Rate Limits

Rate limits and quotas are applied per account, not per API key. All API keys under your account share the same limits.

Rate Limit Headers

The API returns rate limit information in response headers:

Field Reference

Core Fields

Location Fields

Enrichment Fields

Network Fields

Code Examples

Here are code snippets for popular programming languages to help you get started quickly.

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

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);

import requests

response = requests.get(
    'https://api.freeipapi.app/api/v1/lookup?ip=8.8.8.8',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

print(response.json())

<?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']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

echo $response;

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    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")
    
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

require 'net/http'
require 'json'

uri = URI('https://api.freeipapi.app/api/v1/lookup?ip=8.8.8.8')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer YOUR_API_KEY'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.pretty_generate(JSON.parse(res.body))

import java.net.URI;
import java.net.http.*;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.freeipapi.app/api/v1/lookup?ip=8.8.8.8"))
            .header("Authorization", "Bearer YOUR_API_KEY")
            .GET()
            .build();
            
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

using System.Net.Http;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");

var response = await client.GetStringAsync("https://api.freeipapi.app/api/v1/lookup?ip=8.8.8.8");
Console.WriteLine(response);

Troubleshooting

401 Unauthorized

• Verify your API key is correct and includes the fip_ prefix
• Ensure the Authorization header format is Bearer YOUR_API_KEY
• Check that your API key is active in the dashboard
• Remove any extra spaces or newlines from the key

403 Quota Exceeded

• Your monthly request quota has been reached
• Upgrade your plan for higher limits or wait for the monthly reset
• Check your usage in the dashboard

429 Rate Limited

• You're sending requests too quickly
• Implement exponential backoff in your code
• Consider upgrading for higher rate limits
• Check the X-RateLimit-Reset header for when to retry

404 IP Not Found

• The IP address is not in the database
• This can happen with private IPs or very new allocations
• Try a different IP address

503 Service Error

• Temporary service issue on our end
• Retry the request with exponential backoff
• Check our status page for any ongoing incidents