> 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/proxies/residential-proxies/location-settings.md).

# Location Settings

Learn more about location settings for Residential Proxies. Here you'll find guides for location targeting from continents to specific cities and coordinates.

Oxylabs Residential Proxies cover over 195 locations worldwide, allowing granular traffic routing down to **country**, **city**, **state**, **continent**, **ZIP code**, **ASN**, or **coordinate** levels. Location parameters are added directly into your proxy `username` string or passed via custom headers.

{% hint style="info" %}
**Location mapping:** We use the [**MaxMind GeoIP2**](https://www.maxmind.com/en/geoip2-databases) database to assign our exit nodes `cc`, `st`, and `city` values. This database is updated weekly.

Some other public IP databases may show different locations. In cases where there can not be any location mismatches, please double-check if the location of the assigned proxy is the same on the IP database used by the target website.
{% endhint %}

<table><thead><tr><th width="105">Targeting</th><th width="194">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><a href="#country"><strong>Country</strong></a></td><td><code>cc</code></td><td>ISO 3166-1 alpha-2 code. Supports country-specific entry ports.<br>E.g. <code>customer-USERNAME-cc-US</code></td></tr><tr><td><a href="#city"><strong>City</strong></a></td><td><code>city</code></td><td>English city name. Requires <code>cc</code> parameter for maximum accuracy.<br>E.g. <code>customer-USERNAME-cc-US-city-new_york</code></td></tr><tr><td><a href="#state"><strong>State</strong></a></td><td><code>st</code></td><td>US states only. Requires <code>us_</code> prefix.<br>E.g. <code>customer-USERNAME-st-us_california</code></td></tr><tr><td><a href="#continent"><strong>Continent</strong></a></td><td><code>cn</code></td><td>Two-letter continent code (<code>AF</code>, <code>AN</code>, <code>AS</code>, <code>EU</code>, <code>NA</code>, <code>OC</code>, <code>SA</code>).<br>E.g. <code>customer-USERNAME-cn-EU</code></td></tr><tr><td><a href="#zip-postal-code"><strong>ZIP / Postal code</strong></a></td><td><code>postalcode</code></td><td>5-digit US ZIP codes only. Requires <code>cc-US</code>.<br>E.g. <code>customer-USERNAME-cc-US-postalcode-90210</code></td></tr><tr><td><a href="#geo-hash"><strong>Geo hash</strong></a></td><td><code>geohash</code></td><td>Grid cell levels 1 to 4 (<code>9</code> to <code>drq4</code>). Mutually exclusive with other geo parameters.<br>E.g. <code>customer-USERNAME-geohash-u09</code></td></tr><tr><td><a href="#asn-targeting"><strong>ASN tageting</strong></a></td><td><code>ASN</code></td><td>Target specific Autonomous System Numbers. Overridden if <code>cc</code> is present.<br>E.g. <code>customer-USERNAME-ASN-21928</code></td></tr><tr><td><a href="#coordinates"><strong>Coordinates</strong></a></td><td><code>X-Oxylabs-Geolocation</code></td><td>Passed as an HTTP proxy header. Minimum 10-mile radius.<br>E.g. <code>Latitude:Longitude;Radius</code></td></tr></tbody></table>

{% hint style="warning" %}
**For requests from mainland China**, see dedicated HTTPS regional [China entry nodes](#china-entry-nodes).
{% endhint %}

***

## Country

Adding the `cc` parameter to the authorization header specifies the target country using a 2-letter ISO [**3166-1 alpha-2 format**](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code (e.g., `DE` for Germany, `GB` for the United Kingdom, `JP` for Japan):

```
customer-USERNAME-cc-DE:PASSWORD
```

#### Code examples

{% tabs %}
{% tab title="cURL" %}

```shell
curl -x pr.oxylabs.io:7777 -U "customer-USERNAME-cc-DE:PASSWORD" https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="Python" %}

```python
import urllib.request

username = 'USERNAME'
password = 'PASSWORD'
country = 'DE'
entry = f'http://customer-{username}-cc-{country}:{password}@pr.oxylabs.io:7777'

query = urllib.request.ProxyHandler({'http': entry, 'https': entry})
execute = urllib.request.build_opener(query)
print(execute.open('https://ip.oxylabs.io/location').read().decode('utf-8'))
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$username = 'USERNAME';
$password = 'PASSWORD';
$country = 'DE';
$proxy = 'pr.oxylabs.io:7777';
$query = curl_init('https://ip.oxylabs.io/location');
curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username-cc-$country:$password");
$output = curl_exec($query);
curl_close($query);
if ($output)
    echo $output;
?>
```

{% endtab %}

{% tab title="Java" %}

```java
package example;

import org.apache.http.HttpHost;
import org.apache.http.client.fluent.*;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpHost entry = new HttpHost("pr.oxylabs.io", 7777);
        String query = Executor.newInstance()
            .auth(entry, "customer-USERNAME-cc-DE", "PASS")
            .execute(Request.Get("http://ip.oxylabs.io/location").viaProxy(entry))
            .returnContent().asString();
        System.out.println(query);
    }
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("pr.oxylabs.io:7777");
        client.Proxy.Credentials = new NetworkCredential("customer-USERNAME-cc-DE", "PASSWORD");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io/location"));
    }
}
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'uri'
require 'net/http'

uri = URI.parse('https://ip.oxylabs.io/location')
proxy = Net::HTTP::Proxy('pr.oxylabs.io', 7777, 'customer-USERNAME-cc-DE', 'PASSWORD')

req = Net::HTTP::Get.new(uri.path)

result = proxy.start(uri.host,uri.port) do |http|
    http.request(req)
end

puts result.body
```

{% endtab %}
{% endtabs %}

### Country-specific entry nodes

Alternatively, connect directly to country-specific domain entry points without modifying your username parameters. The following example query to `ip.oxylabs.io/location` is performed from a random Turkish IP:

{% tabs %}
{% tab title="cURL" %}

```shell
curl -x tr-pr.oxylabs.io:30000 -U "customer-USERNAME:PASSWORD" https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$username = 'USERNAME';
$password = 'PASSWORD';
$proxy = 'tr-pr.oxylabs.io:30000';
$query = curl_init('https://ip.oxylabs.io/location');
curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username:$password");
$output = curl_exec($query);
curl_close($query);
if ($output)
    echo $output;
?>
```

{% endtab %}

{% tab title="Python" %}

```python
import urllib.request
import random
username = 'USERNAME'
password = 'PASSWORD'
entry = ('http://customer-%s:%s@tr-pr.oxylabs.io:30000' %
    (username, password))
query = urllib.request.ProxyHandler({
    'http': entry,
    'https': entry,
})
execute = urllib.request.build_opener(query)
print(execute.open('https://ip.oxylabs.io/location').read())
```

{% endtab %}

{% tab title="Java" %}

```java
package example;

import org.apache.http.HttpHost;
import org.apache.http.client.fluent.*;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpHost entry = new HttpHost("tr-pr.oxylabs.io", 30000);
        String query = Executor.newInstance()
            .auth(entry, "customer-USERNAME", "PASS")
            .execute(Request.Get("http://ip.oxylabs.io/location").viaProxy(entry))
            .returnContent().asString();
        System.out.println(query);
    }
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("tr-pr.oxylabs.io:30000");
        client.Proxy.Credentials = new NetworkCredential("customer-USERNAME", "PASSWORD");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io/location"));
    }
}
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
#!/usr/bin/ruby

require 'uri'
require 'net/http'

uri = URI.parse('https://ip.oxylabs.io/location')
proxy = Net::HTTP::Proxy('tr-pr.oxylabs.io', 30000, 'customer-USERNAME', 'PASSWORD')

req = Net::HTTP::Get.new(uri.path)

result = proxy.start(uri.host,uri.port) do |http|
    http.request(req)
end

puts result.body
```

{% endtab %}
{% endtabs %}

Please see the dashboard for entry point information. Download a complete list of random entry points or find them in the table below.

{% file src="/files/rnlVPJj2DQXXcKBdSUG9" %}

<details>

<summary><strong>Table of available entry nodes</strong></summary>

| <p><strong>Random</strong><br>pr.oxylabs.io:7777</p>             | <p><strong>USA</strong><br>us-pr.oxylabs.io:10000</p>                      | <p><strong>Canada</strong><br>ca-pr.oxylabs.io:30000</p>                         |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| <p><strong>Great Britain</strong><br>gb-pr.oxylabs.io:20000</p>  | <p><strong>Germany</strong><br>de-pr.oxylabs.io:30000</p>                  | <p><strong>France</strong><br>fr-pr.oxylabs.io:40000</p>                         |
| <p><strong>Spain</strong><br>es-pr.oxylabs.io:10000</p>          | <p><strong>Italy</strong><br>it-pr.oxylabs.io:20000</p>                    | <p><strong>Sweden</strong><br>se-pr.oxylabs.io:30000</p>                         |
| <p><strong>Greece</strong><br>gr-pr.oxylabs.io:40000</p>         | <p><strong>Portugal</strong><br>pt-pr.oxylabs.io:10000</p>                 | <p><strong>Netherlands</strong><br>nl-pr.oxylabs.io:20000</p>                    |
| <p><strong>Belgium</strong><br>be-pr.oxylabs.io:30000</p>        | <p><strong>Indonesia</strong><br>id-pr.oxylabs.io:10000</p>                | <p><strong>Ukraine (non-occupied regions)</strong><br>ua-pr.oxylabs.io:10000</p> |
| <p><strong>Poland</strong><br>pl-pr.oxylabs.io:20000</p>         | <p><strong>Israel</strong><br>il-pr.oxylabs.io:20000</p>                   | <p><strong>Turkey</strong><br>tr-pr.oxylabs.io:30000</p>                         |
| <p><strong>Australia</strong><br>au-pr.oxylabs.io:40000</p>      | <p><strong>Malaysia</strong><br>my-pr.oxylabs.io:10000</p>                 | <p><strong>Thailand</strong><br>th-pr.oxylabs.io:20000</p>                       |
| <p><strong>South Korea</strong><br>kr-pr.oxylabs.io:30000</p>    | <p><strong>Japan</strong><br>jp-pr.oxylabs.io:40000</p>                    | <p><strong>Philippines</strong><br>ph-pr.oxylabs.io:10000</p>                    |
| <p><strong>Singapore</strong><br>sg-pr.oxylabs.io:20000</p>      | <p><strong>China</strong><br>cn-pr.oxylabs.io:30000</p>                    | <p><strong>Hong Kong</strong><br>hk-pr.oxylabs.io:40000</p>                      |
| <p><strong>Taiwan</strong><br>tw-pr.oxylabs.io:10000</p>         | <p><strong>India</strong><br>in-pr.oxylabs.io:20000</p>                    | <p><strong>Pakistan</strong><br>pk-pr.oxylabs.io:30000</p>                       |
| <p><strong>Kazakhstan</strong><br>kz-pr.oxylabs.io:30000</p>     | <p><strong>UAE</strong><br>ae-pr.oxylabs.io:40000</p>                      | <p><strong>Mexico</strong><br>mx-pr.oxylabs.io:10000</p>                         |
| <p><strong>Brazil</strong><br>br-pr.oxylabs.io:20000</p>         | <p><strong>Argentina</strong><br>ar-pr.oxylabs.io:30000</p>                | <p><strong>Chile</strong><br>cl-pr.oxylabs.io:40000</p>                          |
| <p><strong>Peru</strong><br>pe-pr.oxylabs.io:10000</p>           | <p><strong>Ecuador</strong><br>ec-pr.oxylabs.io:20000</p>                  | <p><strong>Colombia</strong><br>co-pr.oxylabs.io:30000</p>                       |
| <p>​​<strong>South Africa</strong><br>za-pr.oxylabs.io:40000</p> | <p><strong>Egypt</strong><br>eg-pr.oxylabs.io:10000</p>                    | <p><strong>Angola</strong><br>ao-pr.oxylabs.io:40000</p>                         |
| <p><strong>Cameroon</strong><br>cm-pr.oxylabs.io:41000</p>       | <p><strong>Central African Republic</strong><br>cf-pr.oxylabs.io:42000</p> | <p><strong>Chad</strong><br>td-pr.oxylabs.io:43000</p>                           |
| <p><strong>Benin</strong><br>bj-pr.oxylabs.io:44000</p>          | <p><strong>Ethiopia</strong><br>et-pr.oxylabs.io:45000</p>                 | <p><strong>Djibouti</strong><br>dj-pr.oxylabs.io:46000</p>                       |
| <p><strong>Gambia</strong><br>gm-pr.oxylabs.io:47000</p>         | <p><strong>Ghana</strong><br>gh-pr.oxylabs.io:48000</p>                    | <p><strong>Côte d'Ivoire</strong><br>ci-pr.oxylabs.io:49000</p>                  |
| <p><strong>Kenya</strong><br>ke-pr.oxylabs.io:10000</p>          | <p><strong>Liberia</strong><br>lr-pr.oxylabs.io:11000</p>                  | <p><strong>Madagascar</strong><br>mg-pr.oxylabs.io:12000</p>                     |
| <p><strong>Mali</strong><br>ml-pr.oxylabs.io:13000</p>           | <p><strong>Mauritania</strong><br>mr-pr.oxylabs.io:14000</p>               | <p><strong>Mauritius</strong><br>mu-pr.oxylabs.io:15000</p>                      |
| <p><strong>Morocco</strong><br>ma-pr.oxylabs.io:16000</p>        | <p><strong>Mozambique</strong><br>mz-pr.oxylabs.io:17000</p>               | <p><strong>Nigeria</strong><br>ng-pr.oxylabs.io:18000</p>                        |
| <p><strong>Senegal</strong><br>sn-pr.oxylabs.io:19000</p>        | <p><strong>Seychelles</strong><br>sc-pr.oxylabs.io:20000</p>               | <p><strong>Zimbabwe</strong><br>zw-pr.oxylabs.io:21000</p>                       |
| <p><strong>South Sudan</strong><br>ss-pr.oxylabs.io:22000</p>    | <p><strong>Sudan</strong><br>sd-pr.oxylabs.io:23000</p>                    | <p><strong>Togo</strong><br>tg-pr.oxylabs.io:24000</p>                           |
| <p><strong>Tunisia</strong><br>tn-pr.oxylabs.io:25000</p>        | <p><strong>Uganda</strong><br>ug-pr.oxylabs.io:26000</p>                   | <p><strong>Zambia</strong><br>zm-pr.oxylabs.io:27000</p>                         |
| <p><strong>Afghanistan</strong><br>af-pr.oxylabs.io:28000</p>    | <p><strong>Bahrain</strong><br>bh-pr.oxylabs.io:29000</p>                  | <p><strong>Bangladesh</strong><br>bd-pr.oxylabs.io:30000</p>                     |
| <p><strong>Armenia</strong><br>am-pr.oxylabs.io:31000</p>        | <p><strong>Bhutan</strong><br>bt-pr.oxylabs.io:32000</p>                   | <p><strong>Myanmar</strong><br>mm\_pr.oxylabs.io:33000</p>                       |
| <p><strong>Cambodia</strong><br>kh-pr.oxylabs.io:34000</p>       | <p><strong>Georgia</strong><br>ge-pr.oxylabs.io:36000</p>                  | <p><strong>Iraq</strong><br>iq-pr.oxylabs.io:37000</p>                           |
| <p><strong>Jordan</strong><br>jo-pr.oxylabs.io:38000</p>         | <p><strong>Lebanon</strong><br>lb-pr.oxylabs.io:39000</p>                  | <p><strong>Maldives</strong><br>mv-pr.oxylabs.io:40000</p>                       |
| <p><strong>Mongolia</strong><br>mn-pr.oxylabs.io:41000</p>       | <p><strong>Oman</strong><br>om-pr.oxylabs.io:42000</p>                     | <p><strong>Qatar</strong></p><p>qa-pr.oxylabs.io:43000</p>                       |
| <p><strong>Saudi Arabia</strong><br>sa-pr.oxylabs.io:44000</p>   | <p><strong>Vietnam</strong><br>vn-pr.oxylabs.io:45000</p>                  | <p><strong>Turkmenistan</strong><br>tm-pr.oxylabs.io:46000</p>                   |
| <p><strong>Uzbekistan</strong><br>uz-pr.oxylabs.io:47000</p>     | <p><strong>Yemen</strong><br>ye-pr.oxylabs.io:48000</p>                    | <p><strong>Albania</strong></p><p>al-pr.oxylabs.io:49000</p>                     |
| <p><strong>Andorra</strong><br>ad-pr.oxylabs.io:10000</p>        | <p><strong>Austria</strong><br>at-pr.oxylabs.io:11000</p>                  | <p><strong>Bosnia and Herzegovina</strong><br>ba-pr.oxylabs.io:13000</p>         |
| <p><strong>Bulgaria</strong><br>bg-pr.oxylabs.io:14000</p>       | <p><strong>Azerbaijan</strong><br>az-pr.oxylabs.io:20000</p>               | <p><strong>Croatia</strong><br>hr-pr.oxylabs.io:16000</p>                        |
| <p><strong>Cyprus</strong><br>cy-pr.oxylabs.io:35000</p>         | <p><strong>Czech Republic</strong></p><p>cz-pr.oxylabs.io:18000</p>        | <p><strong>Denmark</strong><br>dk-pr.oxylabs.io:19000</p>                        |
| <p><strong>Estonia</strong><br>ee-pr.oxylabs.io:20000</p>        | <p><strong>Finland</strong><br>fi-pr.oxylabs.io:21000</p>                  | <p><strong>Hungary</strong><br>hu-pr.oxylabs.io:23000</p>                        |
| <p><strong>Iceland</strong><br>is-pr.oxylabs.io:24000</p>        | <p><strong>Ireland</strong><br>ie-pr.oxylabs.io:25000</p>                  | <p><strong>Latvia</strong><br>lv-pr.oxylabs.io:26000</p>                         |
| <p><strong>Liechtenstein</strong><br>li-pr.oxylabs.io:27000</p>  | <p><strong>Lithuania</strong><br>lt-pr.oxylabs.io:28000</p>                | <p><strong>Luxembourg</strong><br>lu-pr.oxylabs.io:29000</p>                     |
| <p><strong>Malta</strong><br>mt-pr.oxylabs.io:30000</p>          | <p><strong>Monaco</strong><br>mc-pr.oxylabs.io:31000</p>                   | <p><strong>Moldova</strong><br>md-pr.oxylabs.io:32000</p>                        |
| <p><strong>Montenegro</strong><br>me-pr.oxylabs.io:33000</p>     | <p><strong>Norway</strong><br>no-pr.oxylabs.io:34000</p>                   | <p><strong>Romania</strong><br>ro-pr.oxylabs.io:35000</p>                        |
| <p><strong>Serbia</strong><br>rs-pr.oxylabs.io:36000</p>         | <p><strong>Slovakia</strong><br>sk-pr.oxylabs.io:37000</p>                 | <p><strong>Slovenia</strong><br>si-pr.oxylabs.io:38000</p>                       |
| <p><strong>Switzerland</strong><br>ch-pr.oxylabs.io:39000</p>    | <p><strong>Macedonia</strong></p><p>mk-pr.oxylabs.io:40000</p>             | <p><strong>Bahamas</strong><br>bs-pr.oxylabs.io:41000</p>                        |
| <p><strong>Belize</strong><br>bz-pr.oxylabs.io:42000</p>         | <p><strong>British Virgin Islands</strong><br>vg-pr.oxylabs.io:43000</p>   | <p><strong>Costa Rica</strong><br>cr-pr.oxylabs.io:44000</p>                     |
| <p><strong>Namibia</strong><br>na-pr.oxylabs.io:28000</p>        | <p><strong>Dominica</strong><br>dm-pr.oxylabs.io:46000</p>                 | <p><strong>Haiti</strong><br>ht-pr.oxylabs.io:47000</p>                          |
| <p><strong>Honduras</strong><br>hn-pr.oxylabs.io:48000</p>       | <p><strong>Jamaica</strong><br>jm-pr.oxylabs.io:49000</p>                  | <p><strong>Aruba</strong><br>aw-pr.oxylabs.io:10000</p>                          |
| <p><strong>Panama</strong><br>pa-pr.oxylabs.io:11000</p>         | <p><strong>Puerto Rico</strong><br>pr-pr.oxylabs.io:12000</p>              | <p><strong>Trinidad and Tobago</strong><br>tt-pr.oxylabs.io:13000</p>            |
| <p><strong>Fiji</strong><br>fj-pr.oxylabs.io:14000</p>           | <p><strong>New Zealand</strong><br>nz-pr.oxylabs.io:15000</p>              | <p><strong>Bolivia</strong><br>bo-pr.oxylabs.io:16000</p>                        |
| <p><strong>Paraguay</strong><br>py-pr.oxylabs.io:17000</p>       | <p><strong>Uruguay</strong><br>uy-pr.oxylabs.io:18000</p>                  | <p><strong>Venezuela</strong><br>ve-pr.oxylabs.io:19000</p>                      |
| <p><strong>European Union</strong><br>eu-pr.oxylabs.io:10000</p> | <p><strong>Dominican Republic</strong></p><p>do-pr.oxylabs.io:21000</p>    | <p><strong>Laos</strong></p><p>la-pr.oxylabs.io:22000</p>                        |
| <p><strong>Tanzania</strong></p><p>tz-pr.oxylabs.io:23000</p>    | <p><strong>Sri Lanka</strong></p><p>lk-pr.oxylabs.io:24000</p>             | <p><strong>Brunei</strong></p><p>bn-pr.oxylabs.io:25000</p>                      |
| <p><strong>Nepal</strong></p><p>np-pr.oxylabs.io:26000</p>       | <p><strong>Kuwait</strong></p><p>kw-pr.oxylabs.io:20000</p>                | <p><strong>Guatemala</strong></p><p>gt-pr.oxylabs.io:27000</p>                   |
| <p><strong>Algeria</strong><br>dz-pr.oxylabs.io:29000</p>        |                                                                            |                                                                                  |

</details>

***

## City

Target proxies in specific cities by combining the `city` parameter with a matching country code (`cc`). Multi-word city names use underscores instead of spaces (e.g., `new_york`, `rio_de_janeiro`).

```
customer-USERNAME-cc-US-city-los_angeles:PASSWORD
```

#### Code examples

{% tabs %}
{% tab title="cURL" %}

```shell
curl -x pr.oxylabs.io:7777 -U "customer-USERNAME-cc-DE-city-munich:PASSWORD" https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="Python" %}

```python
import urllib.request
import random
username = 'USERNAME'
password = 'PASSWORD'
country = 'DE'
city = 'munich'
entry = ('http://customer-%s-cc-%s-city-%s:%s@pr.oxylabs.io:7777' %
    (username, country, city, password))
query = urllib.request.ProxyHandler({
    'http': entry,
    'https': entry,
})
execute = urllib.request.build_opener(query)
print(execute.open('https://ip.oxylabs.io/location').read())
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$username = 'USERNAME';
$password = 'PASSWORD';
$country = 'DE';
$city = 'munich';
$proxy = 'pr.oxylabs.io:7777';
$query = curl_init('https://ip.oxylabs.io/location');
curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username-cc-$country-city-$city:$password");
$output = curl_exec($query);
curl_close($query);
if ($output)
    echo $output;
?>
```

{% endtab %}

{% tab title="Java" %}

```java
package example;

import org.apache.http.HttpHost;
import org.apache.http.client.fluent.*;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpHost entry = new HttpHost("pr.oxylabs.io", 7777);
        String query = Executor.newInstance()
            .auth(entry, "customer-USERNAME-cc-DE-city-munich", "PASS")
            .execute(Request.Get("http://ip.oxylabs.io/location").viaProxy(entry))
            .returnContent().asString();
        System.out.println(query);
    }
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("pr.oxylabs.io:7777");
        client.Proxy.Credentials = new NetworkCredential("customer-USERNAME-cc-DE-city-munich", "PASSWORD");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io/location"));
    }
}
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'uri'
require 'net/http'

uri = URI.parse('https://ip.oxylabs.io/location')
proxy = Net::HTTP::Proxy('pr.oxylabs.io', 7777, 'customer-USERNAME-cc-DE-city-munich', 'PASSWORD')

req = Net::HTTP::Get.new(uri.path)

result = proxy.start(uri.host,uri.port) do |http|
    http.request(req)
end

puts result.body
```

{% endtab %}
{% endtabs %}

Download the list of supported cities by clicking the file below:

{% file src="/files/628qdEipraPVtaUrEWuA" %}

{% hint style="info" %}
We support every city in the world, yet due to the dynamic nature of Residential Proxies we do not guarantee we will have proxies there at specific moment in time. Most popular cities are well covered.
{% endhint %}

***

## State

Select proxies from specific US states using the `st` parameter. State names must include the `us_` prefix (e.g., `us_california`, `us_illinois`).

```
customer-USERNAME-st-us_california:PASSWORD
```

#### Code Examples

In this example, a query to `ip.oxylabs.io/location` is performed from a random IP address from California, USA:

{% tabs %}
{% tab title="cURL" %}

```shell
curl -x pr.oxylabs.io:7777 -U "customer-USERNAME-st-us_california:PASSWORD" https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$username = 'USERNAME';
$password = 'PASSWORD';
$state = 'us_california';
$proxy = 'pr.oxylabs.io:7777';
$query = curl_init('https://ip.oxylabs.io/location');
curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username-st-$state:$password");
$output = curl_exec($query);
curl_close($query);
if ($output)
    echo $output;
?>
```

{% endtab %}

{% tab title="Python" %}

```python
import urllib.request
import random
username = 'USERNAME'
password = 'PASSWORD'
state = 'us_california'
entry = ('http://customer-%s-st-%s:%s@pr.oxylabs.io:7777' %
    (username, state, password))
query = urllib.request.ProxyHandler({
    'http': entry,
    'https': entry,
})
execute = urllib.request.build_opener(query)
print(execute.open('https://ip.oxylabs.io/location').read())
```

{% endtab %}

{% tab title="Java" %}

```java
package example;

import org.apache.http.HttpHost;
import org.apache.http.client.fluent.*;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpHost entry = new HttpHost("pr.oxylabs.io", 7777);
        String query = Executor.newInstance()
            .auth(entry, "customer-USERNAME-st-us_california", "PASS")
            .execute(Request.Get("http://ip.oxylabs.io/location").viaProxy(entry))
            .returnContent().asString();
        System.out.println(query);
    }
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("pr.oxylabs.io:7777");
        client.Proxy.Credentials = new NetworkCredential("customer-USERNAME-st-us_california", "PASSWORD");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io/location"));
    }
}
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'uri'
require 'net/http'

uri = URI.parse('https://ip.oxylabs.io/location')
proxy = Net::HTTP::Proxy('pr.oxylabs.io', 7777, 'customer-USERNAME-st-us_california', 'PASSWORD')

req = Net::HTTP::Get.new(uri.path)

result = proxy.start(uri.host,uri.port) do |http|
    http.request(req)
end

```

{% endtab %}
{% endtabs %}

See the full supported state list below:

{% file src="/files/EvsJRuHoN38IvMVSY0x2" %}

***

## Continent

Route requests through any of the seven continents using the `cn` parameter followed by a two-letter continent code:

`cn-AF` – Africa\
`cn-AN` – Antarctica\
`cn-AS` – Asia\
`cn-EU` – Europe\
`cn-NA` – North America\
`cn-OC` – Oceania\
`cn-SA` – South America

```
customer-USERNAME-cn-EU:PASSWORD
```

#### Code example

{% tabs %}
{% tab title="cURL" %}

```shell
curl -x pr.oxylabs.io:7777 -U "customer-USERNAME-cn-AS:PASSWORD" https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$username = 'USERNAME';
$password = 'PASSWORD';
$continent = 'AS';
$proxy = 'pr.oxylabs.io:7777';
$query = curl_init('https://ip.oxylabs.io/location');
curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username-cn-$continent:$password");
$output = curl_exec($query);
curl_close($query);
if ($output)
    echo $output;
?>
```

{% endtab %}

{% tab title="Python" %}

```python
import urllib.request
import random
username = 'USERNAME'
password = 'PASSWORD'
continent = 'AS'
entry = ('http://customer-%s-cn-%s:%s@pr.oxylabs.io:7777' %
    (username, continent, password))
query = urllib.request.ProxyHandler({
    'http': entry,
    'https': entry,
})
execute = urllib.request.build_opener(query)
print(execute.open('https://ip.oxylabs.io/location').read())
```

{% endtab %}

{% tab title="Java" %}

```java
package example;

import org.apache.http.HttpHost;
import org.apache.http.client.fluent.*;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpHost entry = new HttpHost("pr.oxylabs.io", 7777);
        String query = Executor.newInstance()
            .auth(entry, "customer-USERNAME-cn-AS", "PASS")
            .execute(Request.Get("http://ip.oxylabs.io/location").viaProxy(entry))
            .returnContent().asString();
        System.out.println(query);
    }
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("pr.oxylabs.io:7777");
        client.Proxy.Credentials = new NetworkCredential("customer-USERNAME-cn-AS", "PASSWORD");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io/location"));
    }
}
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'uri'
require 'net/http'

uri = URI.parse('https://ip.oxylabs.io/location')
proxy = Net::HTTP::Proxy('pr.oxylabs.io', 7777, 'customer-USERNAME-cn-AS', 'PASSWORD')

req = Net::HTTP::Get.new(uri.path)

result = proxy.start(uri.host,uri.port) do |http|
    http.request(req)
end

puts result.body
```

{% endtab %}
{% endtabs %}

***

## ZIP / Postal code

Target specific US 5-digit ZIP codes using the `postalcode` parameter. The parameter must be used with the country code parameter `cc` and a case-insensitive country code in 2-letter [**3166-1 alpha-2 format**](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

{% hint style="info" %}
Currently we support **only US-based codes** for ZIP code targeting, the parameter **must be accompanied by** `cc-US`.
{% endhint %}

```
customer-USERNAME-cc-US-postalcode-90210:PASSWORD
```

#### Code examples

{% tabs %}
{% tab title="cURL" %}

```shell
curl -x pr.oxylabs.io:7777 -U "customer-USERNAME-cc-US-postalcode-90210:PASSWORD" https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$username = 'USERNAME';
$password = 'PASSWORD';
$country = 'US';
$postalcode = '90210';
$proxy = 'pr.oxylabs.io:7777';
$query = curl_init('https://ip.oxylabs.io/location');
curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username-cc-$country-postalcode-$postalcode:$password");
$output = curl_exec($query);
curl_close($query);
if ($output)
    echo $output;
?>
```

{% endtab %}

{% tab title="Python" %}

```python
import urllib.request
import random
username = 'USERNAME'
password = 'PASSWORD'
country = 'US'
postalcode = '90210'
entry = ('http://customer-%s-cc-%s-postalcode-%s:%s@pr.oxylabs.io:7777' %
    (username, country, postalcode, password))
query = urllib.request.ProxyHandler({
    'http': entry,
    'https': entry,
})
execute = urllib.request.build_opener(query)
print(execute.open('https://ip.oxylabs.io/location').read())
```

{% endtab %}

{% tab title="Java" %}

```java
package example;

import org.apache.http.HttpHost;
import org.apache.http.client.fluent.*;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpHost entry = new HttpHost("pr.oxylabs.io", 7777);
        String query = Executor.newInstance()
            .auth(entry, "customer-USERNAME-cc-US-postalcode-90210", "PASS")
            .execute(Request.Get("https://ip.oxylabs.io/location").viaProxy(entry))
            .returnContent().asString();
        System.out.println(query);
    }
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("pr.oxylabs.io:7777");
        client.Proxy.Credentials = new NetworkCredential("customer-USERNAME-cc-US-postalcode-90210", "PASSWORD");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io/location"));
    }
}
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'uri'
require 'net/http'

uri = URI.parse('https://ip.oxylabs.io/location')
proxy = Net::HTTP::Proxy('pr.oxylabs.io', 7777, 'customer-USERNAME-cc-US-postalcode-90210', 'PASSWORD')

req = Net::HTTP::Get.new(uri.path)

result = proxy.start(uri.host,uri.port) do |http|
    http.request(req)
end

puts result.body
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Proxy location using ZIP code is being matched using [**MaxMind IP Geolocation**](https://www.maxmind.com/en/geoip-demo) database. There can be a mismatch between ZIP codes when checking IP addresses against other IP geo-location databases.
{% endhint %}

***

## Geo hash

Target proxies within specific geographic grid cells using Geo hash codes ranging from Level 1 (largest) to Level 4 (smallest). Geo hash allows precise grid-based targeting without relying on traditional administrative boundaries like country or city borders.

By default, Geo hash uses strict targeting: if no IP is available in the requested cell, the request returns a `502 Bad Gateway` error.

```
customer-USERNAME-geohash-u09:PASSWORD
```

<table><thead><tr><th width="79">Length</th><th width="205.69921875">Approx. cell size</th><th>Examples</th></tr></thead><tbody><tr><td>1</td><td>≤ 5,000 km × 5,000 km</td><td><code>geohash-9</code> (Large part of US &#x26; Mexico), <code>geohash-c</code> (Northern US &#x26; Canada)</td></tr><tr><td>2</td><td>≤ 1,250 km × 625 km</td><td><code>geohash-gc</code> (Ireland, Northern Ireland, England and Scotland)</td></tr><tr><td>3</td><td>≤ 156 km × 156 km</td><td><code>geohash-u09</code> (Paris)</td></tr><tr><td>4</td><td>≤ 39.1 km × 19.5 km</td><td><code>geohash-drq4</code> (Most of Nantucket Island)</td></tr></tbody></table>

#### Code examples

{% tabs %}
{% tab title="cURL" %}

```shell
curl -x pr.oxylabs.io:7777 -U "customer-USERNAME-geohash-u09:PASSWORD" https://ip.oxylabs.io/location
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$username = 'USERNAME';
$password = 'PASSWORD';
$geohash = 'u09';
$proxy = 'pr.oxylabs.io:7777';
$query = curl_init('https://ip.oxylabs.io/location');
curl_setopt($query, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($query, CURLOPT_PROXY, "http://$proxy");
curl_setopt($query, CURLOPT_PROXYUSERPWD, "customer-$username-geohash-$geohash:$password");
$output = curl_exec($query);
curl_close($query);
if ($output)
    echo $output;
?>
```

{% endtab %}

{% tab title="Python" %}

```python
import urllib.request
import random
username = 'USERNAME'
password = 'PASSWORD'
geohash = 'u09'
entry = ('http://customer-%s-geohash-%s:%s@pr.oxylabs.io:7777' %
    (username, geohash, password))
query = urllib.request.ProxyHandler({
    'http': entry,
    'https': entry,
})
execute = urllib.request.build_opener(query)
print(execute.open('https://ip.oxylabs.io/location').read())
```

{% endtab %}

{% tab title="Java" %}

```java
package example;

import org.apache.http.HttpHost;
import org.apache.http.client.fluent.*;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpHost entry = new HttpHost("pr.oxylabs.io", 7777);
        String query = Executor.newInstance()
            .auth(entry, "customer-USERNAME-geohash-u09", "PASS")
            .execute(Request.Get("http://ip.oxylabs.io/location").viaProxy(entry))
            .returnContent().asString();
        System.out.println(query);
    }
}
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System;
using System.Net;

class Example
{
    static void Main()
    {
        var client = new WebClient();
        client.Proxy = new WebProxy("pr.oxylabs.io:7777");
        client.Proxy.Credentials = new NetworkCredential("customer-USERNAME-geohash-u09", "PASSWORD");
        Console.WriteLine(client.DownloadString("https://ip.oxylabs.io/location"));
    }
}
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'uri'
require 'net/http'

uri = URI.parse('https://ip.oxylabs.io/location')
proxy = Net::HTTP::Proxy('pr.oxylabs.io', 7777, 'customer-USERNAME-geohash-u09', 'PASSWORD')

req = Net::HTTP::Get.new(uri.path)

result = proxy.start(uri.host,uri.port) do |http|
    http.request(req)
end

puts result.body

```

{% endtab %}
{% endtabs %}

### Geohash fallback

{% hint style="warning" %}
`geohash` and `geohash_fallback` are mutually exclusive with each other and with other geo-location parameters, such as `cc` (country), `city`, `st` (state), `cn` (continent), and `postalcode`.
{% endhint %}

If your use case does not require a strict cell match, `geohash_fallback` uses the rotator that automatically removes one Geo hash character at a time to expand the area until an available proxy is found.&#x20;

If no IP is found at single-character level, a `502 Bad Gateway` error is returned.

```
customer-USERNAME-geohash_fallback-2svd:PASSWORD
```

* **Initial target:** `2svd` (≤ 39.1 km × 19.5 km)
* **Fallback 1 (1 character removed):** `2sv` (≤ 156 km × 156 km)
* **Fallback 2 (2 characters removed):** `2s` (≤ 1,250 km × 625 km)
* **Fallback 3 (3 characters removed):** `2` (≤ 5,000 km × 5,000 km)

{% hint style="info" %}
**Tracking the fallback:** Geo hash cell that was used is returned in the `x-geo-hash-fallback` response header. Compare it with your requested value to see if a fallback occurred and how far the area was expanded.
{% endhint %}

#### Code example

```shellscript
curl -v -x pr.oxylabs.io:7777 -U "customer-USERNAME-geohash_fallback-2svd:PASSWORD" https://ip.oxylabs.io/location
```

***

## ASN targeting

Route traffic through specific Internet Service Provider (ISP) networks using Autonomous System Numbers (`ASN`). You can find ASN numbers [**here**](https://asnlookup.com/)**.**

```
customer-USERNAME-ASN-21928-sessid-abcde12345:PASSWORD
```

If no active proxies are available for the specified ASN, the request returns a `502 Bad Gateway` error.

{% hint style="warning" %}
Accessing Residential Proxies from certain ASNs can return a `403 Access denied: restricted ASN` error if KYC verification is not completed for your Oxylabs account. [Contact support](mailto:support@oxylabs.io) to complete KYC process.
{% endhint %}

{% hint style="info" %}
You can use either Country or ASN parameter per each request. If both location parameters are used, only Country parameter will be applied.
{% endhint %}

***

## Coordinates

Target proxies near specific geographic coordinates using the `X-Oxylabs-Geolocation` HTTP proxy header. Value format is `Latitude:Longitude;Radius` (radius in miles, minimum 10 miles).

```
X-Oxylabs-Geolocation: 49.9235:-97.0811;10
```

{% hint style="info" %}
If no IP is found within the provided coordinates and radius, you will receive `502` response code. See full list of response codes [**here**](/products/proxies/residential-proxies/additional-information.md).
{% endhint %}

#### Code example

```bash
curl -x pr.oxylabs.io:7777 -U "customer-USERNAME:PASSWORD" --proxy-header "X-Oxylabs-Geolocation: 49.9235:-97.0811;10" https://ip.oxylabs.io/location
```

## China entry nodes

For requests initiated from mainland China, dedicated HTTPS regional entry nodes provide optimized connectivity.

* **Hong Kong:** `a81298871.com:8000`
* **Beijing:** `cnt9t1is.com:8000`

```bash
curl -x cnt9t1is.com:8000 -U "customer-USERNAME-cc-US:PASSWORD" https://ip.oxylabs.io/location
```

{% hint style="warning" %}
**Note:** Some third-party tools may not work with Hong Kong and Beijing entry nodes. Confirmed working tools include [Oxy Proxy Extension for Chrome](https://developers.oxylabs.io/integrations/proxy-integrations/oxy-proxy-extension-for-chrome), [SwitchyOmega](https://developers.oxylabs.io/integrations/proxy-integrations/switchyomega), and [Shadowrocket](https://developers.oxylabs.io/integrations/proxy-integrations/shadowrocket). We are currently working on supporting more integrations for HTTPS protocol.

If you are connecting to our residential network from China and still have issues with provided entry nodes, please get in touch at [**support@oxylabs.io**](mailto:support@oxylabs.io) for additional help.
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/proxies/residential-proxies/location-settings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.