Response Format

All LimesIndex API responses follow a consistent JSON structure. This page documents the complete response schema and field definitions.

Response Structure

All successful API responses follow this structure:

{
  "data": { ... },
  "meta": { ... }
}

Field	Type	Description
data	object	The response payload
meta	object	Request metadata

Meta Object

The meta object is included in every response and contains request metadata:

{
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "processing_time_ms": 5,
    "cache_status": "HIT",
    "dataset_version": 1
  }
}

Field	Type	Description
request_id	string (UUID)	Unique identifier for the request (useful for support)
processing_time_ms	integer	Server-side processing time in milliseconds
cache_status	string	Cache status: HIT (served from cache) or MISS (fresh lookup)
dataset_version	integer	Version of the dataset used for this lookup

IP Lookup Response

Single IP Lookup

{
  "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": { ... }
}

IP Lookup Fields

Field	Type	Required	Description
ip	string	Yes	The queried IP address (normalized)
prefix	string	Yes	CIDR prefix containing this IP
asn	integer	Yes	Autonomous System Number
asn_name	string	No	Name of the organization owning the ASN
country	string	Yes	ISO 3166-1 alpha-2 country code
rir	string	No	Regional Internet Registry
connection_type	string	No	Type of connection
detection	object	No	Detection flags
threat	object	No	Threat information

Connection Types

Value	Description
residential	Home/consumer internet connection
datacenter	Server/cloud hosting provider
mobile	Mobile carrier network
business	Business/enterprise network
education	Educational institution

Regional Internet Registries (RIR)

Value	Region
ARIN	North America
RIPE	Europe, Middle East, Central Asia
APNIC	Asia-Pacific
LACNIC	Latin America, Caribbean
AFRINIC	Africa

Detection Object

The detection object contains boolean flags for various IP classifications:

{
  "detection": {
    "is_datacenter": true,
    "is_tor_exit": false,
    "is_proxy": false,
    "is_vpn": false,
    "is_residential": false,
    "is_mobile": false,
    "is_ai_crawler": false,
    "ai_company": "OpenAI",
    "cloud_provider": "AWS"
  }
}

Field	Type	Description
is_datacenter	boolean	IP belongs to a datacenter or hosting provider
is_tor_exit	boolean	IP is a known Tor exit node
is_proxy	boolean	IP is a known proxy server
is_vpn	boolean	IP belongs to a VPN provider
is_residential	boolean	IP is a residential/home connection
is_mobile	boolean	IP is from a mobile carrier
is_ai_crawler	boolean	IP is used by an AI company for web crawling
ai_company	string	Name of the AI company (only if is_ai_crawler is true)
cloud_provider	string	Name of the cloud provider (only if detected)

Known AI Crawlers

When is_ai_crawler is true, the ai_company field may contain:

• OpenAI - GPTBot, ChatGPT-User
• Anthropic - ClaudeBot
• Google - Google-Extended
• Meta - Meta-ExternalAgent
• Cohere - cohere-ai
• Common Crawl - CCBot
• And others...

Known Cloud Providers

When detected, the cloud_provider field may contain:

• AWS - Amazon Web Services
• Google Cloud - Google Cloud Platform
• Azure - Microsoft Azure
• Cloudflare - Cloudflare
• DigitalOcean - DigitalOcean
• Linode - Linode/Akamai
• OVH - OVHcloud
• Hetzner - Hetzner
• And others...

Threat Object

The threat object provides risk assessment for the IP:

{
  "threat": {
    "score": 75,
    "level": "high",
    "explanation": [
      "Known malicious IP range",
      "Associated with spam activity"
    ]
  }
}

Field	Type	Description
score	integer	Threat score from 0 (safe) to 100 (high risk)
level	string	Human-readable threat level
explanation	array	Reasons contributing to the score

Threat Levels

Level	Score Range	Description
low	0-24	No significant risk detected
medium	25-49	Some risk factors present
high	50-74	Significant risk factors
critical	75-100	Known malicious activity

Threat Explanations

Common explanations include:

• "Known malicious IP range"
• "Associated with spam activity"
• "Part of botnet infrastructure"
• "Scanning activity detected"
• "Previous abuse reports"
• "Tor exit node"
• "Open proxy"

Batch Lookup Response

Batch lookups return a map of IP addresses to their results:

{
  "data": {
    "8.8.8.8": {
      "ip": "8.8.8.8",
      "prefix": "8.8.8.0/24",
      "asn": 15169,
      "asn_name": "Google LLC",
      "country": "US",
      "detection": { ... },
      "threat": { ... }
    },
    "1.1.1.1": {
      "ip": "1.1.1.1",
      "prefix": "1.1.1.0/24",
      "asn": 13335,
      "asn_name": "Cloudflare, Inc.",
      "country": "US",
      "detection": { ... },
      "threat": { ... }
    }
  },
  "meta": { ... }
}

Missing IPs

If an IP is not found in the database, it will be omitted from the results. Always check if an IP exists in the response.

ASN Lookup Response

{
  "data": {
    "asn": 15169,
    "name": "Google LLC",
    "country": "US",
    "rir": "ARIN",
    "allocation_date": "2000-03-30"
  },
  "meta": { ... }
}

ASN Fields

Field	Type	Description
asn	integer	Autonomous System Number
name	string	Organization name
country	string	ISO 3166-1 alpha-2 country code
rir	string	Regional Internet Registry
allocation_date	string	Date of ASN allocation (YYYY-MM-DD)

ASN with Prefixes

When include_prefixes=true:

{
  "data": {
    "asn": 15169,
    "name": "Google LLC",
    "country": "US",
    "rir": "ARIN",
    "allocation_date": "2000-03-30",
    "prefixes": [
      {
        "prefix": "8.8.8.0/24",
        "country": "US",
        "is_datacenter": true,
        "threat_score": 0
      }
    ],
    "total_prefixes": 1234
  },
  "meta": { ... }
}

Field	Type	Description
prefixes	array	List of IP prefixes
total_prefixes	integer	Total number of prefixes for this ASN

Error Response

All error responses follow this format:

{
  "data": {
    "error": "invalid IP address",
    "code": "INVALID_IP",
    "details": "Expected IPv4 or IPv6 format"
  },
  "meta": {
    "processing_time_ms": 0
  }
}

Error Fields

Field	Type	Description
error	string	Human-readable error message
code	string	Machine-readable error code
details	string	Additional error details (optional)

Error Codes

Code	HTTP Status	Description
MISSING_IP	400	IP parameter is required but missing
INVALID_IP	400	IP address format is invalid
INVALID_JSON	400	Request body is not valid JSON
MISSING_IPS	400	IPs array is required for batch lookup
BATCH_TOO_LARGE	400	Batch size exceeds limit
INVALID_ASN	400	ASN parameter is invalid
UNAUTHORIZED	401	Missing or invalid API key
NOT_FOUND	404	No data found for the IP or ASN
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded
LOOKUP_ERROR	500	Internal lookup error
NOT_CONFIGURED	503	Service not properly configured

Statistics Response

{
  "data": {
    "version": 1,
    "total_ranges": 1500000,
    "total_asns": 75000,
    "cache_size": 50000,
    "cache_hit_rate": 0.85,
    "lookups_total": 1000000,
    "lookups_cached": 850000
  },
  "meta": { ... }
}

Field	Type	Description
version	integer	Current dataset version
total_ranges	integer	Number of IP ranges in the dataset
total_asns	integer	Number of ASNs in the dataset
cache_size	integer	Maximum cache entries
cache_hit_rate	float	Cache hit rate (0.0 to 1.0)
lookups_total	integer	Total lookups performed
lookups_cached	integer	Lookups served from cache

TypeScript Definitions

For TypeScript users, here are the complete type definitions:

interface Meta {
  request_id: string;
  processing_time_ms: number;
  cache_status?: 'HIT' | 'MISS';
  dataset_version?: number;
}

interface Detection {
  is_datacenter: boolean;
  is_tor_exit: boolean;
  is_proxy: boolean;
  is_vpn: boolean;
  is_residential: boolean;
  is_mobile: boolean;
  is_ai_crawler: boolean;
  ai_company?: string;
  cloud_provider?: string;
}

interface Threat {
  score: number;
  level: 'low' | 'medium' | 'high' | 'critical';
  explanation?: string[];
}

interface IPLookupResult {
  ip: string;
  prefix: string;
  asn: number;
  asn_name?: string;
  country: string;
  rir?: 'ARIN' | 'RIPE' | 'APNIC' | 'LACNIC' | 'AFRINIC';
  connection_type?: 'residential' | 'datacenter' | 'mobile' | 'business' | 'education';
  detection?: Detection;
  threat?: Threat;
}

interface IPLookupResponse {
  data: IPLookupResult;
  meta: Meta;
}

interface BatchLookupResponse {
  data: Record<string, IPLookupResult>;
  meta: Meta;
}

interface ASNInfo {
  asn: number;
  name: string;
  country: string;
  rir: 'ARIN' | 'RIPE' | 'APNIC' | 'LACNIC' | 'AFRINIC';
  allocation_date: string;
}

interface ASNPrefix {
  prefix: string;
  country: string;
  is_datacenter: boolean;
  threat_score: number;
}

interface ASNInfoWithPrefixes extends ASNInfo {
  prefixes: ASNPrefix[];
  total_prefixes: number;
}

interface ASNLookupResponse {
  data: ASNInfo | ASNInfoWithPrefixes;
  meta: Meta;
}

interface ErrorData {
  error: string;
  code: string;
  details?: string;
}

interface ErrorResponse {
  data: ErrorData;
  meta: Meta;
}

Content Types

Request Content-Type

For POST requests (batch lookup), set:

Content-Type: application/json

Response Content-Type

All API responses use:

Content-Type: application/json; charset=utf-8

Accept Header

While optional, you can explicitly request JSON:

Accept: application/json

Encoding

• All responses are UTF-8 encoded
• IP addresses are normalized (e.g., IPv6 addresses are fully expanded)
• Dates are in ISO 8601 format (YYYY-MM-DD)
• Timestamps are Unix epoch (seconds since 1970-01-01 00:00:00 UTC)