IP.LS Command Documentation

IP.LS is a free IP address lookup service. Query your public IP or inspect any IP/domain — just like the ls command.

Quick Start

Get Your Public IP

curl ip.ls
# => 1.2.3.4

Note: curl ip.ls returns your IPv4 or IPv6 address depending on your network. Use curl -4 ip.ls or curl -6 ip.ls to force a specific stack. Clients that cannot pick a stack (browsers, PowerShell, most HTTP libraries) can use the single-stack hostnames 4.ip.ls (A record only) and 6.ip.ls (AAAA record only) instead — DNS selects the stack, so no flag is needed; 4.ip.ls/json and 6.ip.ls/json return the same JSON. If 6.ip.ls cannot connect, that client has no usable IPv6.

Get IP Info as JSON

curl ip.ls/json

{
  "ip": "1.2.3.4",
  "city": "San Francisco",
  "region": "California",
  "country": "US",
  "loc": "37.7749,-122.4194",
  "org": "AS13335 Cloudflare, Inc.",
  "timezone": "America/Los_Angeles",
  "continent": "North America"
}

Single Field Lookup

Return a single field as plain text — handy in shell scripts.

curl ip.ls/city      # => San Francisco
curl ip.ls/loc       # => 37.7749,-122.4194
curl ip.ls/org       # => AS13335 Cloudflare, Inc.
curl ip.ls/timezone  # => America/Los_Angeles
curl ip.ls/continent # => North America

Lookup a Specific IP

curl ip.ls/8.8.8.8
curl ip.ls/example.com   # domain lookup

{
  "ip": "8.8.8.8",
  "city": "Mountain View",
  "region": "California",
  "country": "US",
  "loc": "37.4220,-122.0850",
  "org": "AS15169 Google LLC",
  "timezone": "America/Los_Angeles",
  "continent": "North America"
}

Domain Lookup

curl ip.ls/example.com

{
  "ip": "104.20.23.154",
  "domain": "example.com",
  "city": "Toronto",
  "region": "Ontario",
  "country": "CA",
  "loc": "43.6532,-79.3832",
  "org": "AS13335 Cloudflare, Inc.",
  "timezone": "",
  "continent": "North America"
}

Note: the domain field is present only when a domain was looked up — it echoes the queried domain. IP lookups do not include it. The returned ip is one of the resolved addresses; geolocation of CDN/anycast domains reflects that edge node, not the site operator.

Multi-IP domains: the primary result is served at the base path, while /<ip>/resolved returns all resolved A/AAAA records (deduplicated, max 6, primary first) as a uniform array. Each entry matches the standard record shape (including domain echo).

curl ip.ls/baidu.com/resolved

[
  { "ip": "111.63.65.103", "domain": "baidu.com", "city": "Shijiazhuang", "region": "Hebei", "country": "CN", "loc": "38.0360,114.4700", "org": "AS24547 Hebei Mobile", "timezone": "Asia/Shanghai", "continent": "Asia" }
]

# Single field of a specific IP
curl ip.ls/8.8.8.8/city      # => Mountain View
curl ip.ls/8.8.8.8/loc       # => 37.4220,-122.0850

Note: IPv4 and IPv6 are both supported. There is no postal field and no /postal path — the free DB-IP Lite database carries no postal data. There is no protocol field either: /<ip>/resolved entries carry the standard record shape (plus the domain echo for domain lookups) and nothing more. timezone is empty when the coordinates are unknown (common for anycast and CDN edge addresses).

Help & Usage

curl ip.ls/help

Check User-Agent

curl ip.ls/ua
# => curl/8.7.1

View All Request Headers

curl ip.ls/headers

API Endpoints

Core

Method Path Description Content-Type
GET / Public IP (plain text) text/plain
GET /json IP info as JSON application/json
GET /:ip Lookup any IP as JSON application/json
GET /:ip/resolved All resolved A/AAAA records as a JSON array application/json
GET /embed Embeddable live IP card (iframe) text/html
GET /ai Redirect to the AI/MCP cards on the home page —

Single Field (plain text)

Path (self) Path (any IP) Returns
/city /:ip/city City
/region /:ip/region Region
/country /:ip/country Country code
/loc /:ip/loc "lat,lon"
/org /:ip/org ASN + ISP
/timezone /:ip/timezone Timezone
/continent /:ip/continent Continent name

Utility

Method Path Description Content-Type
GET /ua User-Agent string text/plain
GET /headers All request headers as JSON application/json
GET /help Usage & tips text/plain
GET /docs This documentation text/html or text/plain
GET /* Non-HTML clients: your IP; browsers: 404 page text/plain or text/html

Response Fields

Field Description
ip Public IP address
domain Queried domain — present only for domain lookups
city City name
region Region/state name
country ISO 3166-1 alpha-2 country code
loc Latitude,longitude
org ASN + ISP / organization name
timezone IANA timezone
continent Continent full name (English)

Note: Fields may be empty when the corresponding data is unavailable.

Rate Limits

IP.LS runs on a self-hosted VPS. There are no hard rate limits, but please use responsibly. For high-volume needs, consider self-hosting or contact us.

Error Responses

Content Negotiation

Requests whose Accept header contains text/html are treated as browsers, not as API clients:

So curl ip.ls/8.8.8.8 and opening https://ip.ls/8.8.8.8 in a browser deliberately do different things. To force machine output regardless of Accept, use a client that does not send text/html.

Embed

Embed a live IP card (showing each visitor's own IP, location and ISP) on any website with an iframe:

<iframe src="https://ip.ls/embed" style="border:0;width:280px;height:96px" loading="lazy" title="IP.LS"></iframe>

Options: ?lang=zh (Chinese), ?theme=dark / ?theme=light (default auto, follows the visitor's dark-mode setting).

MCP

A standard MCP (Model Context Protocol) Streamable HTTP endpoint is available at https://ip.ls/mcp (JSON-RPC 2.0), exposing five tools: ip_lookup (single or batch), ip_resolved (all DNS records of a domain), ip_self (your own public IP), headers and ua. No API key, no sign-up.

Client configuration:

Claude Code

claude mcp add --transport http ipls-ip-lookup-service https://ip.ls/mcp

Claude Desktop — mcpServers in claude_desktop_config.json:

{ "mcpServers": { "ipls-ip-lookup-service": { "type": "http", "url": "https://ip.ls/mcp" } } }

Cursor — .cursor/mcp.json:

{ "mcpServers": { "ipls-ip-lookup-service": { "type": "http", "url": "https://ip.ls/mcp" } } }

opencode — the mcp field in opencode.json:

{ "mcp": { "ipls-ip-lookup-service": { "type": "remote", "url": "https://ip.ls/mcp", "enabled": true } } }

GitHub Copilot — .vscode/mcp.json:

{ "servers": { "ipls-ip-lookup-service": { "type": "http", "url": "https://ip.ls/mcp" } } }

Once connected, the AI can answer directly: geolocation of any IP or domain, your public IP, request headers and UA.

Notes