For authentication headers, API keys, and common error format see API General.
Proxy Counts
Public endpoints — no authentication required.
Get Proxy Counts
GET /geo/counts
Returns available proxy IP counts per country.
Structure: counts[proxyTypeId][pool][service][countryCode] = count.
Query Parameters
| Name | Type | Description | Required |
|---|---|---|---|
type | string | filter by proxy type (e.g. residential-giga) | No |
pool | string | filter by pool name (e.g. default) | No |
noservice | boolean | collapse service layer, return counts keyed directly by country | No |
Response
Default (with service layer):
{
"counts": {
"residential-giga": {
"default": {
"provider-api": {
"US": 1200000,
"GB": 350000
}
}
}
}
}With ?noservice=true:
{
"counts": {
"residential-giga": {
"default": { "US": 1200000, "GB": 350000 }
}
}
}Get Available Countries
GET /geo/countries
Returns country codes that have proxy availability for a given proxy type.
Query Parameters
| Name | Type | Description | Required |
|---|---|---|---|
type | string | proxy type ID | Yes |
pool | string | pool name (default: default) | No |
Response
{
"countries": ["AE", "AU", "BR", "DE", "GB", "US"]
}List IP Data Providers
GET /geo/providers
Lists all supported IP data providers with their load status. No authentication required.
Response
{
"providers": [
{
"id": "maxmind",
"name": "MaxMind GeoLite2",
"type": "mmdb",
"description": "ASN, city, region, country, lat/lng, timezone from MaxMind GeoLite2 databases.",
"ready": true
},
...
]
}IP Lookup
Lookup IP — All Providers 10 req / 30m
GET /geo/ip/:ip
Queries all enabled IP databases in parallel and returns a normalized merged result plus raw per-provider data. Authentication is optional — authenticated requests receive a higher rate limit.
Rate limits: unauthenticated — 10 requests / 30 min (keyed by client IP). Authenticated (JWT or API key) — 30 requests / 1 min. See API General for authentication options and API Keys for key management.
Bogon / private IPs: if the requested IP is a private, loopback, link-local, or otherwise reserved address, the API returns
{ "ip": "...", "bogon": true }immediately — no geo data is queried or returned.
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
ip | string | IPv4 or IPv6 address to look up | Yes |
Query Parameters
| Name | Type | Description | Required |
|---|---|---|---|
with_sources | boolean | include raw per-provider sources object in the response | No |
Response
{
"ip": "8.8.8.8",
"normalized": {
"countryCode": "US",
"country": "United States",
"continent": "North America",
"region": "California",
"city": "Mountain View",
"latitude": 37.386,
"longitude": -122.0838,
"timezone": "America/Los_Angeles",
"postalCode": "94043",
"asn": 15169,
"asnOrg": "GOOGLE",
"isp": "Google LLC",
"company": "Google LLC",
"asDomain": "google.com",
"prefix": "8.8.8.0/24",
"isProxy": false,
"proxyType": null,
"rir": "arin",
"rirSource": "delegation-stats"
},
"errors": {}
}Bogon / private IP response — when the IP is a reserved address (e.g. 192.168.1.1, 127.0.0.1, ::1):
{
"ip": "192.168.1.1",
"bogon": true
}With ?with_sources=1 the response includes a sources key with raw provider data:
{
"ip": "8.8.8.8",
"sources": {
"maxmind": {
"asn": { "autonomousSystemNumber": 15169, "autonomousSystemOrganization": "GOOGLE", "network": "8.8.8.0/24" },
"city": { "countryCode": "US", "region": "California", "city": "Mountain View", "latitude": 37.386, "longitude": -122.0838, "timezone": "America/Los_Angeles" },
"country": { "countryCode": "US", "inEu": false }
},
"ip2location": {
"db11": { "countryCode": "US", "region": "California", "city": "Mountain View", "latitude": 37.3861, "longitude": -122.0839 },
"asn": { "asn": "AS15169", "isp": "Google LLC" },
"proxy": { "isProxy": false, "proxyType": "-", "usageType": "DCH", "proxyScore": 0 }
},
"rir": { "rir": "arin", "countryCode": "US", "source": "delegation-stats" }
},
"normalized": { "...": "..." },
"errors": {}
}normalized field priority
| Field | Source priority |
|---|---|
countryCode | majority vote across all providers |
country | maxmind-city → ip2location-db11 → ipinfo → dbip → iplocate |
region, city, lat/lng, timezone, postalCode | maxmind-city → ip2location-db11 |
asn, asnOrg | maxmind-asn → iplocate-asn → ipinfo |
isp | ip2location-asn.isp → ip2location-proxy.isp → ipinfo.org |
company | ipinfo.asnOrg |
asDomain | ipinfo.asDomain |
prefix | iplocate-asn.prefix → maxmind-asn.network |
isProxy | ip2location-proxy.isProxy (always boolean, default false) |
proxyType | ip2location-proxy.proxyType lowercased, null when not a proxy |
rir, rirSource | rir provider |
errorsis a map ofproviderName → errorMessagefor any provider that failed during lookup.
Lookup IP — Single Provider Auth required
GET /geo/ip/:ip/:provider
Queries a single provider only. Requires JWT or API key. See API General for authentication.
Bogon / private IPs: same behaviour as the all-providers endpoint — returns
{ "ip": "...", "bogon": true }with no provider query performed.
Parameters
| Name | Type | Description | Required |
|---|---|---|---|
ip | string | IPv4 or IPv6 address to look up | Yes |
provider | string | provider ID — one of maxmind, ip2location, iplocate, dbip, ipinfo, rir | Yes |
Query Parameters
| Name | Type | Description | Required |
|---|---|---|---|
with_sources | boolean | include raw sources object in the response | No |
Response
{
"ip": "8.8.8.8",
"normalized": { "countryCode": "US", "...": "..." },
"errors": {}
}