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

# Perform strict matching

### Overview

Previously, when you requested an IP address from a specific geolocation and none were available, the system would silently fall back to a similar location in the same country. We are changing this behavior to make it explicit and give you more control:

1. **Strict Matching (Default)**
   * By default, if your requested geolocation is unavailable, you will receive an error indicating that no IP address is available (`proxy-error`).
   * This means the system will **not** automatically provide an alternative IP from another location.

2. **Fallback with Flag**
   * If you **want** to allow fallback (i.e., you want an IP from another location in the same country when your exact requested location is unavailable), you must explicitly enable it by setting the flag `-strict-off`.

### URL Flag Usage

You can now include one of the following flags in your username string:

* `-strict-on`
  * Forces strict matching. If there are no available IPs for the specified location, the system returns a `proxy-error`.
  * This is the **default** if you do **not** specify any strict flag.

* `-strict-off`
  * Allows fallback. If the exact location is unavailable, the system will return another IP from the same country (if available).

#### Syntax

```
geonode_<username>-type-<type_of_ip>-country-<country_code>-asn-<ASN_NUMBER>-strict-on:<password>
```

or

```
geonode_<username>-type-<type_of_ip>-country-<country_code>-asn-<ASN_NUMBER>-strict-off:<password>
```

> **Note:**
>
> * You can apply `-strict-on` or `-strict-off` to any combination of geo-targeting flags (e.g., `country`, `city`, `state`, `asn`), but we recommend always including a `-country-<country_code>` in your query.
> * The `asn` flag must be used **with** the `country` flag; otherwise, you will receive an error.

### Example Usage

#### 1. Fallback Enabled (`-strict-off`)

If you want to **allow** fallback to a different location in the same country when your requested location is unavailable:

```bash theme={null}
curl -x <proxy_host>:<port> \
    -U "geonode_username-type-residential-country-fr-asn-3215-strict-off:your_password" \
    --url "http://ip-api.com"
```

* Here, you requested a French (`country-fr`) IP that belongs to ASN `3215`.
* With `-strict-off`, if no IP is available exactly for ASN 3215 in France, the system will return a **different** IP from France.

#### 2. Strict Matching (`-strict-on`)

If you want **strict** matching for the exact country/ASN combination:

```bash theme={null}
curl -x <proxy_host>:<port> \
    -U "geonode_username-type-residential-country-fr-asn-3215-strict-on:your_password" \
    --url "http://ip-api.com"
```

* If no IP is available that exactly matches France + ASN 3215, the system will return:
  ```json theme={null}
  {"proxy-error":"country-fr-asn-3215 target was not found"}
  ```

### Error Cases

1. **No Exact Location Found (Strict Matching)**
   * **Error**: `{"proxy-error":"country-fr-asn-3215 target was not found"}`
   * Occurs when using `-strict-on` (or default strict matching) and the system cannot find an IP for that location.

2. **`asn`Without`country`**
   * **Error**: `{"proxy-error":"ASN should be used with country."}`
   * The `asn` flag must be paired with a specific country code.

3. **`-strict-on`or`-strict-off` Without Any Geo‐Targeting Flag**
   * **Error**: If you use `-strict-on` or `-strict-off` **without** specifying any location or ASN.
   * You must include at least one geo‐targeting parameter (e.g. `-country-xx`, `-asn-xxxxx`, etc.) for the request to make sense.

### Summary

* **Default**: Strict matching is enforced (the system does **not** fall back to another location).
* **Use`-strict-off`**: to allow fallback to a similar location within the same country.
* **Always Pair`asn` With `country`**:  `-asn-50543` must be accompanied by `-country-xx`.
* **Error Handling**: You will receive JSON error responses if no IP is found under strict conditions or if flags are incorrectly combined.

By explicitly controlling strict matching via `-strict-on` or `-strict-off`, you can now decide whether to **always** require a specific location or to **allow** fallback within the same country in case your requested location is unavailable.