API Documentation

Complete guide to integrating The IP API into your applications
Get Your API Key
Need Help?

Getting Started

Learn the basics of using The IP API, from authentication to making your first request.

API Reference

Complete reference for all API endpoints, parameters, and response formats.

Code Examples

Ready-to-use code examples in multiple programming languages.

Getting Started

Follow these simple steps to start using The IP API in your application.

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"

3. Parse the Response

The API returns JSON data with geolocation information:

{
  "status": "OK",
  "body": {
    "asn": {
      "asn": 13335,
      "asn_description": "CLOUDFLARENET, US",
      "country": "AU",
      "created": "2010-07-15",
      "network": "1.1.1.0/24",
      "org_name": "Cloudflare, Inc.",
      "rir": "ARIN",
      "updated": "2021-07-01"
    },
    "company": {
      "address": "101 Townsend Street, San Francisco, CA, US",
      "name": "APNIC and Cloudflare DNS Resolver project",
      "network": "1.1.1.0 - 1.1.1.255",
      "route": "1.1.1.0/24"
    },
    "ip": "1.1.1.1",
    "location": {
      "city": "Los Angeles",
      "country": "United States of America",
      "country_code": "US",
      "latitude": 34.052571,
      "longitude": -118.243907,
      "region": "California",
      "timezone": "America/Los_Angeles"
    },
    "is_bogon": false,
    "is_datacenter": false,
    "is_vpn": false
  },
  "response_time_ms": 10
}

API Reference

IP Geolocation Endpoint

GET /v1/ip/{ip_address}

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

GET /v1/asn/{asn_number}

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

Batch IP Geolocation Endpoint

POST /v1/ip/batch

Look up geolocation data for multiple IP addresses in a single request. Up to 100 IPs per request. Each unique IP counts as one request against your API quota.

Parameters

  • api_key (required) - Your API key (query parameter)
  • ips (required) - JSON array of IP addresses (request body)

Notes

  • Maximum of 100 IP addresses per request
  • Duplicate IPs are automatically deduplicated and only counted once
  • All IPs are validated upfront - if any IP is invalid, the entire request is rejected
  • Quota is checked before processing - if you don't have enough remaining requests for all unique IPs, the batch is rejected

Example Request

curl -X POST "https://api.theipapi.com/v1/ip/batch?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1", "192.168.1.1"]}'

Example Response

{
  "status": "OK",
  "results": {
    "8.8.8.8": {
      "status": "OK",
      "body": {
        "ip": "8.8.8.8",
        "location": {
          "city": "Mountain View",
          "country": "United States of America",
          "country_code": "US",
          "latitude": 37.386,
          "longitude": -122.0838,
          "region": "California",
          "timezone": "America/Los_Angeles"
        },
        "asn": { "asn": 15169, "org_name": "Google LLC", ... },
        "company": { "name": "Google LLC", ... },
        "is_bogon": false,
        "is_datacenter": true,
        "is_vpn": false
      },
      "response_time_ms": 12
    },
    "1.1.1.1": {
      "status": "OK",
      "body": { ... },
      "response_time_ms": 8
    },
    "192.168.1.1": {
      "status": "OK",
      "body": {
        "ip": "192.168.1.1",
        "is_bogon": true
      },
      "response_time_ms": 1
    }
  },
  "total_ips": 3,
  "response_time_ms": 15
}

Response Fields

  • status - Overall request status ("OK" if the batch was accepted)
  • results - Dictionary keyed by IP address, each containing the same response format as the single IP endpoint
  • total_ips - Number of unique IPs processed
  • response_time_ms - Total batch processing time in milliseconds

Error Responses

  • 400 - Invalid JSON body, no IPs provided, more than 100 IPs, or invalid IP address
  • 401 - Missing or invalid API key
  • 405 - Method not allowed (must use POST)
  • 429 - Insufficient API quota for the batch size

Code Examples

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

Batch Request - curl

curl -X POST "https://api.theipapi.com/v1/ip/batch?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1", "9.9.9.9"]}'

Rate Limits

API requests are rate limited based on your subscription plan:

  • Free Plan: 1,000 requests per day
  • Beginner Plan: 600,000 requests per month
  • Standard Plan: 3,000,000 requests per month
  • Premium Plan: 15,000,000 requests per month

Rate limits reset daily for the Free plan and monthly for paid plans. For batch requests, each unique IP address counts as one request. Check your usage in the dashboard.

Error Handling

The API returns standard HTTP status codes:

  • 200 - Success
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid API key)
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error

Error Response Format

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}

Best Practices

  • Cache Results: IP geolocation data doesn't change frequently, so cache results to reduce API calls
  • Handle Errors: Always implement proper error handling for network issues and API errors
  • Respect Rate Limits: Monitor your usage and implement backoff strategies
  • Use HTTPS: Always use HTTPS endpoints for secure communication
  • Validate Input: Validate IP addresses before making API calls

Need More Help?

If you need additional assistance or have questions about the API: