Quickstart

Before you start

• A Watch-IP account — the free plan is enough to follow this guide.
• A page or script you can add a fetch or curl call to.

1. Create an account and get a key

Sign up and open your dashboard. Every account starts with a publishable visitor key — configure its allowed origins to include the site you'll call it from (or localhost while testing).

2. Make your first request

Call GET /v1/geo with your publishable key in the X-Api-Key header. From a browser, this resolves the visitor's own connection; from a server, it resolves the server's own connection instead.

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

3. Read the response

A successful call returns 200 with a JSON body — country, city, and timezone are the fields most integrations start with, and every field is independently nullable, so check before you use one.

{
  "ip": "203.0.113.1",
  "country": "US",
  "city": "Austin",
  "timezone": "America/Chicago"
}

4. Look up a different IP

Need to resolve an address you already have, rather than the connecting visitor? That's a separate server-to-server endpoint authenticated with a secret key, not your publishable key — see the IP lookup reference.

If something goes wrong

A 401 means the API key is missing or invalid; a 403 from GET /v1/geo usually means the calling origin isn't on the key's allowed-origins list yet. See errors and rate limits for the full list of status codes.

Next step

Read authentication for how key types and origin-locking work, or go straight to the endpoint reference for the response you're integrating against.