Skip to main content
Geo Targeting routes each request through a proxy exit in a specific region. Use it when content changes by location or language. Common uses:
  • Localized content: pricing, availability, shipping, store pages.
  • SEO & market research: region-specific SERPs and ads.
  • Fewer blocks: look like a real local user with residential exits.

​
Parameters

​
country
string
default:"US"
Make your request appear as if it’s coming from a specific country. Perfect for accessing region-specific content like localized prices or availability.When to use:
  • E-commerce sites with different prices by country
  • Content that varies by region
  • Accessing geo-restricted pages
  • SEO analysis for different markets
Use ISO Alpha-2 Country Codes i.e. US, DE, GB.
Use ALL for random country selection.
Example:
"country": "UK"
​
state
string
For US or CA locations only - specify which state your request should come from.Use ISO Alpha-2 Country Codes i.e. NY, AZ, CANote: Only works when country is set to US or CA. Useful for state-specific content like local store inventory or regional pricing.
Example:
"country": "US",
"state": "CA"
​
city
string
Target a specific city for hyper-local content. Works best when combined with country (and state for US cities).When to use:
  • Local business listings
  • City-specific promotions
  • Store availability by location
  • Hyper-local content
Examples: "new_york", "london", "paris"
Example:
"country": "US",
"state": "NY",
"city": "new_york"
​
locale
string
default:"auto"
Set the browser’s preferred language. This changes the Accept-Language header and tells websites which language you prefer.Most common locales:
  • en-US - English (United States)
  • en-GB - English (United Kingdom)
  • fr-FR - French (France)
  • de-DE - German (Germany)
  • es-ES - Spanish (Spain)
  • ja-JP - Japanese (Japan)
  • zh-CN - Chinese (China)
  • pt-BR - Portuguese (Brazil)
  • auto - Automatically match the country
Supported locales:aa-DJ, aa-ER, aa-ET, af, af-NA, af-ZA, ak, ak-GH, am, am-ET, an-ES, ar, ar-AE, ar-BH, ar-DZ, ar-EG, ar-IN, ar-IQ, ar-JO, ar-KW, ar-LB, ar-LY, ar-MA, ar-OM, ar-QA, ar-SA, ar-SD, ar-SY, ar-TN, ar-YE, as, as-IN, asa, asa-TZ, ast-ES, az, az-AZ, az-Cyrl, az-Cyrl-AZ, az-Latn, az-Latn-AZ, be, be-BY, bem, bem-ZM, ber-DZ, ber-MA, bez, bez-TZ, bg, bg-BG, bho-IN, bm, bm-ML, bn, bn-BD, bn-IN, bo, bo-CN, bo-IN, br-FR, brx-IN, bs, bs-BA, byn-ER, ca, ca-AD, ca-ES, ca-FR, ca-IT, cgg, cgg-UG, chr, chr-US, crh-UA, cs, cs-CZ, csb-PL, cv-RU, cy, cy-GB, da, da-DK, dav, dav-KE, de, de-AT, de-BE, de-CH, de-DE, de-LI, de-LU, dv-MV, dz-BT, ebu, ebu-KE, ee, ee-GH, ee-TG, el, el-CY, el-GR, en, en-AG, en-AS, en-AU, en-BE, en-BW, en-BZ, en-CA, en-DK, en-GB, en-GU, en-HK, en-IE, en-IN, en-JM, en-MH, en-MP, en-MT, en-MU, en-NA, en-NG, en-NZ, en-PH, en-PK, en-SG, en-TT, en-UM, en-US, en-VI, en-ZA, en-ZM, en-ZW, eo, es, es-419, es-AR, es-BO, es-CL, es-CO, es-CR, es-CU, es-DO, es-EC, es-ES, es-GQ, es-GT, es-HN, es-MX, es-NI, es-PA, es-PE, es-PR, es-PY, es-SV, es-US, es-UY, es-VE, et, et-EE, eu, eu-ES, fa, fa-AF, fa-IR, ff, ff-SN, fi, fi-FI, fil, fil-PH, fo, fo-FO, fr, fr-BE, fr-BF, fr-BI, fr-BJ, fr-BL, fr-CA, fr-CD, fr-CF, fr-CG, fr-CH, fr-CI, fr-CM, fr-DJ, fr-FR, fr-GA, fr-GN, fr-GP, fr-GQ, fr-KM, fr-LU, fr-MC, fr-MF, fr-MG, fr-ML, fr-MQ, fr-NE, fr-RE, fr-RW, fr-SN, fr-TD, fr-TG, fur-IT, fy-DE, fy-NL, ga, ga-IE, gd-GB, gez-ER, gez-ET, gl, gl-ES, gsw, gsw-CH, gu, gu-IN, guz, guz-KE, gv, gv-GB, ha, ha-Latn, ha-Latn-GH, ha-Latn-NE, ha-Latn-NG, ha-NG, haw, haw-US, he, he-IL, hi, hi-IN, hne-IN, hr, hr-HR, hsb-DE, ht-HT, hu, hu-HU, hy, hy-AM, id, id-ID, ig, ig-NG, ii, ii-CN, ik-CA, is, is-IS, it, it-CH, it-IT, iu-CA, iw-IL, ja, ja-JP, jmc, jmc-TZ, ka, ka-GE, kab, kab-DZ, kam, kam-KE, kde, kde-TZ, kea, kea-CV, khq, khq-ML, ki, ki-KE, kk, kk-Cyrl, kk-Cyrl-KZ, kk-KZ, kl, kl-GL, kln, kln-KE, km, km-KH, kn, kn-IN, ko, ko-KR, kok, kok-IN, ks-IN, ku-TR, kw, kw-GB, ky-KG, lag, lag-TZ, lb-LU, lg, lg-UG, li-BE, li-NL, lij-IT, lo-LA, lt, lt-LT, luo, luo-KE, luy, luy-KE, lv, lv-LV, mag-IN, mai-IN, mas, mas-KE, mas-TZ, mer, mer-KE, mfe, mfe-MU, mg, mg-MG, mhr-RU, mi-NZ, mk, mk-MK, ml, ml-IN, mn-MN, mr, mr-IN, ms, ms-BN, ms-MY, mt, mt-MT, my, my-MM, nan-TW, naq, naq-NA, nb, nb-NO, nd, nd-ZW, nds-DE, nds-NL, ne, ne-IN, ne-NP, nl, nl-AW, nl-BE, nl-NL, nn, nn-NO, nr-ZA, nso-ZA, nyn, nyn-UG, oc-FR, om, om-ET, om-KE, or, or-IN, os-RU, pa, pa-Arab, pa-Arab-PK, pa-Guru, pa-Guru-IN, pa-IN, pa-PK, pap-AN, pl, pl-PL, ps, ps-AF, pt, pt-BR, pt-GW, pt-MZ, pt-PT, rm, rm-CH, ro, ro-MD, ro-RO, rof, rof-TZ, ru, ru-MD, ru-RU, ru-UA, rw, rw-RW, rwk, rwk-TZ, sa-IN, saq, saq-KE, sc-IT, sd-IN, se-NO, seh, seh-MZ, ses, ses-ML, sg, sg-CF, shi, shi-Latn, shi-Latn-MA, shi-Tfng, shi-Tfng-MA, shs-CA, si, si-LK, sid-ET, sk, sk-SK, sl, sl-SI, sn, sn-ZW, so, so-DJ, so-ET, so-KE, so-SO, sq, sq-AL, sq-MK, sr, sr-Cyrl, sr-Cyrl-BA, sr-Cyrl-ME, sr-Cyrl-RS, sr-Latn, sr-Latn-BA, sr-Latn-ME, sr-Latn-RS, sr-ME, sr-RS, ss-ZA, st-ZA, sv, sv-FI, sv-SE, sw, sw-KE, sw-TZ, ta, ta-IN, ta-LK, te, te-IN, teo, teo-KE, teo-UG, tg-TJ, th, th-TH, ti, ti-ER, ti-ET, tig-ER, tk-TM, tl-PH, tn-ZA, to, to-TO, tr, tr-CY, tr-TR, ts-ZA, tt-RU, tzm, tzm-Latn, tzm-Latn-MA, ug-CN, uk, uk-UA, unm-US, ur, ur-IN, ur-PK, uz, uz-Arab, uz-Arab-AF, uz-Cyrl, uz-Cyrl-UZ, uz-Latn, uz-Latn-UZ, uz-UZ, ve-ZA, vi, vi-VN, vun, vun-TZ, wae, wae-CH, wo-SN, xh-ZA, xog, xog-UG, yav, yav-CM, yo, yo-NG, zh, zh-CN, zh-HK, zh-Hans, zh-Hans-CN, zh-Hans-HK, zh-Hans-MO, zh-Hans-SG, zh-Hant, zh-Hant-HK, zh-Hant-MO, zh-Hant-TW, zh-MO, zh-SG, zh-TW, zu, zu-ZABest practice: Match your locale to your country (e.g., fr-FR with country: "FR") for the most authentic experience.
Example:
"country": "FR",
"locale": "fr-FR"

Supprted Geo Locations
country/state/city geo targeting changes where the request comes from. locale changes which language the browser prefers.

​
Usage

This request exits from New York and sets the browser language to English. 
from nimble_python import Nimble

nimble = Nimble(api_key="YOUR-API-KEY")

result = nimble.extract(
    url="https://ipinfo.io/json",
    country="US",
    state="NY",
    locale="en-US",
)

print(result)

​
Best practices

​
Use geo targeting when content varies by location

Only specify country/state/city when the content differs by location. 
# ✅ Use for location-specific content
result = nimble.extract({
    "url": "https://www.example.com/products",
    "country": "UK"  # Prices and availability vary by country
})

# ❌ Unnecessary for global content
result = nimble.extract({
    "url": "https://www.example.com/about",
    "country": "DE"  # About page is the same everywhere
})

​
Match locale to target country

Set the locale to match the country for accurate localized content. 
# ✅ Locale matches country
result = nimble.extract({
    "url": "https://www.example.com",
    "country": "FR",
    "locale": "fr-FR"
})

# ✅ Locale auto matching country
result = nimble.extract({
    "url": "https://www.example.com",
    "country": "FR",
    "locale": "auto"
})

# ❌ Locale doesn't match country
result = nimble.extract({
    "url": "https://www.example.com",
    "country": "FR",
    "locale": "en-US"  # May not get French content
})

​
Start with country-level targeting

Use country-level targeting first, then add state/city if needed. 
# ✅ Start simple with country
result = nimble.extract({
    "url": "https://www.example.com",
    "country": "US"
})

# ✅ Add state if content differs
result = nimble.extract({
    "url": "https://www.example.com",
    "country": "US",
    "state": "NY"  # Only if NY shows different content
})

# ❌ Overly specific when not needed
result = nimble.extract({
    "url": "https://www.example.com/global-page",
    "country": "US",
    "state": "NY",
    "city": "New York"  # Unnecessary granularity
})