> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinmassive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geotargeting

> You can tune the request by providing geo parameters like an [ISO ZIP code, subdivision, and country code](https://www.iso.org/obp/ui/#search), and by [city](https://www.geonames.org/).

You can tune the request by providing geo parameters like an [ISO ZIP code, subdivision, and country code](https://www.iso.org/obp/ui/#search), and by [city](https://www.geonames.org/).

```bash theme={null}
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-country-US-zipcode-10001:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
```

## Country, subdivision, city, zipcode

| Key         | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Examples         |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| country     | A two-letter country code (these codes are case insensitive)                                                                                                                                                                                                                                                                                                                                                                                             | US, GB           |
| subdivision | The alphanumeric second part (proceeding the separator) of a first-level subdivision code in the (prerequisite) country (case insensitive)                                                                                                                                                                                                                                                                                                               | CA, LND          |
| city        | A commonly spelled city name (temporarily case sensitive and inclusive of URL-encoded spaces and punctuation marks) in the (prerequisite) country. We always use the **English (en)** variant of the **preferred** city name, which can be verified on [GeoNames](https://www.geonames.org/) (as referenced in [MaxMind’s documentation](https://support.maxmind.com/hc/en-us/articles/4414877149467-IP-Geolocation-Data#h_01FRRNFD5Z5EWNCAXM6SZZ5H2C)). | New York, London |
| zipcode     | A postal code. Please take a look at the limitations below.                                                                                                                                                                                                                                                                                                                                                                                              | 10001, OX2       |

## Geotargeting rules

* `country` key must always persist if any of the geo parameters is specified. Otherwise, HTTP 400 is returned.
* If more than one geo key is specified, the server finds an appropriate node strictly matching all the parameters. The only exception is `zipcode`: if specified, `city` key is ignored.
  * **Details**:
    * If both subdivision and zipcode are provided, the city is ignored.
    * If both zipcode and city are provided, the city is ignored.
    * If subdivision and city are provided, both are strictly matched.

*Please, take into account, that due to technical reasons, the more strict geotargeting narrows the range of appropriate nodes.*

## Zipcode Notes

For the following countries, we accept partial postal codes with the number of characters indicated below:

* **United States**: 5
* **Canada**: 3
* **United Kingdom**: 2-4
* **Brazil**: 5
* **Ireland**: 3
* **Japan**: 7 (specified for the first 6. The last digit defaults to 1)
* **Netherlands**: 4
* **Portugal**: 7 (accurate for the first 4. The last 3 often default to -001)
* **Singapore**: 2

Geotargeting by country and city is always more robust than by ZIP code.

## Examples

### Country

```bash theme={null}
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-country-US:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
```

### Country and city

```bash theme={null}
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-country-US-city-New%20York:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
```

### Country and subdivision

```bash theme={null}
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-country-US-subdivision-NY:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
```

### Country and zipcode

```bash theme={null}
curl -x https://network.joinmassive.com:65535 \
     -U '{PROXY_USERNAME}-country-US-zipcode-10001:{API_KEY}' \
     https://cloudflare.com/cdn-cgi/trace
```