Skip to main content

IP Lookup

The IP Lookup endpoint retrieves comprehensive intelligence data for a single IP address, including ASN information, geolocation, detection flags, and threat scoring.

Endpoint​

GET /v1/ip/{ip}

Authentication​

This endpoint requires an API key. See Authentication for details.

Path Parameters​

ParameterTypeRequiredDescription
ipstringYesIPv4 or IPv6 address to look up

Request Headers​

HeaderRequiredDescription
X-API-KeyYesYour API key
AcceptNoSet to application/json (default)

Response Headers​

HeaderDescription
X-Request-IDUnique identifier for the request
X-RateLimit-LimitMaximum requests allowed per time window
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix timestamp when the limit resets
X-Cache-StatusCache status (HIT or MISS)

Response​

Success Response (200)​

{
  "data": {
    "ip": "8.8.8.8",
    "prefix": "8.8.8.0/24",
    "asn": 15169,
    "asn_name": "Google LLC",
    "country": "US",
    "rir": "ARIN",
    "connection_type": "datacenter",
    "detection": {
      "is_datacenter": true,
      "is_tor_exit": false,
      "is_proxy": false,
      "is_vpn": false,
      "is_residential": false,
      "is_mobile": false,
      "is_ai_crawler": false,
      "cloud_provider": "Google Cloud"
    },
    "threat": {
      "score": 0,
      "level": "low"
    }
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "processing_time_ms": 5,
    "cache_status": "HIT",
    "dataset_version": 1
  }
}

Response Fields​

Data Object​

FieldTypeDescription
ipstringThe queried IP address (normalized)
prefixstringCIDR prefix containing this IP
asnintegerAutonomous System Number
asn_namestringName of the organization owning the ASN
countrystringISO 3166-1 alpha-2 country code
rirstringRegional Internet Registry (ARIN, RIPE, APNIC, LACNIC, AFRINIC)
connection_typestringConnection type (residential, datacenter, mobile, business, education)
detectionobjectDetection flags
threatobjectThreat information

Detection Object​

FieldTypeDescription
is_datacenterbooleanIP belongs to a datacenter
is_tor_exitbooleanIP is a Tor exit node
is_proxybooleanIP is a known proxy
is_vpnbooleanIP belongs to a VPN provider
is_residentialbooleanIP is a residential connection
is_mobilebooleanIP is a mobile connection
is_ai_crawlerbooleanIP is used by an AI crawler/bot
ai_companystringName of AI company (if is_ai_crawler is true)
cloud_providerstringName of cloud provider (if detected)

Threat Object​

FieldTypeDescription
scoreintegerThreat score from 0 (safe) to 100 (high risk)
levelstringHuman-readable level: low, medium, high, critical
explanationarrayReasons contributing to the score

Error Responses​

400 Bad Request - Invalid IP​

{
  "data": {
    "error": "invalid IP address",
    "code": "INVALID_IP"
  },
  "meta": {
    "processing_time_ms": 0
  }
}

401 Unauthorized​

{
  "data": {
    "error": "unauthorized",
    "code": "UNAUTHORIZED"
  },
  "meta": {
    "processing_time_ms": 0
  }
}

404 Not Found​

{
  "data": {
    "error": "no data found for IP",
    "code": "NOT_FOUND"
  },
  "meta": {
    "processing_time_ms": 2,
    "cache_status": "MISS",
    "dataset_version": 1
  }
}

429 Rate Limit Exceeded​

{
  "data": {
    "error": "rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED"
  },
  "meta": {
    "processing_time_ms": 0
  }
}

Code Examples​

cURL​

# Basic IP lookup
curl -X GET "https://api.limesindex.com/v1/ip/8.8.8.8" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

# IPv6 lookup
curl -X GET "https://api.limesindex.com/v1/ip/2001:4860:4860::8888" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

# With verbose output (shows rate limit headers)
curl -v -X GET "https://api.limesindex.com/v1/ip/1.1.1.1" \
  -H "X-API-Key: YOUR_API_KEY"

Python​

import requests
import os

API_KEY = os.environ.get("LIMESINDEX_API_KEY")
BASE_URL = "https://api.limesindex.com"

def lookup_ip(ip_address: str) -> dict:
    """Look up intelligence data for an IP address."""
    response = requests.get(
        f"{BASE_URL}/v1/ip/{ip_address}",
        headers={
            "X-API-Key": API_KEY,
            "Accept": "application/json"
        }
    )
    response.raise_for_status()
    return response.json()

# Example usage
result = lookup_ip("8.8.8.8")

# Access the data
ip_data = result["data"]
print(f"IP: {ip_data['ip']}")
print(f"ASN: {ip_data['asn']} ({ip_data['asn_name']})")
print(f"Country: {ip_data['country']}")

# Check detection flags
detection = ip_data["detection"]
if detection["is_datacenter"]:
    print(f"Datacenter IP - Provider: {detection.get('cloud_provider', 'Unknown')}")
if detection["is_vpn"]:
    print("VPN detected")
if detection["is_tor_exit"]:
    print("Tor exit node detected")
if detection["is_ai_crawler"]:
    print(f"AI Crawler - Company: {detection.get('ai_company', 'Unknown')}")

# Check threat level
threat = ip_data["threat"]
print(f"Threat Score: {threat['score']} ({threat['level']})")

JavaScript (Node.js)​

const API_KEY = process.env.LIMESINDEX_API_KEY;
const BASE_URL = 'https://api.limesindex.com';

async function lookupIP(ipAddress) {
  const response = await fetch(`${BASE_URL}/v1/ip/${ipAddress}`, {
    method: 'GET',
    headers: {
      'X-API-Key': API_KEY,
      'Accept': 'application/json'
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.data.error} (${error.data.code})`);
  }

  return response.json();
}

// Example usage
async function main() {
  try {
    const result = await lookupIP('8.8.8.8');
    const { data, meta } = result;

    console.log(`IP: ${data.ip}`);
    console.log(`ASN: ${data.asn} (${data.asn_name})`);
    console.log(`Country: ${data.country}`);
    console.log(`Connection Type: ${data.connection_type}`);

    // Detection flags
    if (data.detection.is_datacenter) {
      console.log(`Datacenter: ${data.detection.cloud_provider || 'Yes'}`);
    }
    if (data.detection.is_vpn) {
      console.log('VPN: Yes');
    }
    if (data.detection.is_ai_crawler) {
      console.log(`AI Crawler: ${data.detection.ai_company}`);
    }

    // Threat info
    console.log(`Threat: ${data.threat.score}/100 (${data.threat.level})`);

    // Meta info
    console.log(`Request ID: ${meta.request_id}`);
    console.log(`Cache: ${meta.cache_status}`);
    console.log(`Processing Time: ${meta.processing_time_ms}ms`);
  } catch (error) {
    console.error('Lookup failed:', error.message);
  }
}

main();

Go​

package main

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

const baseURL = "https://api.limesindex.com"

type Detection struct {
    IsDatacenter  bool   `json:"is_datacenter"`
    IsTorExit     bool   `json:"is_tor_exit"`
    IsProxy       bool   `json:"is_proxy"`
    IsVPN         bool   `json:"is_vpn"`
    IsResidential bool   `json:"is_residential"`
    IsMobile      bool   `json:"is_mobile"`
    IsAICrawler   bool   `json:"is_ai_crawler"`
    AICompany     string `json:"ai_company,omitempty"`
    CloudProvider string `json:"cloud_provider,omitempty"`
}

type Threat struct {
    Score       int      `json:"score"`
    Level       string   `json:"level"`
    Explanation []string `json:"explanation,omitempty"`
}

type IPData struct {
    IP             string    `json:"ip"`
    Prefix         string    `json:"prefix"`
    ASN            int       `json:"asn"`
    ASNName        string    `json:"asn_name"`
    Country        string    `json:"country"`
    RIR            string    `json:"rir"`
    ConnectionType string    `json:"connection_type"`
    Detection      Detection `json:"detection"`
    Threat         Threat    `json:"threat"`
}

type Meta struct {
    RequestID        string `json:"request_id"`
    ProcessingTimeMs int    `json:"processing_time_ms"`
    CacheStatus      string `json:"cache_status"`
    DatasetVersion   int    `json:"dataset_version"`
}

type IPLookupResponse struct {
    Data IPData `json:"data"`
    Meta Meta   `json:"meta"`
}

func lookupIP(apiKey, ipAddress string) (*IPLookupResponse, error) {
    url := fmt.Sprintf("%s/v1/ip/%s", baseURL, ipAddress)

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        return nil, err
    }

    req.Header.Set("X-API-Key", apiKey)
    req.Header.Set("Accept", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

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

    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("API error: %s", string(body))
    }

    var result IPLookupResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

func main() {
    apiKey := os.Getenv("LIMESINDEX_API_KEY")

    result, err := lookupIP(apiKey, "8.8.8.8")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    data := result.Data
    fmt.Printf("IP: %s\n", data.IP)
    fmt.Printf("ASN: %d (%s)\n", data.ASN, data.ASNName)
    fmt.Printf("Country: %s\n", data.Country)
    fmt.Printf("Connection Type: %s\n", data.ConnectionType)

    if data.Detection.IsDatacenter {
        fmt.Printf("Datacenter: %s\n", data.Detection.CloudProvider)
    }
    if data.Detection.IsVPN {
        fmt.Println("VPN: Yes")
    }
    if data.Detection.IsAICrawler {
        fmt.Printf("AI Crawler: %s\n", data.Detection.AICompany)
    }

    fmt.Printf("Threat: %d/100 (%s)\n", data.Threat.Score, data.Threat.Level)
    fmt.Printf("Request ID: %s\n", result.Meta.RequestID)
}

Use Cases​

Fraud Detection​

def is_suspicious_ip(ip_address: str) -> bool:
    """Check if an IP shows suspicious characteristics."""
    result = lookup_ip(ip_address)
    data = result["data"]

    # Check for VPN, proxy, or Tor
    if data["detection"]["is_vpn"]:
        return True
    if data["detection"]["is_proxy"]:
        return True
    if data["detection"]["is_tor_exit"]:
        return True

    # Check threat score
    if data["threat"]["score"] >= 50:
        return True

    return False

Bot Detection​

def is_bot_traffic(ip_address: str) -> tuple[bool, str]:
    """Detect if traffic is from a bot."""
    result = lookup_ip(ip_address)
    data = result["data"]

    if data["detection"]["is_ai_crawler"]:
        return True, f"AI Crawler: {data['detection'].get('ai_company', 'Unknown')}"

    if data["detection"]["is_datacenter"]:
        return True, f"Datacenter: {data['detection'].get('cloud_provider', 'Unknown')}"

    return False, "Human traffic"

Geographic Verification​

def verify_user_location(ip_address: str, expected_country: str) -> bool:
    """Verify if user's IP matches expected country."""
    result = lookup_ip(ip_address)
    return result["data"]["country"] == expected_country

Performance Tips​

  1. Use caching - Responses include cache status; cache results locally when appropriate
  2. Use batch endpoint - For multiple IPs, use Batch Lookup
  3. Handle rate limits - Monitor X-RateLimit-Remaining headers