> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/pt-br/headless-browser/geolocation-and-proxy-selection.md).

# 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

<table data-header-hidden><thead><tr><th width="90"></th><th></th></tr></thead><tbody><tr><td><code>p_cc</code></td><td>Código de país de 2 letras (ex.: <code>US</code>, <code>DE</code>, <code>FR</code>). Se nenhum país for especificado, ele é atribuído automaticamente com base na disponibilidade.</td></tr></tbody></table>

```
wss://USER:PASS@hb.oxylabs.io?p_cc=US
```

### Cidade

<table data-header-hidden><thead><tr><th width="90"></th><th></th></tr></thead><tbody><tr><td><code>p_city</code></td><td>Nome da cidade escrito em minúsculas (ex.: <code>berlin</code>, <code>los_angeles</code>). Também deve especificar um dos <code>p_cc</code> ou <code>p_state</code>.</td></tr></tbody></table>

```
wss://USER:PASS@hb.oxylabs.io?p_cc=US&p_city=new_york
```

{% hint style="info" %}
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.
{% endhint %}

### Estado (somente EUA)

<table data-header-hidden><thead><tr><th width="90"></th><th></th></tr></thead><tbody><tr><td><code>p_state</code></td><td>Nome do estado dos EUA em minúsculas (ex.: <code>texas</code>, <code>ohio</code>). Veja a lista completa de <a href="https://content.gitbook.com/content/BQ7Zf9paoN3FTeGcyfY1/blobs/cVjpiu1GKicluiVIT9og/us_states.txt">estados compatíveis</a>.</td></tr></tbody></table>

```
wss://USER:PASS@hb.oxylabs.io?p_state=texas&p_city=houston
```

{% hint style="info" %}
**Observação:** Se `p_state` e `p_cc` forem ambos especificados, `p_state` tem prioridade e `p_cc` é ignorado.
{% endhint %}

## 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.

<table><thead><tr><th width="181">Parâmetro</th><th width="479">Descrição</th><th width="83">Tipo</th></tr></thead><tbody><tr><td><code>proxy_resi_ses_id</code></td><td>Nome alfanumérico do rastreador de sessão com 3 a 36 caracteres.</td><td>cadeia de caracteres</td></tr><tr><td><code>proxy_resi_ses_time</code></td><td>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).</td><td>inteiro</td></tr></tbody></table>

```bash
# Exemplo: Fixar um IP com base nos EUA por 60 minutos
wss://USER:PASS@hb.oxylabs.io?p_cc=US&proxy_resi_ses_id=unique_job_id_101&proxy_resi_ses_time=60
```

{% hint style="warning" %}
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.
{% endhint %}

## 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.

{% tabs %}
{% tab title="Python (Playwright)" %}

```python
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()
```

{% endtab %}

{% tab title="JavaScript (Playwright)" %}

```javascript
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();
})();
```

{% endtab %}

{% tab title="JavaScript (Puppeteer)" %}

```javascript
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();
})();
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/pt-br/headless-browser/geolocation-and-proxy-selection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.