# ipatlas

> Fast IP geolocation API and hosted Model Context Protocol (MCP) server. Turn any public IPv4 or IPv6 address into continent, country, EU membership, region, approximate city, coordinates, IANA time zone, and ASN (internet provider). Free for 50,000 lookups/month with no credit card; keyless tier allows 1,000 lookups/day per IP. Looked-up IP addresses are never logged.

- Base URL: `https://api.ipatlas.dev`
- Website: https://ipatlas.dev
- Documentation: https://ipatlas.dev/docs
- AI Agents & MCP Setup: https://ipatlas.dev/ai-agents
- OpenAPI 3.1 Specification: https://ipatlas.dev/openapi.json
- Pricing: https://ipatlas.dev/pricing

## Hosted MCP Server (Streamable HTTP)

Connect Claude Desktop, Claude Code, Cursor, or any MCP client directly to the hosted remote endpoint — no local package or binary required:

- Endpoint: `POST https://api.ipatlas.dev/mcp` (JSON-RPC 2.0 over HTTP POST; `initialize`, `ping`, `tools/list`, `tools/call`; notifications return `202 Accepted`)
- Authentication: Optional `Authorization: Bearer ipa_...` (or `X-API-Key: ipa_...`). Keyless requests are allowed up to 1,000 lookups/day per IP (10 req/s, 4 in-flight).

### MCP Tools

- `lookup_ip` — Look up geolocation for a single public IPv4 or IPv6 address.
  - Arguments: `{"ip": "8.8.8.8"}`
- `my_location` — Look up geolocation for the caller's own public IP address as seen by the API.
  - Arguments: `{}`
- `lookup_batch` — Look up geolocation for 1 to 100 public IPv4 or IPv6 addresses in one call. All IPs are validated (format and public address check) before charging quota; if any entry is invalid or private/reserved, the call returns an MCP tool error (`isError: true`) and charges nothing. Each IP in a valid batch counts as one lookup against your quota.
  - Arguments: `{"ips": ["8.8.8.8", "2606:4700:4700::1111"]}`

Private, reserved, or invalid IP addresses return an MCP tool result with `isError: true` and a plain-language explanation.

## REST API Endpoints

- `GET https://api.ipatlas.dev/v1/me` — Look up the caller's public IP address.
- `GET https://api.ipatlas.dev/v1/{ip}` — Look up any IPv4 or IPv6 address (e.g. `/v1/8.8.8.8`).
- `POST https://api.ipatlas.dev/v1/signup` — Body `{"email":"you@example.com"}`. Creates a free API key (50,000 lookups/month), returned once (HTTP 201) as `{"key":"ipa_...","monthly_quota":50000,"note":"..."}`.
- `GET https://api.ipatlas.dev/v1/account` — Authenticated with your API key. Returns `{plan, status, rps, daily_quota, used_today, monthly_quota, used_this_month, max_inflight}`.
- `POST https://api.ipatlas.dev/v1/checkout` — Authenticated with your API key; body `{"plan":"dev|pro|scale"}`. Returns a Stripe Checkout `{"url":"..."}`.
- `GET https://api.ipatlas.dev/health` — Service status, version, and GeoIP data build date (`{"status":"ok","version":"...","data_build":"YYYY-MM-DD"}`).

## Lookup Response Fields

```json
{
  "ip": "8.8.8.8",
  "continent": "NA",
  "country_code": "US",
  "country": "United States",
  "is_eu": false,
  "region": "California",
  "city": "Mountain View",
  "latitude": 37.422,
  "longitude": -122.085,
  "timezone": "America/Los_Angeles",
  "asn": { "number": 15169, "organization": "Google LLC" },
  "attribution": "IP geolocation data by DB-IP.com (CC BY 4.0, https://db-ip.com). Served by ipatlas.dev"
}
```

- Fields are omitted when the database has no value for that field.
- Private and reserved IP addresses on `GET /v1/{ip}` return `200` with `{"ip": "192.168.0.1", "reserved": true}`.
- Unknown unallocated public ranges without data return `404` (`{"error": "no geolocation data for this IP"}`).

## Authentication

Pass an optional API key via header (recommended) or query parameter:

- `Authorization: Bearer ipa_...`
- `X-API-Key: ipa_...`
- `?key=ipa_...`

## Plans & Rate Limits

| Plan | Price | req/s | req/day | req/month | Max in-flight |
| --- | --- | --- | --- | --- | --- |
| Keyless (per IP) | $0 | 10 | 1,000 | n/a | 4 |
| Free | $0 | 50 | 5,000 | 50,000 | 8 |
| Dev | $9/mo | 50 | 50,000 | 500,000 | 16 |
| Pro | $29/mo | 100 | 300,000 | 3,000,000 | 16 |
| Scale | $99/mo | 200 | 1,500,000 | 15,000,000 | 32 |

Lookup responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `X-RateLimit-Window` (`second`, `day`, `month`, or `concurrency`). `429 Too Many Requests` responses add `Retry-After` (seconds) and JSON `{error, window, limit, retry_after, upgrade_url?}`.

## Accuracy, Privacy & Attribution

- Accuracy: Country is usually right. City is approximate and can be off by tens of kilometres, especially on mobile networks, VPNs, and corporate connections. Time zone is derived from coordinates.
- Privacy: Looked-up IP addresses are never logged to disk or stored in our database.
- Attribution: Data is powered by DB-IP City Lite and ASN Lite (CC BY 4.0, https://db-ip.com), updated monthly. Free plan and keyless users displaying or using data in a public product must credit DB-IP.com.
- Operator: ipatlas · the Netherlands · Contact: hello@ipatlas.dev