Watch-IP

IP Lookup API Reference

GET/v1/lookup/{ip}

Resolves a single IPv4 or IPv6 address you supply, using a third-party IP geolocation and ASN database — a different data source from GET /v1/geo, but the same derived fields (currency, compliance, locale, sun, holiday, age, tax, and more) computed from that source's country/region/coordinates. Server-to-server only; call it from your backend, never from a browser.

Authentication

Provide a secret key via Authorization: Bearer YOUR_SECRET_KEY. Unlike the publishable key used by GET /v1/geo, this key must stay on your server — using a publishable key here returns 403.

Response fields

ip
The IP address you supplied, echoed back.
country, city, continent
Approximate location from the source database, or null when unavailable.
region
Subdivision name, resolved from a GeoNames table keyed on country and regionCode — null when that pair isn't in GeoNames' table.
regionCode
Subdivision ISO code (e.g. "TX"), when the source database has an entry for it — otherwise null.
postalCode
Resolved from a compiled GeoNames postal-code index keyed on country+coordinates when the source database itself has no postal entry (which is always, for this data source). Null when GeoNames has no coverage for that area either — coverage is partial in several countries.
timezone
Computed from latitude/longitude (the source database has no timezone field of its own), or null when coordinates are unavailable.
latitude, longitude
Approximate coordinates, or null when unavailable.
isEUCountry, asn, asOrganization
isEUCountry comes from the source database's own data (or a static EU-27 table as a fallback); asn/asOrganization come from a separate ASN database.
currency, callingCode, compliance, locale, sun, holiday, age, tax
Same derivation as GET /v1/geo's identically-named fields, computed from this endpoint's country/regionCode/coordinates. locale's suggestedLocale is always just the country's own default here — there's no Accept-Language header to read on a server-to-server call.
userAgent
Null unless you pass ?userAgent=<value> (single-IP route only) — there's no browser request for this endpoint to read a User-Agent header from.
hostname
Reverse-DNS PTR hostname, only present when requested via ?include=hostname (single-IP route only).
security
Same VPN/Tor/threat classification as GET /v1/geo, present only on plans that include it.
found
False when the IP has no matching record or the underlying database is temporarily unavailable — the two cases aren't distinguished in this field.

Errors

400
The supplied IP is not a valid IPv4 or IPv6 address.
401
Missing or invalid API key.
403
A publishable key was used instead of a secret key.
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/lookup/203.0.113.1 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Response

{
  "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",
  "found": true
}

Limits

Billed per IP looked up, separate from your visitor-geo plan's request volume — see the IP lookup product page for pricing and availability. Need more than one IP per call? Use the batch endpoint instead. Location data for this endpoint is provided by DB-IP (IP Geolocation by DB-IP, db-ip.com — CC BY 4.0) and GeoNames (IP Geolocation data by GeoNames.org — CC BY 4.0).

Related pages