Geo-Targeted Screenshots by Country

Some web pages render differently depending on where the request comes from. Pricing pages that show local currency, e-commerce stores that swap content for a specific region, or sites that block traffic from certain countries entirely. Capturing what those pages actually look like from a given location requires more than a regular screenshot call.

The Rendex geo parameter routes your capture through an IP in the country you specify. Pass a two-letter ISO 3166-1 alpha-2 country code and Rendex renders the page as a user in that country would see it. This is a Pro and Enterprise feature.

Prerequisites

A Rendex Pro or Enterprise API key. Geo-targeting is not available on Free or Starter. See the pricing page to upgrade.
An ISO 3166-1 alpha-2 country code for your target (e.g., US, DE, JP, BR).

Step 1: Send your first geo request

Add geo to any POST /v1/screenshot request. The value is a two-letter country code. The page will load through an IP registered to that country and return a PNG.

geo-screenshot.sh

curl -X POST https://api.rendex.dev/v1/screenshot \
  -H "Authorization: Bearer rdx_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -o screenshot.png \
  -d '{
    "url": "https://example.com/pricing",
    "geo": "DE",
    "width": 1280,
    "height": 800
  }'
# Get your API key at https://rendex.dev/login

The response is a raw PNG binary, the same as a normal screenshot call. The response header x-rendex-geo-country confirms which country code was used.

The JS and Python SDKs accept the same parameters:

geo-screenshot.ts

import { Rendex } from "@copperline/rendex"

const rendex = new Rendex("rdx_YOUR_KEY")

const result = await rendex.screenshot("https://example.com/pricing", {
  geo: "DE",
  width: 1280,
  height: 800,
})

// Write the PNG to disk
await Bun.write("screenshot.png", result.image)

geo_screenshot.py

from rendex import Rendex
from pathlib import Path

rendex = Rendex("rdx_YOUR_KEY")

result = rendex.screenshot(
    "https://example.com/pricing",
    geo="DE",
    width=1280,
    height=800,
)

Path("screenshot.png").write_bytes(result.image)
print(f"Captured from: {result.metadata.geo_country}")

The proof image below shows the full request on the left and the captured page on the right, rendered through a German IP with EUR pricing and the German locale active.

Geo-targeted screenshot API: a POST /v1/screenshot request with geo DE on the left, the captured pricing page showing EUR prices and German text on the right

Step 2: Target a city or region

Country-level geo targets the country generally. If you need a more precise location, add geoCity and optionally geoState:

geo-city.sh

curl -X POST https://api.rendex.dev/v1/screenshot \
  -H "Authorization: Bearer rdx_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -o screenshot.png \
  -d '{
    "url": "https://example.com/pricing",
    "geo": "US",
    "geoState": "California",
    "geoCity": "San Francisco",
    "width": 1280,
    "height": 800
  }'

geoCity requires geo to be set. geoState is optional but recommended when the city name is shared across multiple states. Both fields accept the English name of the location (e.g., Bavaria, not Bayern).

Supported countries

Geo-targeting maps ISO 3166-1 alpha-2 codes. Major markets across North America, Europe, Asia Pacific, Latin America, the Middle East, and Africa are supported. A few examples:

supported-codes.txt

Americas:  US, CA, MX, BR, AR, CO, CL, PE
Europe:    GB, DE, FR, IT, ES, NL, SE, CH, PL, PT, NO, DK
Asia Pac:  JP, CN, IN, AU, KR, SG, HK, TW, ID, PH, MY, TH, VN, NZ
Mid East:  AE, SA, IL, TR
Africa:    ZA, NG, EG, KE

If you pass a code that is not in the supported list, the API returns a VALIDATION_ERROR. Stick to ISO 3166-1 alpha-2 codes.

Step 3: Know the geo path's limits

Geo requests go through a proxy rather than Cloudflare Browser Rendering. That path is more constrained. The following parameters cannot be used alongside geo:

Input mode: html (HTML source input). Only URL mode works with geo.
Injections: css, js, cookies, headers, userAgent. The proxy handles rendering server-side.
Browser controls: selector, waitForSelector, hideSelectors, blockCookieBanners, device, darkMode, blockAds, fullPage.
Output format: only png is returned. PDF, JPEG, and WebP are not available on the geo path.
Content extraction: extract is not supported. Use the screenshot tool for standard captures instead.

If you include an incompatible parameter, the API returns GEO_FEATURE_UNAVAILABLE (HTTP 422) and lists the specific params that conflict. Remove them or remove geo to proceed.

422 GEO_FEATURE_UNAVAILABLE

{
  "success": false,
  "error": {
    "code": "GEO_FEATURE_UNAVAILABLE",
    "message": "These parameters are not supported with geo-targeting: fullPage, darkMode. Remove them or remove the geo parameter."
  }
}

Using geo with async mode

Geo captures can take longer than standard ones. For background workloads, combine geo with async: true and a webhookUrl to receive the PNG when it is ready rather than holding the connection open:

async-geo.sh

curl -X POST https://api.rendex.dev/v1/screenshot \
  -H "Authorization: Bearer rdx_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "geo": "JP",
    "async": true,
    "webhookUrl": "https://api.your-app.com/hooks/rendex"
  }'

The response is an HTTP 202 with a jobId. Rendex posts the completed PNG URL to your webhook when the render finishes. See the rendering vs screenshot API comparison for more on when async makes sense.

Troubleshooting

PLAN_UPGRADE_REQUIRED (403): Your key is on Free or Starter. Geo-targeting requires Pro or Enterprise. Upgrade your plan.

GEO_FEATURE_UNAVAILABLE (422): You included a parameter that is incompatible with geo. The error message lists the specific fields. Remove them and retry.

VALIDATION_ERROR (422) on the country code: The code you passed is not in the supported list. Check it against ISO 3166-1 alpha-2 (two uppercase letters). Codes like EUR or DEU are ISO 3166-1 alpha-3 and will not work.

Page content looks wrong:Some sites detect proxies and serve different content to them. Geo-targeting routes through a country's IP but cannot guarantee a site treats it the same as an end-user browser. Test the target URL directly from a VPN in the same country to confirm the site serves the expected content.

Next steps

Geo-targeting is one option on the same API reference endpoint that handles all Rendex captures. You can combine it with width, height, quality, and timeout settings.

If you need to capture dozens of countries for a monitoring or QA run, the screenshot tool lets you test individual requests before wiring them into code. For batch captures across many URLs, see the batch endpoint covered in the API reference.

Start a geo capture from your current plan at rendex.dev/login, or upgrade to Pro to access the feature.