GeoIP Database

Understand BotBrowser’s GeoIP lookup behavior, data boundaries, and performance characteristics.

Prerequisites

BotBrowser with --bot-profile.
Proxy routing configured (recommended).

Quick Start

Geo lookup is automatic when proxy routing is active:


chromium-browser \
  --bot-profile="path/to/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080

Use --proxy-ip if you already know the exit IP:


chromium-browser \
  --bot-profile="path/to/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --proxy-ip=203.0.113.1

For a single-family proxy, include ipv4_none or ipv6_none in the comma-separated value to declare the unavailable family and avoid an unnecessary lookup. See Proxy and Geolocation Alignment for the supported formats.

How It Works

BotBrowser uses a local GeoIP database to translate proxy exit IP into geographic defaults.

IP resolution

Source: proxy exit IP.
Input path: automatic IP service lookup or explicit --proxy-ip.

Local lookup

Lookup runs against bundled local GeoIP data.
No external geolocation API call is required for the mapping step.

Derived defaults

Timezone
Locale
Languages
Approximate coordinates

Override priority

Manual flags (--bot-timezone, --bot-locale, --bot-languages, --bot-location) override lookup-derived values.

For end-to-end usage strategy and practical configuration recipes, see Proxy and Geolocation.

Common Scenarios

Custom IP service list


--bot-ip-service="https://ip1.example.com,https://ip2.example.com"

Known exit IP from provider API


--proxy-ip=203.0.113.1

Strict manual geographic control


--proxy-ip=203.0.113.1 \
--bot-timezone=Asia/Tokyo \
--bot-locale=ja-JP \
--bot-languages=ja-JP,ja,en-US,en \
--bot-location=35.6762,139.6503

Accuracy boundary handling

If city-level mapping is not precise enough for your use case, keep GeoIP for baseline and set exact values via manual overrides.

Accuracy and Limits

Country-level mapping is generally strong.
City-level mapping can be approximate (nearby city/region).
Coordinate output is approximate and should not be treated as GPS-grade precision.

Performance Notes

Automatic IP resolution can add context activation latency.
--proxy-ip removes that external IP resolution roundtrip.
Lookup results are reused during session flow after initialization.

Troubleshooting / FAQ

Problem	Solution
Wrong timezone/locale after startup	Set explicit `--bot-timezone` / `--bot-locale`.
IP resolution fails	Provide `--proxy-ip` directly or replace IP services via `--bot-ip-service`.
City/coordinates look off	Expected for some IP ranges. Use `--bot-location` for exact coordinates.
Slow context activation	Use `--proxy-ip` to skip the initial IP-resolution request.

Next Steps

Proxy and Geolocation. User-facing configuration playbook.
Performance Optimization. Startup tuning.
CLI Flags Reference. Full list of geo and proxy flags.

Related documentation: Advanced Features | Playwright Guide

Legal Disclaimer & Terms of Use • Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.