IP Geolocation API

Look up approximate location and network information for an IPv4 or IPv6 address. Send an HTTPS request and receive a JSON object. Fields without available data are null.

Make a request

GET https://whatsmyip.com/api/ip-lookup

Create a key in your account. Copy it when it is created: the full key is shown only once. Keep it on your server, not in public frontend code or a shared URL.

curl --get 'https://whatsmyip.com/api/ip-lookup' \
  --data-urlencode 'ip=8.8.8.8' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --max-time 15

Replace YOUR_API_KEY with your key. The optional ip query parameter accepts a single IPv4 or IPv6 address, not a domain or URL. If omitted, the lookup uses the request's public source IP—your server's address if your backend makes the request.

The legacy apikey query parameter is accepted, but the header is preferred because URLs can appear in logs and browser history. Revoking a key in your account prevents further use.

JavaScript on your server

const response = await fetch(
  'https://whatsmyip.com/api/ip-lookup?ip=8.8.8.8',
  { headers: { 'x-api-key': process.env.WHATSMYIP_API_KEY,
               'Accept': 'application/json' } }
);
const result = await response.json();
if (!response.ok) {
  throw new Error(`IP lookup failed: ${response.status}`);
}
console.log(result.ip, result.country_code);

Read the response

The response is a flat object, not a success/data wrapper. This illustrative response shows unavailable values; it is not a current location claim about the example address.

{
  "ip": "8.8.8.8",
  "city": null,
  "region": null,
  "country": null,
  "country_code": null,
  "isp": null,
  "latitude": null,
  "longitude": null,
  "timezone": null,
  "postal": null,
  "note": "Location data unavailable for this address. IP geolocation is approximate.",
  "network_note": "Network/ASN data is unavailable; location data is independent."
}

ip: The requested address, or the source address when no IP was supplied.
city, region, country, country_code: Approximate place names and a two-letter country code where available.
latitude, longitude: Numeric geographic estimates, not a person's address or device coordinates.
timezone, postal: Estimated time zone and postal code where available.
isp, asn: The legacy isp field identifies a network organization when ASN data is available; this is not necessarily the subscriber's retail ISP. asn is an optional numeric autonomous system number.
note, network_note: Explanations of accuracy or unavailable data. Treat these as informational text, not stable error codes.

Private or reserved addresses can return HTTP 200 with location fields set to null. They do not identify a public internet location. Additional fields may be added; clients should tolerate them.

Limits & errors

This endpoint allows up to 120 requests per minute per source IP. Requests from clients behind the same public IP share that limit. A rate limit is not a paid plan or a credit balance.

Status	Meaning	Next step
200	Lookup completed; some fields may be null.	Check available fields before displaying them.
401	Missing, invalid or revoked key. The JSON `error` is `invalid_api_key`.	Check the key and its environment.
422	The IP parameter is invalid.	Use one valid address. The JSON `errors.ip` array explains the validation error.
429	Request limit reached.	Wait for the `Retry-After` response header, then retry with backoff.
5xx	Temporary server failure.	Retry later with bounded backoff, not a tight loop.

The current endpoint does not return credits_remaining or deduct a lookup credit. This page does not offer a paid plan, unlimited usage or an availability guarantee.

Data & privacy

Location lookups use a local MaxMind GeoLite2 database. Coverage, age and accuracy vary; a VPN, mobile network or shared gateway can make the result differ from the user's physical location. Network data comes from a separate IPtoASN ASN database and can be unavailable independently of location data. Network organizations are not necessarily retail internet providers.

IPtoASN network data is released under PDDL 1.0. Additive fields network_source, network_source_url, network_license and network_updated identify the source and database publication date when a network match is available.

Responses are private and not intended for shared CDN caching. Avoid collecting IP lookups unnecessarily, and keep API keys out of analytics, URLs and public source code.

For an interactive lookup, use IP geolocation. To see the address making your browser request, open What is my IP address?