API Documentation — ipaddress.ai

GET /

Returns the caller's IP address. CLI tools get plain text, browsers get the HTML page, and Accept: application/json returns JSON.

Returns: text/plain · text/html · application/json

Request

curl ipaddress.ai

Response

203.0.113.42

GET /json

Returns full IP information as JSON — geolocation, ASN, hostname, and user agent.

Returns: application/json

Request

curl ipaddress.ai/json

Response

{ "ip": "203.0.113.42", "ip_decimal": 3405803818, "country": "Canada", "country_eu": false, "country_iso": "CA", "city": "Vancouver", "hostname": "vc.shawcable.net", "latitude": 49.2827, "longitude": -123.1207, "asn": "AS6327", "asn_org": "Shaw Communications", "user_agent": { "product": "curl", "version": "8.7.1", "raw_value": "curl/8.7.1" } }

Response Fields

Field	Type	Description
ip	string	IP address
ip_decimal	integer	Decimal representation of the IP
country	string	Country name
country_eu	boolean	Whether the country is in the EU
country_iso	string	ISO 3166-1 alpha-2 country code
city	string	City name
hostname	string	Reverse DNS hostname
latitude	float	Approximate latitude
longitude	float	Approximate longitude
asn	string	Autonomous System Number (e.g. AS6327)
asn_org	string	ASN organization / ISP name
user_agent	object	Parsed user agent with product, version, raw_value

GET /ip

Always returns just the IP address as plain text, regardless of user agent.

Returns: text/plain

Request

curl ipaddress.ai/ip

Response

203.0.113.42

GET /country

Returns the country name associated with the caller's IP.

Returns: text/plain

Request

curl ipaddress.ai/country

Response

Canada

GET /country-iso

Returns the ISO 3166-1 alpha-2 country code.

Returns: text/plain

Request

curl ipaddress.ai/country-iso

Response

CA

GET /city

Returns the city name associated with the caller's IP.

Returns: text/plain

Request

curl ipaddress.ai/city

Response

Vancouver

GET /asn

Returns the Autonomous System Number for the caller's IP.

Returns: text/plain

Request

curl ipaddress.ai/asn

Response

AS6327

GET /coordinates

Returns the approximate latitude and longitude as comma-separated values.

Returns: text/plain

Request

curl ipaddress.ai/coordinates

Response

49.282700,-123.120700

GET /lookup/{ip}

Look up geolocation and network information for any public IP address.

Returns: application/json · text/html

Path Parameters

Parameter	Type	Description
ip required	string	IPv4 or IPv6 address (e.g. 8.8.8.8, 2001:4860::8888)

Request

curl ipaddress.ai/lookup/8.8.8.8

Response

{ "ip": "8.8.8.8", "ip_decimal": 134744072, "country": "United States", "country_eu": false, "country_iso": "US", "latitude": 37.751, "longitude": -97.822, "asn": "AS15169", "asn_org": "Google LLC" }

Returns 400 for invalid IPs. Browser requests get the full HTML page with a map.

GET /port/{port}

Test if a specific port on the caller's IP is reachable from the internet.

Returns: application/json

Path Parameters

Parameter	Type	Description
port required	integer	Port number between 1 and 65535

Request

curl ipaddress.ai/port/443

Response

{ "ip": "203.0.113.42", "port": 443, "reachable": true }

Returns 400 for invalid port numbers (0, negative, or above 65535).

GET /health

Health check endpoint. Returns a simple status for monitoring.

Returns: application/json

Request

curl ipaddress.ai/health

Response

{"status":"OK"}