API Documentation - ip2.world

Authentication

All API requests require an API key. Pass it as a query parameter or in the Authorization header.

# Via query parameter

GET /v1/lookup?ip=8.8.8.8&api_key=ip2_xxx

# Via Authorization header

GET /v1/lookup?ip=8.8.8.8
Authorization: Bearer ip2_xxx

IP Lookup

GET /api/v1/lookup

Parameters

Param	Required	Description
ip	Yes	IPv4 or IPv6 address to look up
product	No	Product tier: `lite`, `pro`, `max` (default: lite)
api_key	Yes*	Your API key (or use Authorization header)

Response - Lite

{
  "ip": "8.8.8.8",
  "product": "lite",
  "data": {
    "country": "United States", "country_code": "US",
    "region": "California", "city": "Mountain View",
    "latitude": 37.4056, "longitude": -122.0775,
    "timezone": "America/Los_Angeles"
  }
}

Response - Pro (+ risk data)

{
  ...lite fields...,
  "risk": {
    "is_proxy": false, "is_vpn": false, "is_tor": false,
    "is_hosting": true, "risk_score": 12
  }
}

Response - Max (+ organization data)

{
  ...pro fields...,
  "organization": {
    "asn": "AS15169", "name": "Google LLC",
    "domain": "google.com", "type": "hosting"
  }
}

Error Responses

HTTP	Description
400	Invalid or missing IP parameter
401	Missing or invalid API key
402	Insufficient balance
403	API key does not have access to requested product
404	Product not found or inactive

Rate Limits

Each API call deducts from your prepaid balance. Ensure sufficient balance before making requests. Rate limiting per key is enforced at 100 requests/second.

MCP Integration

Model Context Protocol (MCP) allows AI tools to discover and use ip2world as a native resource. Configure ip2world as an MCP server to let Claude, Cursor, or other MCP-compatible tools perform IP lookups directly.

MCP Server Configuration

{
  "mcpServers": {
    "ip2world": {
      "command": "npx",
      "args": ["-y", "@ip2world/mcp-server"],
      "env": {
        "IP2_API_KEY": "ip2_xxx"
      }
    }
  }
}

Available MCP Tools

Tool	Description
ip_lookup	Look up IP address information (geolocation, risk, ASN)
ip_batch_lookup	Batch look up multiple IP addresses

SKILL Integration

SKILL integration allows you to define ip2world as a reusable capability within AI agents like Claude Code. Agents can automatically invoke IP lookups during code analysis, security audits, or infrastructure review.

Skill Definition

# .claude/skills/ip2world.md
---
name: ip2world
description: Look up IP intelligence including geolocation, risk assessment, and ASN data
---

## Usage
When analyzing network traffic, reviewing logs, or auditing security,
use the ip2world API to look up IP addresses:

curl "https://api.ip2.world/v1/lookup?ip={ip}&api_key={key}"

How It Works

Define ip2world as a skill in your AI agent's configuration. The agent will automatically detect when IP intelligence is relevant to its task and invoke the lookup tool without manual prompting.

Agent Integration

For custom AI agents, ip2world provides Function Calling and Tool Use patterns compatible with OpenAI, Anthropic, and other LLM APIs. Define ip2world as a tool in your agent's tool schema.

Tool Definition (Anthropic)

{
  "tools": [{
    "name": "ip2world_lookup",
    "description": "Look up IP intelligence data for a given IP address",
    "input_schema": {
      "type": "object",
      "properties": {
        "ip": {"type": "string", "description": "IPv4 or IPv6 address"},
        "product": {"type": "string", "enum": ["lite", "pro", "max"]}
      },
      "required": ["ip"]
    }
  }]
}

Agent Workflow

# 1. User asks: "Where is 8.8.8.8 located?"
# 2. Agent decides to call ip2world_lookup tool
# 3. Your backend calls ip2world API
# 4. Return result to agent as tool_result
# 5. Agent generates natural language response