API
Plain text and JSON over HTTP or HTTPS. No key and no sign-up. Every endpoint answers GET requests and allows cross-origin requests from any site. Examples use addresses reserved for documentation.
curl ipchk.sh
prints your address
Hosts
Every path works on all three hosts. Use 4. or 6. to check one protocol on purpose.
| Host | Answers over | Typical use |
|---|---|---|
| ipchk.sh | IPv4 or IPv6 | The address your system prefers, usually IPv6 when both work |
| 4.ipchk.sh | IPv4 only | Your IPv4 address, even on a dual-stack connection |
| 6.ipchk.sh | IPv6 only | Your IPv6 address, or a connection error without IPv6 |
Plain text
One line with a trailing newline, ready for scripts. N/A means there is no answer, such as an address without a PTR record.
| Endpoint | Returns | Example |
|---|---|---|
| GET / | Your address, for command-line clients | 203.0.113.42 |
| GET /ip | Your address | 203.0.113.42 |
| GET /ptr | Reverse DNS for your address | host-42.acme.example |
| GET /asn | ASN and network name | AS64496 · ACME - Acme, Inc, US |
JSON
Served as application/json. /api/geo/ takes any public IPv4 or IPv6 address and is limited to 30 lookups per minute for each visitor.
| Endpoint | Returns |
|---|---|
| GET /api/ip | {"ip":"203.0.113.42"} |
| GET /api/ptr | {"ptr":"host-42.acme.example"} |
| GET /api/asn | {"asn":"AS64496 · ACME - Acme, Inc, US"} |
| GET /api/all | Address, reverse DNS, network and location in one response |
| GET /api/geo | Location for your address |
| GET /api/geo/{ip} | Location for any public address |
| GET /health | {"status":"ok","geo":"ready"} |
Response fields
A full response from 4.ipchk.sh/api/all. The geo object is also what /api/geo returns.
{
"ip": "203.0.113.42",
"ptr": "host-42.acme.example",
"asn": "AS64496 · ACME - Acme, Inc, US",
"geo": {
"country": "United States",
"country_code": "US",
"continent": "North America",
"continent_code": "NA",
"city": "Los Angeles",
"region": "California",
"region_code": "CA",
"postal": "90060",
"latitude": 34.0544,
"longitude": -118.244,
"timezone": "America/Los_Angeles",
"accuracy_km": 20,
"asn_number": 64496,
"org": "Acme, Inc"
},
"version": 4,
"type": "public",
"network": {
"asn": 64496,
"name": "Acme, Inc",
"prefix": "203.0.113.0/24",
"registry": "ARIN",
"country": "US",
"allocated": "2010-01-01"
}
}
| Field | Meaning |
|---|---|
| ip | The address that made the request |
| ptr | Reverse DNS name, or N/A |
| asn | Origin ASN and network name from Team Cymru |
| country_code | ISO 3166-1 alpha-2 code |
| region_code | ISO 3166-2 subdivision code |
| latitude, longitude | Approximate point, read with accuracy_km |
| accuracy_km | Radius of the estimate in kilometers |
| asn_number, org | Network from MaxMind GeoLite2 ASN |
| geo_error | Set instead of geo when location data is unavailable |
| version | 4 or 6 |
| type | public, or the kind of reserved address |
| network | ASN, name, announced prefix, registry, registry country and allocation date |
Errors
JSON endpoints answer errors with a status code and an error field.
| Status | When | Body |
|---|---|---|
| 400 | The address in the path is not a valid IP address | {"error":"invalid IP address"} |
| 422 | The address is private or reserved, such as 192.168.1.10 | {"error":"private or reserved address","type":"private"} |
| 429 | More than 30 lookups of other addresses in a minute | {"error":"too many lookups","retry_after":2} |
| 503 | Location data is loading or being updated | {"error":"location data not ready"} |
Embed widget
Add the script once, then place an element with one of the IDs below. The widget fills in the visitor's details as plain text, with no styling of its own.
<script src="https://ipchk.sh/widget.js"></script> <p>Your IP address is <span id="ipchk-ip"></span></p>
| Element ID | Shows |
|---|---|
| ipchk-ip | IPv4 address, or IPv6 when there is no IPv4 |
| ipchk-ip4 | IPv4 address |
| ipchk-ip6 | IPv6 address |
| ipchk-ptr4 | Reverse DNS for the IPv4 address |
| ipchk-ptr6 | Reverse DNS for the IPv6 address |
| ipchk-asn4 | ASN for the IPv4 address |
| ipchk-asn6 | ASN for the IPv6 address |