> 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/cn/headless-browser/geolocation-and-proxy-selection.md).

# 地理位置与代理选择

了解如何使用位置参数从特定地点访问网页数据。

直接将地理位置和代理路由参数添加到 WebSocket 连接 URL，以便将自动化无头浏览器会话路由到目标地理区域，并控制代理 IP 的使用。

## 地理位置参数

你可以使用三个主要查询参数，通过国家、州或城市来定位特定地理位置。

### 国家

<table data-header-hidden><thead><tr><th width="90"></th><th></th></tr></thead><tbody><tr><td><code>p_cc</code></td><td>2 位国家代码（例如， <code>US</code>, <code>DE</code>, <code>FR</code>）。如果未指定国家，则会根据可用性自动分配。</td></tr></tbody></table>

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

### 城市

<table data-header-hidden><thead><tr><th width="90"></th><th></th></tr></thead><tbody><tr><td><code>p_city</code></td><td>以小写形式写出的城市名称（例如， <code>berlin</code>, <code>los_angeles</code>）。还必须同时指定以下之一： <code>p_cc</code> 或 <code>p_state</code>.</td></tr></tbody></table>

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

{% hint style="info" %}
城市级定位采用 *最佳努力优先策略*。如果住宅代理池中没有所请求精确位置的可用代理，它会自动回退到国家范围。
{% endhint %}

### 州（仅限美国）

<table data-header-hidden><thead><tr><th width="90"></th><th></th></tr></thead><tbody><tr><td><code>p_state</code></td><td>以小写形式写出的美国州名（例如， <code>texas</code>, <code>ohio</code>）。请查看完整的 <a href="https://content.gitbook.com/content/BQ7Zf9paoN3FTeGcyfY1/blobs/cVjpiu1GKicluiVIT9og/us_states.txt">支持的州列表</a>.</td></tr></tbody></table>

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

{% hint style="info" %}
**注意：** 如果 `p_state` 和 `p_cc` 同时指定了两者， `p_state` 则优先使用 `p_cc` 将被忽略。
{% endhint %}

## 代理选择（粘性代理）

默认情况下，代理网关会为每个唯一的浏览器连接会话分配一个新的出口 IP。或者，你可以通过包含以下 `proxy_resi_ses_id` 和 `proxy_resi_ses_time` 参数，在连续的浏览器连接尝试中固定某个特定的住宅出口 IP。

<table><thead><tr><th width="181">参数</th><th width="479">说明</th><th width="83">类型</th></tr></thead><tbody><tr><td><code>proxy_resi_ses_id</code></td><td>3 到 36 个字符的字母数字会话跟踪器名称。</td><td>字符串</td></tr><tr><td><code>proxy_resi_ses_time</code></td><td>保持固定住宅代理出口 IP 的分钟数。最小值为 1 分钟，最大值为 1440 分钟（24 小时）。</td><td>整数</td></tr></tbody></table>

```bash
# 示例：将一个美国 IP 固定 60 分钟
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" %}
要在连续连接中保持完全相同的出口 IP，你必须为以下两项传入相同的值： `proxy_resi_ses_id` 和 `proxy_resi_ses_time` 在之后的每个 URL 字符串中。
{% endhint %}

## 代码示例

以下示例展示了如何构建同时应用地理定位和粘性住宅代理 IP 约束的连接字符串。

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

```python
from playwright.sync_api import sync_playwright

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

# 定位纽约市并将住宅 IP 固定 30 分钟
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";

// 定位得克萨斯州并将住宅 IP 固定 60 分钟
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';
    
    // 定位得克萨斯州并将住宅 IP 固定 60 分钟
    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/cn/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.