# Edge IP Geolocation API (ipapi) — PayloadAPI LLM & Agent Reference

> Ultra-low latency IP intelligence and geolocation API. Lookup country, city, ASN, ISP, timezone, and proxy/VPN flags with edge caching.

## Quick Facts
- **Catalog Page**: https://payloadapi.com/apis/ipapi
- **LLM Context URL**: https://payloadapi.com/apis/ipapi/llms.txt
- **Gateway Origin**: `https://gateway.payloadapi.com`
- **Trust Score**: 0/100
- **Published Versions**: `v1` (REST)

## Authentication
All requests route through the PayloadAPI Edge Gateway and authenticate with a buyer application key in the `Authorization` header. Never hardcode keys; export `$PAYLOADAPI_KEY` in your environment:

```bash
export PAYLOADAPI_KEY="payload_live_<app_public_id>.<secret>"
```

Required request header:
```http
Authorization: Bearer $PAYLOADAPI_KEY
```

## Edge REST-to-MCP Bridge (Model Context Protocol)
Every REST version of `ipapi` is automatically exposed as a JSON-RPC 2.0 MCP server at the edge. Discovery methods (`initialize`, `notifications/initialized`, `ping`, `tools/list`) are **quota-free**; `tools/call` executions are metered against your active plan.

- **MCP Server Endpoint**: `POST https://gateway.payloadapi.com/ipapi/v1/mcp`

### One-Click MCP Configuration (`.cursor/mcp.json` / `claude_desktop_config.json` / Antigravity)
```json
{
  "mcpServers": {
    "payloadapi-ipapi": {
      "url": "https://gateway.payloadapi.com/ipapi/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PAYLOADAPI_KEY}"
      }
    }
  }
}
```

### Synthesized MCP Tools
- `get_api_v1_checkgeoip` (`GET /api/v1/checkgeoip`, `v1`, no required params) — Check GeoIP (Legacy Compatibility)
- `get_v1_ip` (`GET /v1/ip`, `v1`, no required params) — Lookup IP Geolocation and Network Intelligence

## Live Plans & Quota Terms
- Pay-As-You-Go ($0.00, 0 included requests, $0.000200/req usage rate)
- Free (Free: 500 requests / month)

## Endpoints

### Version `v1` (REST)

- **Gateway Base Path**: `https://gateway.payloadapi.com/ipapi/v1`
- **MCP Bridge Endpoint**: `POST https://gateway.payloadapi.com/ipapi/v1/mcp`

#### `GET /v1/ip`
**Lookup IP Geolocation and Network Intelligence**
Lookup geolocation coordinates, city, country, ASN, ISP, timezone, and risk/VPN status for IPv4 or IPv6.
- **Gateway URL**: `https://gateway.payloadapi.com/ipapi/v1/v1/ip`
- **Synthesized MCP Tool**: `get_v1_ip`
- **Parameters**:
  - `ip` (query, string, optional) — The IPv4 or IPv6 address to lookup. If omitted, resolves caller IP.

```bash
curl --request GET 'https://gateway.payloadapi.com/ipapi/v1/ip?ip=8.8.8.8' --header "Authorization: Bearer $PAYLOADAPI_KEY"
```

#### `GET /api/v1/checkgeoip`
**Check GeoIP (Legacy Compatibility)**
Compatible endpoint for GeoIP lookup and ASN intelligence.
- **Gateway URL**: `https://gateway.payloadapi.com/ipapi/v1/api/v1/checkgeoip`
- **Synthesized MCP Tool**: `get_api_v1_checkgeoip`
- **Parameters**:
  - `ip` (query, string, optional) — The IPv4 or IPv6 address to lookup. If omitted, resolves caller IP.

```bash
curl --request GET 'https://gateway.payloadapi.com/ipapi/v1/api/v1/checkgeoip?ip=8.8.8.8' --header "Authorization: Bearer $PAYLOADAPI_KEY"
```