Back to docs

Geo Proxy

Category: Infrastructure · Since: v18.39.0

CBrowser routes browser traffic through residential proxies in 12 regions worldwide. 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 Berlin Germany
france Paris France
japan Tokyo Japan
australia Sydney Australia
canada Toronto Canada
brazil Sao Paulo Brazil
india Mumbai India
singapore Singapore Singapore

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.

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)

Related

From the Blog