{"openapi":"3.1.0","info":{"title":"Bolrach Geo API","version":"1.0.0","description":"Self-hosted IP geolocation on Bolrach-owned data (ip-location-db CC0 country ranges + DB-IP Lite CC-BY city data). No third-party lookup service is involved: your traffic never leaves the Bolrach platform.","contact":{"url":"https://docs.bolrach.com/geo"}},"servers":[{"url":"https://api.bolrach.com"}],"security":[{"bearerKey":[]},{"headerKey":[]}],"paths":{"/v1/geo":{"get":{"operationId":"geoLookup","summary":"Locate one IP (or the caller)","description":"Looks up `?ip=`. When `ip` is omitted, the caller's own public address is located.","parameters":[{"name":"ip","in":"query","required":false,"schema":{"type":"string"},"description":"IPv4 or IPv6 address. Omit to locate yourself.","example":"8.8.8.8"}],"responses":{"200":{"description":"The location result.","content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"type":"string","description":"The address that was looked up.","examples":["8.8.8.8"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code.","examples":["US"]},"region":{"type":["string","null"],"description":"Subdivision / state name (IPv4 city data only).","examples":["California"]},"city":{"type":["string","null"],"description":"City name (IPv4 city data only).","examples":["Mountain View"]},"lat":{"type":["number","null"],"description":"Latitude of the city centroid.","examples":[37.422]},"lon":{"type":["number","null"],"description":"Longitude of the city centroid.","examples":[-122.085]},"attribution":{"type":"string","description":"License attribution for the underlying datasets. Keep it when you display results."}},"required":["ip","country","region","city","lat","lon","attribution"]}}}},"400":{"description":"Not a valid IP address (`invalid_ip`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `geo:read` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}},"/v1/geo/{ip}":{"get":{"operationId":"geoLookupPath","summary":"Locate one IP (path style)","description":"Identical to `GET /v1/geo?ip=` with the address in the path.","parameters":[{"name":"ip","in":"path","required":true,"schema":{"type":"string"},"description":"IPv4 or IPv6 address.","example":"2001:4860:4860::8888"}],"responses":{"200":{"description":"The location result.","content":{"application/json":{"schema":{"type":"object","properties":{"ip":{"type":"string","description":"The address that was looked up.","examples":["8.8.8.8"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code.","examples":["US"]},"region":{"type":["string","null"],"description":"Subdivision / state name (IPv4 city data only).","examples":["California"]},"city":{"type":["string","null"],"description":"City name (IPv4 city data only).","examples":["Mountain View"]},"lat":{"type":["number","null"],"description":"Latitude of the city centroid.","examples":[37.422]},"lon":{"type":["number","null"],"description":"Longitude of the city centroid.","examples":[-122.085]},"attribution":{"type":"string","description":"License attribution for the underlying datasets. Keep it when you display results."}},"required":["ip","country","region","city","lat","lon","attribution"]}}}},"400":{"description":"Not a valid IP address (`invalid_ip`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `geo:read` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}},"/v1/geo/batch":{"post":{"operationId":"geoBatch","summary":"Locate up to 100 IPs in one call","description":"Each address in `ips` is resolved; results come back in the same order. One batch call counts as one request against your rate limit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ips":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"1-100 IPv4/IPv6 addresses."}},"required":["ips"]},"example":{"ips":["8.8.8.8","1.1.1.1"]}}}},"responses":{"200":{"description":"All results, in request order.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"ip":{"type":"string","description":"The address that was looked up.","examples":["8.8.8.8"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code.","examples":["US"]},"region":{"type":["string","null"],"description":"Subdivision / state name (IPv4 city data only).","examples":["California"]},"city":{"type":["string","null"],"description":"City name (IPv4 city data only).","examples":["Mountain View"]},"lat":{"type":["number","null"],"description":"Latitude of the city centroid.","examples":[37.422]},"lon":{"type":["number","null"],"description":"Longitude of the city centroid.","examples":[-122.085]},"attribution":{"type":"string","description":"License attribution for the underlying datasets. Keep it when you display results."}},"required":["ip","country","region","city","lat","lon","attribution"]}}},"required":["count","results"]}}}},"400":{"description":"Bad body, invalid address, or more than 100 items.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `geo:read` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["rate_limited"]},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer bt_..."},"headerKey":{"type":"apiKey","in":"header","name":"x-api-key"}}}}