# IP Geolocation API — locate any IPv4/IPv6 address: country, region, city, coordinates, timezone, ASN, ISP and hosting/datacenter flag

> geolocate ONE IPv4/IPv6 → country/region/city/lat-lon/timezone/ASN/ISP/org + hosting flag
> ReefAPI engine `ip-geolocation` · 2 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/ip-geolocation/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /ip-geolocation/v1/lookup — 1 credit
geolocate ONE IPv4/IPv6 → country/region/city/lat-lon/timezone/ASN/ISP/org + hosting flag

**Parameters:**
- `ip` (string, required) — A single IPv4 or IPv6 address to geolocate (e.g. 8.8.8.8 or 2001:4860:4860::8888).
- `lang` (string, optional, default "en") — Preferred language for place names (country/region/city), e.g. en, de, fr, es, ru, ja. Falls back to English when a locale name is unavailable.

**Returns:** flat record: status, country_code/name, region(+code), city, latitude, longitude, timezone, utc_offset, asn, as_org, isp, network, security{is_hosting,is_proxy,is_vpn,is_tor}, country{} metadata bundle

**Example request body:**
```json
{
  "ip": "8.8.8.8"
}
```

### POST /ip-geolocation/v1/batch — 2 credits
geolocate up to 100 IPs in one call

**Parameters:**
- `ips` (array, required) — Up to 100 IPv4/IPv6 addresses. A JSON array, OR a comma/space/newline-separated string. Bad/private IPs are kept (per-item status) so one bad entry never fails the call.
- `lang` (string, optional, default "en") — Preferred language for place names (country/region/city), e.g. en, de, fr, es, ru, ja. Falls back to English when a locale name is unavailable.

**Returns:** count, found_count, results[] (each the same flat record as lookup)

**Example request body:**
```json
{
  "ips": [
    "8.8.8.8",
    "1.1.1.1",
    "192.168.0.1",
    "nonsense"
  ]
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=ip-geolocation
- Human docs page: https://reefapi.com/docs/ip-geolocation
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt