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 month.

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

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

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. 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: