Watch-IP

Visitor Geolocation API Reference

GET/v1/geo

Returns the connecting client's available location and enrichment data. Call it from a visitor's browser to describe that visitor's connection — a request from your application server describes the server's own connection instead.

Authentication

Provide an origin-locked publishable key via the X-Api-Key header, or the key query parameter as an alternative. Access control comes from the allowed-origins list configured for the key, checked against the request's Origin/Referer header — not from keeping the key secret, since it's designed to appear in browser source.

Response fields

ip
The connecting client's IP address.
country, region, regionCode, city, postalCode, continent
Approximate location, nullable when the underlying edge data doesn't resolve one.
latitude, longitude
Approximate coordinates for the resolved location, not a device or GPS position.
timezone
IANA timezone name, or null when unavailable.
isEUCountry
Boolean; a locational flag, not a legal determination.
asn, asOrganization
The connecting network and its operator, when supplied by the underlying data; otherwise null.
currency, callingCode
Regional context derived from the resolved country, or null.
locale, holidays, compliance, tax, ageVerification
Optional derived enrichment groups, each independently nullable. None of these are legal, tax, or identity determinations.
hostname
Only present when requested via ?include=hostname; a reverse-DNS lookup result, null if it fails.
security
Omitted entirely on plans that don't include it. When present: isTor, isVpn, isDatacenter, isThreat, isSanctionedNetwork — list-based indicators. IPv6 Tor detection is not currently implemented; false means no match in available data, not an absence of risk.

Errors

401
Missing or invalid API key.
403
The request's Origin/Referer is not on the key's allowed-origins list. No CORS header is set on this response, so the browser blocks it regardless of the JSON body.
429
The per-minute rate limit or the plan's monthly request cap has been exceeded — see errors and rate limits for how to tell which.

Example

Request

curl https://api.watch-ip.com/v1/geo \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY"

Response — illustrative; fields vary by plan and available data

{
  "ip": "203.0.113.1",
  "country": "US",
  "region": "Texas",
  "regionCode": "TX",
  "city": "Austin",
  "postalCode": "78701",
  "latitude": 30.2672,
  "longitude": -97.7431,
  "continent": "NA",
  "timezone": "America/Chicago",
  "isEUCountry": false,
  "asn": 12345,
  "asOrganization": "Example ISP",
  "currency": { "code": "USD", "name": "US Dollar", "symbol": "$" },
  "callingCode": "+1"
}

Limits

Subject to your plan's monthly request cap and per-minute rate limit — see pricing. Each successful call is recorded as one geo usage event.

Related pages