API documentation.

1. Get your API key

Sign up for a free account at theipapi.com to get your API key. The free plan includes 1,000 requests per day.

2. Make your first request

Use your API key to make a request to our geolocation endpoint:

curl "https://api.theipapi.com/v1/ip/8.8.8.8?api_key=YOUR_API_KEY"

IP geolocation endpoint

Returns geolocation data for a specific IP address.

Parameters

• ip_address (required) - The IP address to look up
• api_key (required) - Your API key

Example request

curl "https://api.theipapi.com/v1/ip/8.8.8.8?api_key=YOUR_API_KEY"

Response fields

• status - Response status ("OK" for successful requests)
• body.ip - The queried IP address
• body.location.country_code - Two-letter country code
• body.location.country - Full country name
• body.location.city - City name
• body.location.region - State/region name
• body.location.latitude - Latitude coordinate
• body.location.longitude - Longitude coordinate
• body.location.timezone - Timezone information
• body.asn.asn - Autonomous System Number
• body.asn.org_name - ASN organization name
• body.asn.asn_description - ASN description
• body.company.name - Company name
• body.company.address - Company address
• body.is_bogon - Whether IP is a bogon (private/invalid)
• body.is_datacenter - Whether IP belongs to a datacenter
• body.is_vpn - Whether IP belongs to a VPN service
• response_time_ms - API response time in milliseconds

ASN lookup endpoint

Returns information about an Autonomous System Number (ASN).

Parameters

• asn_number (required) - The ASN to look up
• api_key (required) - Your API key

Example request

curl "https://api.theipapi.com/v1/asn/15169?api_key=YOUR_API_KEY"

Example response

{
  "status": "OK",
  "body": {
    "asn": {
      "asn": 15169,
      "asn_description": "Google LLC",
      "country": "US",
      "created": "2005-11-23",
      "org_name": "Google LLC",
      "rir": "ARIN",
      "updated": "2019-10-31"
    }
  },
  "response_time_ms": 0
}

Response fields

• status - Response status ("OK" for successful requests)
• body.asn.asn - The Autonomous System Number
• body.asn.asn_description - ASN description/name
• body.asn.country - Country code where ASN is registered
• body.asn.created - Date when ASN was created
• body.asn.org_name - Organization name
• body.asn.rir - Regional Internet Registry (ARIN, RIPE, APNIC, etc.)
• body.asn.updated - Last update date
• response_time_ms - API response time in milliseconds

JavaScript (Node.js)

const https = require('https');

const options = {
  hostname: 'api.theipapi.com',
  path: '/v1/ip/8.8.8.8?api_key=YOUR_API_KEY',
  method: 'GET'
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => {
    data += chunk;
  });
  res.on('end', () => {
    const result = JSON.parse(data);
    console.log(result);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.end();

Python

import requests

url = "https://api.theipapi.com/v1/ip/8.8.8.8"
params = {"api_key": "YOUR_API_KEY"}

response = requests.get(url, params=params)
data = response.json()

print(data)

PHP

<?php
$url = "https://api.theipapi.com/v1/ip/8.8.8.8?api_key=YOUR_API_KEY";
$response = file_get_contents($url);
$data = json_decode($response, true);

print_r($data);
?>

Go

package main

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

func main() {
    url := "https://api.theipapi.com/v1/ip/8.8.8.8?api_key=YOUR_API_KEY"
    resp, err := http.Get(url)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    var result map[string]interface{}
    json.Unmarshal(body, &result)
    fmt.Println(result)
}

Batch request - Python

import requests

url = "https://api.theipapi.com/v1/ip/batch"
params = {"api_key": "YOUR_API_KEY"}
payload = {
    "ips": ["8.8.8.8", "1.1.1.1", "9.9.9.9"]
}

response = requests.post(url, params=params, json=payload)
data = response.json()

for ip, result in data["results"].items():
    location = result["body"]["location"]
    print(f"{ip}: {location['city']}, {location['country_code']}")

Batch request - JavaScript (Node.js)

const response = await fetch(
  "https://api.theipapi.com/v1/ip/batch?api_key=YOUR_API_KEY",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      ips: ["8.8.8.8", "1.1.1.1", "9.9.9.9"]
    })
  }
);

const data = await response.json();

for (const [ip, result] of Object.entries(data.results)) {
  console.log(`${ip}: ${result.body.location.city}`);
}