Look up an IP address from your backend

Resolve a supplied IP address to available country, region, city, and approximate coordinate data. Watch-IP's IP lookup API accepts IPv4 and IPv6 input and returns a JSON result backed by a third-party IP geolocation database. Use a secret API key on your server, and build your application around explicit matches, missing records, and nullable location fields.

View lookup plans Discuss lookup access →

Supply the address you want to resolve

Call GET /v1/lookup/{ip} with an IP address collected by your application, authenticated with Authorization: Bearer and a secret key. The lookup resolves the address in the URL rather than the connection used to make the request, which makes it suitable for backend workflows that already contain IP addresses, including reporting and regional enrichment. Verify how your application obtains an end user's IP before relying on forwarded headers; trust only the proxy path you control. For an ordinary website visitor integration, the browser geolocation endpoint offers a different path with a publishable key and regional enrichment.

Move from one address to a batch

If your workflow contains several IP addresses, the batch endpoint accepts up to 100 in a single request and returns results in the same order. It uses the same lookup result shape and the same server-side secret-key authentication model. Batching changes how you send the requests — lookup usage is still measured per IP, so one batch is not one unit of lookup usage.

Build around approximate data

An IP can represent a shared gateway, hosting network, VPN exit, or mobile carrier connection. Location records can be incomplete or differ between data providers. Use lookup as context for the address you supplied, not proof of a person's residence or identity.

Response fields

ip: The input address associated with this result.
found: Whether a matching database record was found. False can also mean the database is unavailable or has not loaded — it does not prove the address has no location data.
country, continent: Country and continent codes, when available.
region: Subdivision name, resolved from a GeoNames table keyed on country and regionCode — null when that pair isn't in GeoNames' table.
city, latitude, longitude: Approximate city and coordinates, when available in the source database.
postalCode: Resolved from a compiled GeoNames postal-code index keyed on country and coordinates, since the source database itself has no postal field. Null outside GeoNames' coverage.
timezone: Computed from latitude/longitude, since the source database has no timezone field of its own.

Make a server-side request

cURL — GET /v1/lookup/{ip}

curl --fail-with-body \
  'https://api.watch-ip.com/v1/lookup/8.8.8.8' \
  --header "Authorization: Bearer ${WATCH_IP_SECRET_KEY}"

Set WATCH_IP_SECRET_KEY in your server's environment first. 8.8.8.8 is a syntactically valid example address; this snippet does not promise a particular country, city, or response for it.

Frequently asked questions

Can I use this API to look up someone else's IP address?

The endpoint accepts a supplied IP address and returns available database location data, not a person's name, exact address, or identity. Use only data you are authorized to process.

Does it support IPv6?

The endpoint validates IPv4 and IPv6 input. A valid address can still lack a database record or some location fields.

Does lookup include timezone, ASN, or VPN detection?

No. The current lookup response does not include ASN or security indicators, and its third-party database source does not populate timezone or postal-code fields. Review visitor geolocation separately if its connecting-client model fits your application.

Can I send the request from browser JavaScript?

No — never expose a lookup secret in browser code. Make lookup calls from your backend, and use the visitor endpoint with a publishable key for direct browser geolocation.

Is this included with a free visitor key?

No. Lookup uses a separate secret key and plan family; the visitor free plan does not grant access to server-side lookup.

What does found: false mean?

The lookup did not return a matching record. In the current implementation this can also happen when the database is unavailable or has not loaded, so show "Location unavailable" and keep this outcome separate from invalid input, authentication failures, and rate-limit errors.