Introduction

Every lookup is one authenticated request and one clean JSON response. There is no session, no SDK required, and no state to manage. Point an SDK at your API key, or call the endpoint directly with curl - both hit the same resolver.

Get an API key#

Create a key in the dashboard. Each key is scoped to a monthly quota and rate limit that you control. Keep it server-side - it should never ship in a browser bundle or mobile app.

Your first request#

Authenticate with a single X-Api-Key header and pass the address in the path. This works for both IPv4 and IPv6.

curl https://resolver.ipgeotrace.com/v1/resolve/8.8.8.8 \
  -H "X-Api-Key: pk_geoip_your_key"

{
  "ip": "8.8.8.8",
  "ipVersion": 4,
  "country": { "code": "US", "name": "United States", "currency": "USD" },
  "region":  { "code": "CA", "name": "California" },
  "city":    { "name": "Mountain View", "postalCode": "94043" },
  "location":{ "latitude": 37.386, "longitude": -122.084, "timeZone": "America/Los_Angeles" },
  "asn":     { "number": 15169, "name": "Google LLC", "type": "hosting" },
  "isp":     { "name": "Google LLC" }
}

Authentication#

Send your key in the X-Api-Key header on every request. Requests without a valid key are rejected with 401. Rotate keys any time from the dashboard - old and new keys work together during a rollover.

Errors#

Errors are predictable and carry a clear message so you can branch on the status code.

• 400 - the supplied value is not a valid IP address.
• 401 - missing or invalid API key.
• 404 - the address is valid but has no geolocation data.
• 429 - rate limit or monthly quota exceeded. Honor the Retry-After header.

Rate limits & quota#

Every response includes rate-limit headers so you always know where you stand. Batch up to 100 addresses in one request on paid plans to stay well inside your limits.

Pick your SDK#

Prefer not to touch HTTP at all? Drop in an official SDK. .NET and JavaScript/TypeScript are available today, with more languages on the way.