Back to docs

Geo Proxy

Category: Infrastructure · Since: v18.39.0

CBrowser routes browser traffic through residential proxies in 10 built-in regions. Sites see a real residential IP from the target location instead of the server's IP.

Why This Matters

Many websites serve different content based on the visitor's IP location:

  • Language — German vs English product pages
  • Pricing — EUR vs USD, regional discounts
  • Content — region-locked features, local regulations
  • Compliance — GDPR consent banners, cookie walls
  • CDN routing — different edge servers, different performance

Without geo-routing, CBrowser's server IP determines what content the site serves — which may not match what your users see.

Available Regions

Region Code Location Country
us-west Los Angeles, CA United States
us-east New York City, NY United States
us-central Denver, CO United States
uk London United Kingdom
germany Frankfurt Germany
france Paris France
japan Tokyo Japan
australia Sydney Australia
canada Toronto Canada
brazil Sao Paulo Brazil

A geo-proxy.json can define more regions; they merge over these ten.

Usage

Simple: geoRegion parameter

Pass a region code to any supported tool:

site_cognitive_assessment url="https://example.com" geoRegion="uk" userLanguage="en-GB"

cognitive_effort url="https://example.de" persona="first-timer" geoRegion="germany" userLanguage="de-DE"

The tool automatically routes through a residential proxy in that region.

From the CLI

agent-ready-audit is the CLI command that routes through a region:

npx cbrowser agent-ready-audit \
  https://example.com \
  --geo-region uk

Since 20.0 a region that is not configured exits 1 instead of running from your own IP. cognitive-journey has no --geo-region (it exits 1); for the browser's reported location without a proxy, use --geo new-york or --geo 40.71,-74.00 on any command.

Advanced: Raw proxy URL

For custom proxies or providers other than IPRoyal:

site_cognitive_assessment url="https://example.com" proxy="http://user:[email protected]:8080"

Supports HTTP and SOCKS5 proxy protocols.

Supported Tools

Tool geoRegion proxy userLanguage userLocation
site_cognitive_assessment Yes Yes Yes Yes
cognitive_effort Yes Yes Yes Yes
empathy_audit — — Yes Yes
agent_ready_audit — — Yes —
cognitive_journey_init — — — Yes (via location param)

Three Layers of Geo-Accuracy

CBrowser applies three layers when geo parameters are set:

Layer 1: Accept-Language Header (Free)

Setting userLanguage="en-US" configures the browser's Accept-Language header. Most well-implemented sites check this header and serve content in the requested language.

Handles: Sites that follow HTTP content negotiation standards.

Layer 2: Browser Locale (Free)

The browser's navigator.language, Intl.DateTimeFormat, and related APIs are set to match the requested locale. This affects how JavaScript-rendered content (dates, numbers, currency) appears.

Handles: Single-page apps, JavaScript-heavy sites, sites that check navigator.language.

Layer 3: Residential Proxy (Requires proxy infrastructure)

The browser routes through a residential IP in the target region. The site's server sees a real home IP address from that location, not the CBrowser server's IP.

Handles: Sites that use IP-based geolocation (GeoIP databases, CDN-level routing, server-side redirects).

Language Mismatch Detection

When userLanguage is set, CBrowser checks the page's <html lang> attribute after loading. If the detected language doesn't match the expected language, a warning is included in the response:

{
  "languageWarning": {
    "expected": "en-US",
    "detected": "de",
    "message": "Page language \"de\" does not match expected \"en-US\". The site may be geo-detecting the server's IP rather than the user's locale."
  }
}

This helps identify sites where proxy routing (Layer 3) is needed because Accept-Language (Layer 1) isn't sufficient.

Configuration

Server-Side (for self-hosted CBrowser)

Create ~/.cbrowser/geo-proxy.json:

{
  "host": "geo.iproyal.com",
  "port": 12321,
  "username": "your_username",
  "basePassword": "your_password",
  "regions": {
    "us-west": { "country": "us", "city": "losangeles" },
    "uk": { "country": "gb", "city": "london" },
    "germany": { "country": "de", "city": "berlin" }
  }
}

Or set environment variables:

export IPROYAL_USERNAME="your_username"
export IPROYAL_PASSWORD="your_password"

Proxy Providers

CBrowser's geo-proxy system is designed for IPRoyal Residential Proxies but works with any HTTP/SOCKS5 proxy via the proxy parameter.

Requirements for residential proxies:

  • HTTP or SOCKS5 protocol
  • Username/password authentication
  • Country and city targeting (for geoRegion to work)
  • Sticky sessions (30-minute minimum recommended)

Performance Notes

  • Residential proxies add 5-15 seconds of latency per request
  • When geoRegion or proxy is set, navigation timeouts automatically increase from 30s to 60s
  • Agent-ready audit timeouts increase from 60s to 120s when proxied
  • First request through a new session may be slower (proxy handshake)

From the Blog