---
name: ip-geolocation
description: Look up IP address geolocation data using the ipcat.org JSON API, including network, ASN, organization, city, region, country, coordinates, postal code, and timezone.
---

# IP Geolocation

Use this skill when the user asks to identify the approximate location, network, ASN, organization, country, city, timezone, or coordinates for an IP address.

## API

Send a `GET` request to:

```text
https://ipcat.org/json
```

By default, the API looks up the caller's IP address.

### Optional query parameters

| Parameter  | Description                               | Default   |
| ---------- | ----------------------------------------- | --------- |
| `ip`       | Specific IPv4 or IPv6 address to look up. | Caller IP |
| `language` | Language code for localized place names.  | `en`      |

Example requests:

```bash
curl 'https://ipcat.org/json'
```

```bash
curl 'https://ipcat.org/json?ip=8.8.8.8'
```

```bash
curl 'https://ipcat.org/json?ip=8.8.8.8&language=es'
```

## Expected JSON fields

The response may include:

```json
{
  "ip": "8.8.8.8",
  "network": "8.8.8.0/24",
  "found": true,
  "asn": 15169,
  "organization": "Google LLC",
  "continent": "North America",
  "country": "United States",
  "country_code": "US",
  "latitude": 37.751,
  "longitude": -97.822,
  "timezone": "America/Chicago"
}
```

Important fields:

- `ip`: IP address that was looked up.
- `network`: CIDR network range associated with the IP.
- `found`: Whether geolocation data was found.
- `asn`: Autonomous System Number.
- `organization`: Network or ISP organization.
- `continent`: Continent name.
- `country`: Country name.
- `country_code`: ISO country code.
- `city`: City name, when available.
- `region`: State, province, or administrative region.
- `region_code`: Short region code, when available.
- `postal_code`: Postal or ZIP code, when available.
- `latitude`: Approximate latitude.
- `longitude`: Approximate longitude.
- `timezone`: IANA timezone identifier.

## Usage guidance

1. Validate that any user-provided IP address is a plausible IPv4 or IPv6 address before calling the API.
2. If the user does not provide an IP address, call `https://ipcat.org/json` to look up the caller IP.
3. If the user provides an IP address, call `https://ipcat.org/json?ip=<addr>`, URL-encoding the address.
4. If the user asks for localized names, include `language=<lang>`.
5. Parse the JSON response and report only fields present in the response.
6. If `found` is `false`, explain that no geolocation record was found for the IP address.
7. Make clear that IP geolocation is approximate and may identify the ISP, VPN, proxy, or network exit location rather than a user's exact physical location.

## Response format

For a successful lookup, summarize the result in a compact, user-friendly form:

```text
IP: 8.8.8.8
Network: 8.8.8.0/24
ASN: AS15169
Organization: Google LLC
Location: United States
Coordinates: 37.751, -97.822
Timezone: America/Chicago
```

When coordinates are available, include both latitude and longitude together. When a field is missing, omit it rather than guessing.

## Privacy and safety

Use documentation examples with non-residential, public infrastructure IP addresses such as `8.8.8.8`; avoid residential IP addresses in examples or logs.

IP geolocation data is approximate and should not be presented as a precise home, office, or personal address. Do not use this skill to help doxx, stalk, harass, or identify a private person's exact location. For private individuals, provide only coarse location details such as country, region, city, ISP, and timezone when available.