# wtfip.io — full documentation

wtfip.io is a single-purpose public web service that returns the CALLER'S OWN
public IP address together with its approximate geolocation (country name, city,
ISO 3166-1 country codes). It is free, requires no API key, no authentication,
and no rate-limit signup. The service reports only the IP of whoever calls it;
there is no bulk or arbitrary-IP lookup.

Geolocation data comes from the IP2Location LITE DB11 database and is
approximate. Do not rely on it for precise location or for security decisions.

## Base URL

https://wtfip.io

## Response fields

- ip: the caller's public IP address (IPv4 or IPv6), as a string.
- country_name: full country name, e.g. "United States of America".
- city_name: city the IP resolves to, e.g. "Ashburn".
- country_code: ISO 3166-1 alpha-3, LOWERCASE, e.g. "usa".
- country_code_short: ISO 3166-1 alpha-2, e.g. "US".
- ip_list: array of the above objects (present in JSON) when more than one IP is detected.

## Endpoints and representations

### GET /json — JSON (preferred for programs)

    curl -s https://wtfip.io/json

Example response:

    {
      "ip": "203.0.113.7",
      "country_name": "United States of America",
      "city_name": "Ashburn",
      "country_code": "usa",
      "country_code_short": "US",
      "ip_list": [
        { "ip": "203.0.113.7", "country_name": "United States of America", "city_name": "Ashburn", "country_code": "usa", "country_code_short": "US" }
      ]
    }

### GET /xml — XML

    curl -s https://wtfip.io/xml

Returns the same fields under a <wtfip.io> root element.

### GET / with Accept: text/markdown — Markdown

    curl -s -H 'Accept: text/markdown' https://wtfip.io/

Returns a Markdown document with the IP result and links to the machine-readable
endpoints. The response carries an x-markdown-tokens header with an approximate
token count.

### GET / — HTML or plain text

Browsers receive an HTML page. Known CLI user-agents (curl, wget, httpie,
python-requests, node-fetch, xh, and similar) receive a plain-text body:

    IP: 203.0.113.7
    Country: United States of America
    City: Ashburn
    Country Code: usa

## Model Context Protocol (MCP)

An MCP server is exposed over streamable-HTTP at https://wtfip.io/mcp . It
advertises a single tool:

- get_my_ip — returns the caller's public IP and geolocation. Takes no arguments.
  Structured output mirrors the /json fields (ip, country_name, city_name,
  country_code, country_code_short).

The MCP server card is at https://wtfip.io/.well-known/mcp/server-card.json .

## Discovery surfaces

- OpenAPI 3.1 description: https://wtfip.io/openapi.json
- API catalog (RFC 9727 / RFC 9264 linkset): https://wtfip.io/.well-known/api-catalog
- Agent Skills index: https://wtfip.io/.well-known/agent-skills/index.json
- Agent Skill document: https://wtfip.io/.well-known/agent-skills/wtfip-ip-geo/SKILL.md
- Human docs page: https://wtfip.io/docs
- RFC 8288 Link header advertising the catalog and docs is present on /, /json and /xml.
- Concise index: https://wtfip.io/llms.txt

## Errors

- 200: success.
- 429: too many requests — the edge rate-limiter throttled you; back off and retry.
- 500: the geolocation database could not resolve the request (rare, transient).
- The MCP get_my_ip tool returns a tool-level error result when no client-IP
  forwarding header is present (e.g. local development).

There are no 4xx authentication errors because there is no authentication.

## Rate limits and auth

No authentication is required. There are no published per-key quotas; a single
global edge rate-limiter (Traefik) applies best-effort abuse protection. Be
reasonable and cache the result — your own IP does not change on every request.

## Terms and data license

Terms of Service and the AI usage policy are at https://wtfip.io/terms .
Geolocation data is IP2Location LITE (CC BY-SA 4.0, https://lite.ip2location.com ).

## Contact

Stanislav Gumeniuk — https://gumeniuk.com