IP API Reference - netray.info

Returns your public IP address enriched with geolocation, ASN, reverse DNS, network classification, and threat intelligence. Use ?ip= to look up any address.

See also: interactive API reference (auto-generated OpenAPI)

Format Negotiation

All GET endpoints support multiple output formats. Three ways to choose:

URL suffix (highest priority): /ip/json, /all/yaml
Query parameter: ?format=json
Accept header: Accept: application/json

Supported formats: json, yaml, toml, csv, text (plain text).

CLI tools (curl, wget, httpie) receive plain text by default. Browsers get the HTML SPA.

# Plain text (default for curl)
curl https://ip.netray.info

# JSON via suffix
curl -s https://ip.netray.info/ip/json

# YAML via query param
curl -s 'https://ip.netray.info/ip?format=yaml'

# JSON via Accept header
curl -s -H 'Accept: application/json' https://ip.netray.info/ip

Core Endpoints

`GET /` or `GET /ip`

Your public IP address.

curl https://ip.netray.info

203.0.113.42

`GET /ip/cidr`

Your IP in CIDR notation.

curl https://ip.netray.info/ip/cidr

203.0.113.42/32

`GET /all`

Everything: IP, geo, ASN, rDNS, network classification, headers, user agent.

curl -s https://ip.netray.info/all/json | jq .

{
  "ip": "203.0.113.42",
  "hostname": "host-42.example.com",
  "city": "Frankfurt",
  "region": "Hesse",
  "country": "DE",
  "timezone": "Europe/Berlin",
  "latitude": 50.1109,
  "longitude": 8.6821,
  "asn": 64496,
  "isp": "Example Networks",
  "network": {
    "type": "residential",
    "cloud_provider": null,
    "is_vpn": false,
    "is_tor": false
  },
  ...
}

`GET /host`

Reverse DNS (PTR) hostname.

curl https://ip.netray.info/host

host-42.example.com

`GET /location`

Geolocation data.

curl -s https://ip.netray.info/location/json | jq .

{
  "city": "Frankfurt",
  "region": "Hesse",
  "country": "DE",
  "latitude": 50.1109,
  "longitude": 8.6821,
  "timezone": "Europe/Berlin"
}

`GET /isp`

ISP and ASN information.

curl -s https://ip.netray.info/isp/json | jq .

{
  "asn": 64496,
  "isp": "Example Networks",
  "organization": "Example Networks Ltd"
}

`GET /network`

Network classification: cloud provider, VPN, Tor, botnet, datacenter, residential.

curl -s https://ip.netray.info/network/json | jq .

{
  "type": "residential",
  "cloud_provider": null,
  "is_vpn": false,
  "is_tor": false,
  "is_datacenter": false,
  "threat_level": "none"
}

`GET /tcp`

TCP connection info (source port).

curl https://ip.netray.info/tcp

`GET /headers`

Your request headers as seen by the server.

curl -s https://ip.netray.info/headers/json | jq .

`GET /user_agent`

Parsed user agent string.

curl -s https://ip.netray.info/user_agent/json | jq .

Individual Field Endpoints

Each returns a single value as plain text:

curl https://ip.netray.info/country    # DE
curl https://ip.netray.info/city       # Frankfurt
curl https://ip.netray.info/region     # Hesse
curl https://ip.netray.info/asn        # 64496
curl https://ip.netray.info/timezone   # Europe/Berlin
curl https://ip.netray.info/latitude   # 50.1109
curl https://ip.netray.info/longitude  # 8.6821

Protocol-Specific Endpoints

`GET /ipv4`

Force resolution over IPv4.

curl https://ip.netray.info/ipv4

`GET /ipv6`

Force resolution over IPv6.

curl https://ip.netray.info/ipv6

Lookup Endpoints

`GET /asn/{number}`

Look up information about an ASN.

curl -s https://ip.netray.info/asn/64496/json | jq .

`GET /range?cidr=`

Classify a CIDR range.

curl -s 'https://ip.netray.info/range?cidr=203.0.113.0/24&format=json' | jq .

Query Parameters

Parameter	Description	Example
`ip`	Look up an arbitrary IP instead of the caller's	`?ip=203.0.113.1`
`fields`	Comma-separated list of fields to include	`?fields=ip,country,asn`
`format`	Output format: json, yaml, toml, csv, text	`?format=json`
`dns`	Set to `false` to skip PTR lookup (faster)	`?dns=false`
`lang`	BCP-47 locale for localized geo names	`?lang=de`

# Look up a specific IP, only country and ASN, in JSON
curl -s 'https://ip.netray.info/all/json?ip=203.0.113.1&fields=ip,country,asn' | jq .

Batch Lookup

`POST /batch`

Look up multiple IPs in a single request. Send a JSON array of IP addresses.

curl -s -X POST https://ip.netray.info/batch \
  -H 'Content-Type: application/json' \
  -d '["203.0.113.1", "198.51.100.2", "192.0.2.3"]' | jq .

The response is an array. Failed lookups include an error object with an index:

[
  {"ip": "203.0.113.1", "country": "DE", ...},
  {"error": {"code": "not_found", "message": "No data for IP"}, "index": 1},
  {"ip": "192.0.2.3", "country": "US", ...}
]

Note: batch requires batch.enabled=true in server configuration.

Side-by-Side Comparison

`POST /diff`

Compare two IPs side by side.

curl -s -X POST https://ip.netray.info/diff \
  -H 'Content-Type: application/json' \
  -d '{"a": "203.0.113.1", "b": "198.51.100.2"}' | jq .

Rate Limits

60 requests per minute per IP address, with a burst allowance of 10.

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining
`Retry-After`	Seconds to wait (only on 429)

# Check your remaining quota
curl -sI https://ip.netray.info/ip | grep -i x-ratelimit

Health Probes

`GET /health`

Liveness probe. Always returns 200 with {"status":"ok"}. Exempt from rate limiting.

curl https://ip.netray.info/health

`GET /ready`

Readiness probe. Returns 200 when GeoIP databases and UA parser are loaded, 503 otherwise. A 200 response may include a warnings array listing optional data sources that failed to load.

curl https://ip.netray.info/ready

Errors

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 12 seconds."
  }
}

IP Enrichment API

Format Negotiation

Core Endpoints

GET / or GET /ip

GET /ip/cidr

GET /all

GET /host

GET /location

GET /isp

GET /network

GET /tcp

GET /headers

GET /user_agent