Docs / API reference
API reference
One keyless HTTPS endpoint behind every page. Query any IP, select fields, choose your format. It never geo-blocks.
no key on freeHTTPSCORS + JSONPmd · json · txt
Quickstart
Make a request — no key, no signup. Returns JSON by default.
curlnodepython
copy# look up any IP — no key, no signup curl https://yourtrace.net/api/lookup?ip=8.8.8.8 # your own connection, as seen by our edge curl https://yourtrace.net/api/self # select fields + format (markdown for agents) curl "https://yourtrace.net/api/lookup?ip=1.1.1.1&fields=country,asn&format=md" # one field, as plaintext curl https://yourtrace.net/api/lookup?ip=1.1.1.1&fields=countryCode&format=txt
A successful call returns the full GeoResult record, with the sources we consulted listed inline:
{
"ip": "8.8.8.8",
"ipVersion": 4,
"kind": "public",
"countryCode": "US",
"countryName": "United States",
"region": "California",
"city": "Mountain View",
"latitude": 37.751,
"longitude": -97.822,
"accuracyRadiusKm": 1000,
"timezone": "America/Chicago",
"asn": "AS15169",
"asnOrg": "Google LLC",
"isp": "Google LLC",
"isHosting": true,
"isProxyOrVpn": false,
"label": "Google LLC · United States",
"confidence": "high",
"sources": ["rir-stats", "ipwho.is", "db-ip"],
"cached": false
}Base URL & authentication
https://yourtrace.net/api
The free tier is fully keyless. Paid plans authenticate with a bearer token for higher limits and billing:
-H "Authorization: Bearer yt_live_•••••••"
Endpoints
GET/api/lookupLook up any IP. ?ip= required.
GET/api/selfThe caller's own connection, as seen by our edge.
GET/api/lookup?ip={ip}&format=txt&fields={field}A single field as text/plain — perfect for shell scripts.
GET/ip/{ip}.mdHuman / agent page — also .json.
POST/api/batchUp to 1,000 IPs per call. Business.
GET/api/asn/{asn}Prefixes and metadata for an autonomous system. Pro.
Parameters
ParamTypeDescription
ipstringIPv4 or IPv6 to resolve. Required.
fieldscsvComma-separated subset, e.g. country,asn.
formatenumjson · md · txt. Overrides Accept.
callbackstringJSONP wrapper function name.
Formats
Content-negotiated by Accept — agents get Markdown, code gets JSON, browsers get HTML. The ?format= query parameter overrides the header.
application/jsonstructured record — default for API calls
text/markdownagent / LLM digest with the data table inline
text/plainone field, unquoted — ideal for ?fields= selection in scripts
text/htmlthe interactive page, for browsers
Rate limits
FreeDeveloperProBusiness
1k / day100k / mo1M / moCustom
Every response carries X-RateLimit-Remaining and X-RateLimit-Reset.
Errors
CodeMeaning
200OK — record returned (even for private/reserved IPs).
400Malformed IP or parameter.
429Rate limit exceeded — back off per Retry-After.
5xxUpstream source hiccup — retry idempotently.
We never geo-block. There is no 403for where you're calling from — every IP, from every country, gets the same answer.