Geo API

Authentication

Pass your key on every request, either as Authorization: Bearer bt_... or as an x-api-key header. Keys are scoped; the Geo API needs geo:read. A missing key returns 401, a key without the scope returns 403.

curl "https://api.bolrach.com/v1/geo" \
  -H "Authorization: Bearer bt_your_key_here"

Calling /v1/geo with no ip parameter locates the caller, which doubles as the fastest way to test a fresh key.

Endpoints

curl "https://api.bolrach.com/v1/geo?ip=8.8.8.8" \
  -H "Authorization: Bearer bt_your_key_here"

{
  "ip": "8.8.8.8",
  "country": "US",
  "region": "California",
  "city": "Mountain View",
  "lat": 37.422,
  "lon": -122.085,
  "timezone": null,
  "asn": 15169,
  "network": "Google LLC",
  "network_type": "hosting",
  "tor": false,
  "source": "dbip",
  "attribution": "IP geolocation by DB-IP (https://db-ip.com), refined by Bolrach Geo"
}

curl "https://api.bolrach.com/v1/geo/2001:4860:4860::8888" \
  -H "Authorization: Bearer bt_your_key_here"

curl -X POST "https://api.bolrach.com/v1/geo/batch" \
  -H "Authorization: Bearer bt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"]}'

{
  "count": 2,
  "results": [
    { "ip": "8.8.8.8", "country": "US", "city": "Mountain View", "asn": 15169, "network": "Google LLC", "network_type": "hosting", "tor": false, "source": "dbip", ... },
    { "ip": "2620:101:c040::1", "country": "CA", "city": "Edmonton", "timezone": "America/Edmonton", "asn": 3359, "network": "University of Alberta", "network_type": null, "tor": false, "source": "observed", ... }
  ]
}

Result fields

Every field below works for IPv4 and IPv6. Private and unrouted ranges come back with every place and network field set to null.

Using the network signals

The place tells you where a request came from. The network fields tell you what kind of connection it used, and for sign-in checks that often matters more. A new sign-in from a hosting company is usually a script or a proxy rather than a person at home, and a Tor exit hides the real location on purpose.

The usual pattern is to ask for a second factor when one of these shows up, not to refuse the sign-in outright. People use VPNs and office proxies for ordinary reasons.

const res = await fetch(`https://api.bolrach.com/v1/geo?ip=${signInIp}`, {
  headers: { Authorization: `Bearer ${process.env.BOLRACH_API_KEY}` },
});
const geo = await res.json();

// Ask for a second factor instead of blocking: people use VPNs and office proxies for good reasons.
const stepUp =
  geo.tor ||
  geo.network_type === "hosting" ||
  (user.lastCountry && geo.country && geo.country !== user.lastCountry);

await sendSignInAlert(user, {
  where: [geo.city, geo.region, geo.country].filter(Boolean).join(", "),
  network: geo.network,
});

AUTHVIO's own new-device sign-in email is built from exactly these fields: the place, the country, the address, the network owner and a warning line for Tor, VPN and hosting networks.

How the place is chosen

Cloudflare places every visitor that reaches a Bolrach site. Bolrach Geo keeps what Cloudflare reported for each network block (a /24 for IPv4, a /48 for IPv6) for 90 days, learned every 10 minutes from real traffic, and answers from that when it has it. Those results carry source: "observed" and usually a timezone. Every other address is answered from DB-IP Lite with source: "dbip". Only the block and its place are kept, never the address of any single visitor.

Accuracy is city level. It is good enough to say "Lagos" or "Toronto", and mobile networks can place a phone in the carrier's hub city rather than where the person is standing. Never use it as a street address.

Rate limits and quotas

Limits apply per key. Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets); a 429 adds Retry-After.

Errors

Every error, on every service, uses one envelope:

{
  "error": {
    "code": "rate_limited",
    "message": "You hit the rate limit for your plan (free). Retry in 13s.",
    "status": 429
  }
}

Data and attribution

Lookups run entirely on Bolrach-hosted data. City and network-owner data come from DB-IP Lite (CC-BY 4.0), reloaded on the 4th of each month. The Tor exit list is reloaded daily. When Cloudflare's edge has placed a network block for real Bolrach traffic, that answer is kept for 90 days and wins over the database. Your queries never touch a third-party lookup service.

Changelog