# host.sh

> What's my IP? See your IP address, location, ISP and VPN or proxy flags in a browser or with curl host.sh. JSON API for any IPv4 or IPv6 address.

host.sh shows the IP address you connect from and what it says about you: approximate location, time zone, ISP, ASN and connection flags such as VPN, proxy and Tor. You get the same answer in a terminal with `curl host.sh`, and the JSON API looks up any IPv4 or IPv6 address.

- `curl host.sh`: your IP details as JSON, no key needed
- `curl host.sh/ip`: just your IP
- `https://api.host.sh/v2/lookup/{ip}`: the JSON API, any IPv4 or IPv6 address with a token

The full API reference is the [OpenAPI spec](https://api.host.sh/v2/openapi.yaml) (OpenAPI 3.1, YAML).

Guides with examples in curl, JavaScript, Python, PHP and Go are in the [API docs](https://www.host.sh/docs/index.md): [lookup](https://www.host.sh/docs/lookup/index.md), [batch](https://www.host.sh/docs/batch/index.md), [response fields](https://www.host.sh/docs/fields/index.md), [errors](https://www.host.sh/docs/errors/index.md) and [rate limits](https://www.host.sh/docs/rate-limits/index.md).

## No token: your own IP

From a terminal, over HTTP or HTTPS. No key needed.

```sh
curl host.sh            # your IP details
curl host.sh/json       # same, as JSON
curl host.sh/ip         # just your IP
curl host.sh/city       # one field, plain text
curl host.sh/help       # all fields
```

Fields: ip, hostname, city, region, region_code, country, country_code, continent, continent_code, latitude, longitude, time_zone, offset, utc_offset, local_time, postal, flag, is_eu, currency, calling_code, isp, asn, asn_org, org.

Just your IP as text: `curl https://api.host.sh/v2/ip/` (or `https://ipv4.host.sh/v2/ip/` for IPv4). Without a token, the API looks up your own IP, 10 requests a minute.

Data credits: [/credits](https://www.host.sh/credits.md)

## With a token: any IP

JSON out. Send your token as a query parameter, a JSON body field, or a Bearer header. Tokens are invite only for now.

```sh
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.host.sh/v2/lookup/8.8.8.8

curl "https://api.host.sh/v2/lookup/?token=YOUR_TOKEN&ip=8.8.8.8"
```

### Parameters

| Parameter | What it does |
|---|---|
| `ip` | IPv4 or IPv6 address to look up, or put it in the path: `/v2/lookup/8.8.8.8` |
| `fields` | Only these parts of the answer, e.g. `fields=geo.country.code,connection.ip` |
| `format=text` | One field as plain text, e.g. `fields=geo.city.name&format=text` |
| `lang` | Place names in en, de, es, fr, ja, pt-BR, ru or zh-CN |
| `hostname=1` | Add the reverse DNS name |
| `pretty=1` | Indented JSON |
| `callback` | JSONP |
| `ua`, `al` | User-Agent and Accept-Language strings to parse |

### Batch

Up to 100 addresses in one request, answered in the same order.

```sh
curl -H "Authorization: Bearer YOUR_TOKEN" \
  -d '["8.8.8.8", "1.1.1.1"]' https://api.host.sh/v2/lookup/batch/
```

### Response

Example for 8.8.8.8. Which sections you get depends on your token's plan.

```json
{
  "geo": {
    "continent":   { "code": "NA", "name": "North America" },
    "country":     { "code": "US", "name": "United States", "flag": "🇺🇸",
                     "is_eu": false, "calling_code": "+1", "capital": "Washington D.C.",
                     "currency": { "code": "USD", "symbol": "$" } },
    "subdivision": { "code": null, "name": null },
    "city":        { "name": null },
    "postal_code": null,
    "latitude": 37.751, "longitude": -97.822, "radius": 1000,
    "timezone":    { "name": "America/Chicago", "offset": 300, "utc_offset": "-05:00",
                     "is_dst": true, "current_time": "2026-10-26T13:17:15-05:00" }
  },
  "connection": {
    "ip": "8.8.8.8", "version": 4, "bogon": false,
    "isp": { "asn": 15169, "name": "Google", "organization": "Google" },
    "type": "Corporate",
    "anonymity": { "vpn": { "score": 0 }, "tor": { "score": 0 }, … },
    "usage": { … }
  }
}
```

### Errors

```json
{"errors":[{"code":400,"message":"Bad request","reason":"INVALID_IP_ADDRESS",
  "detail":"ip must be an IPv4 or IPv6 address"}]}
```

## FAQ

### How do I find my IP address from the command line?

Run `curl host.sh` to get your IP address and its details as JSON, or `curl host.sh/ip` to get just the address.

### Is host.sh free?

Looking up your own IP is free and needs no key. Without a token, the API allows 10 requests a minute per IP.

### How do I get an API token?

API tokens are invite only for now. A token lets you look up any IP address and send batch lookups.

### Does host.sh support IPv6?

Yes, host.sh answers over IPv4 and IPv6 and looks up both kinds of address. Run `curl -4 host.sh/ip` or `curl -6 host.sh/ip` to see your address in one family.

### What does a lookup return?

A lookup returns the approximate city, region, country and continent, postal code, latitude and longitude, time zone and local time, currency, calling code, ISP, ASN and organization of an IP address. The JSON API can also return connection flags such as VPN, proxy and Tor.

### Does host.sh work over plain HTTP?

Yes, `curl host.sh` works over plain HTTP and HTTPS. The API at api.host.sh is HTTPS only and redirects plain HTTP requests to HTTPS.

### Can I look up many IP addresses at once?

Yes, the batch endpoint `https://api.host.sh/v2/lookup/batch/` takes up to 100 addresses in one request and needs a token.

### Is there an OpenAPI spec?

Yes, the OpenAPI 3.1 spec of the API is at https://api.host.sh/v2/openapi.yaml.

## Links

- [OpenAPI spec](https://api.host.sh/v2/openapi.yaml): the full API reference, OpenAPI 3.1 in YAML
- [Full docs in one file](https://www.host.sh/llms-full.txt): all host.sh docs as one Markdown file
- [Credits](https://www.host.sh/credits.md): licence notices for the public data host.sh builds on