Geolocalização e seleção de proxy

Descubra como usar os parâmetros de localização para acessar dados da web de locais específicos.

Use os parâmetros de geolocalização e roteamento de proxy diretamente na URL de conexão WebSocket para rotear suas sessões automatizadas do Headless Browser por regiões geográficas segmentadas e controlar o uso do IP do proxy.

Parâmetros de geolocalização

Você pode segmentar locais geográficos específicos por país, estado ou cidade usando três parâmetros de consulta principais.

País

p_cc	Código de país de 2 letras (ex.: US, DE, FR). Se nenhum país for especificado, ele é atribuído automaticamente com base na disponibilidade.

wss://USER:[e-mail]?p_cc=US

Cidade

p_city	Nome da cidade escrito em minúsculas (ex.: berlin, los_angeles). Também deve especificar um dos p_cc ou p_state.

wss://USER:[e-mail]?p_cc=US&p_city=new_york

O direcionamento em nível de cidade funciona como preferência de melhor esforço. Se o pool de proxies residenciais não tiver um proxy disponível na localização exata solicitada, ele faz fallback automaticamente para o escopo de país.

Estado (somente EUA)

p_state	Nome do estado dos EUA em minúsculas (ex.: texas, ohio). Veja a lista completa de estados compatíveis.

wss://USER:[e-mail]?p_state=texas&p_city=houston

Observação: Se p_state e p_cc forem ambos especificados, p_state tem prioridade e p_cc é ignorado.

Seleção de proxy (Proxies fixos)

Por padrão, o gateway de proxy atribui um novo IP de saída para cada sessão única de conexão do navegador. Como alternativa, você pode fixar um IP de saída residencial específico em tentativas contínuas de conexão do navegador incluindo os proxy_resi_ses_id e proxy_resi_ses_time parâmetros.

Parâmetro	Descrição	Tipo
proxy_resi_ses_id	Nome alfanumérico do rastreador de sessão com 3 a 36 caracteres.	cadeia de caracteres
proxy_resi_ses_time	Número de minutos para manter o IP de saída do proxy residencial fixado. Mín. – 1 minuto, máx. – 1440 minutos (24 horas).	inteiro

# Exemplo: Fixar um IP com base nos EUA por 60 minutos
wss://USER:[e-mail]?p_cc=US&proxy_resi_ses_id=unique_job_id_101&proxy_resi_ses_time=60

Para manter exatamente o mesmo IP de saída em conexões consecutivas, você deve passar valores idênticos para ambos proxy_resi_ses_id e proxy_resi_ses_time em cada string de URL subsequente.

Exemplos de código

Os exemplos a seguir mostram como construir strings de conexão que aplicam segmentação geográfica juntamente com restrições de IP de proxy residencial fixo.

Python (Playwright)

from playwright.sync_api import sync_playwright

username = "USERNAME_abc12"
password = "PASSWORD"
endpoint = "hb.oxylabs.io"

# Segmente a cidade de Nova York e fixe o IP residencial por 30 minutos
geolocation = "p_cc=US&p_city=new_york"
sticky_proxy = "proxy_resi_ses_id=scrape_session_404&proxy_resi_ses_time=30"
browser_url = f"wss://{username}:{password}@{endpoint}?{geolocation}&{sticky_proxy}"

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(browser_url)
    page = browser.new_page()
    page.goto("https://ip.oxylabs.io/location")
    print(page.title())
    browser.close()

JavaScript (Playwright)

import { chromium } from "playwright";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";

// Segmente o estado do Texas e fixe o IP residencial por 60 minutos
const geolocation = "p_state=texas&p_city=houston";
const sticky_proxy = "proxy_resi_ses_id=scrape_session_404&proxy_resi_ses_time=60";
const browserUrl = `wss://${username}:${password}@${endpoint}?${geolocation}&${sticky_proxy}`;

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const page = await browser.newPage();
    await page.goto("https://ip.oxylabs.io/location");
    console.log(await page.title());
    await browser.close();
})();

JavaScript (Puppeteer)

import puppeteer from 'puppeteer';

(async () => {
    const username = 'USERNAME';
    const password = 'PASSWORD';
    const endpoint = 'hb.oxylabs.io';
    
    // Segmente o estado do Texas e fixe o IP residencial por 60 minutos
    const geolocation = "p_state=texas&p_city=houston";
    const sticky_proxy = "proxy_resi_ses_id=scrape_session_404&proxy_resi_ses_time=60";
    const browserUrl = `wss://${username}:${password}@${endpoint}?${geolocation}&${sticky_proxy}`;

    const browser = await puppeteer.connect({
        browserWSEndpoint: browserUrl
    });
    const page = await browser.newPage();
    await page.goto('https://example.com');
    await browser.close();
})();