Guides
Start typing to search…

Perform Strict Matching / In‐Country Fallback Targeting

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:

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:

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: 
    {"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. asnWithoutcountry

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

  3. -strict-onor-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 Pairasn 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.