Salta ai contenuti

Geolocating with the Spam Filter

Questi contenuti non sono ancora disponibili nella tua lingua.

The Spam Filter offers geolocation and geofencing features, allowing you to restrict access to certain countries or regions. These features are available when providing either the ipAddress or timeZone parameters to the Spam Filter.

Use these features to adjust the spam classification mechanism or to restrict access based on the user’s location.

Expected Countries

To enhance the accuracy of spam classification, specify the list of countries or regions where you expect your users to be located. For instance, if your website is in German, list Germany as the expected country:

"ipAddress": "auto",
"expectedCountries": ["de"]

In this example, if the user is not located in Germany, the scoring rule UNEXPECTED_COUNTRY will be triggered, increasing the overall spam score. This rule is of “medium” significance, meaning it can still pass as a legitimate message depending on other rules.

To forcefully block users, use the blockedCountries parameter, as described in Geofencing below.

For multilingual websites or if you want to accept submissions from broader regions, such as continents, utilize pre-defined lists, for example "expectedCountries": ["list:eu"], which allows all EU member states.


To restrict access to specific locations, send blockedCountries to the Spam Filter’s /classify endpoint:

"ipAddress": "auto",
"blockedCountries": ["ir", "kp"]

In the example above, countries Iran (ir) and North Korea (kp) will trigger the BLOCKED_COUNTRY rule, effectively classifying the data as spam.

The API also provides pre-defined lists of countries, as detailed below in Pre-defined Lists, for simpler notation. For instance, the following example will block all sanctioned countries:

"ipAddress": "auto",
"blockedCountries": ["list:sanctioned"]

Using Time Zone

Although ALTCHA’s IP-location is about 99% accurate on the country level, users often utilize proxies and VPNs to hide their true location when accessing the Internet. The Spam Filter enables geolocation using the user’s time zone, which is considered more accurate than IP addresses, as most modern operating systems automatically adjust the user’s time zone to their actual location.

To classify using the user’s time zone, use the IANA format:

"timeZone": "Europe/London"

You can retrieve a user’s IANA time zone using the following JavaScript code:

const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;


continent:euEurope 1
continent:naNorth America
continent:saSouth America

Pre-defined Lists

list:euEU member states
list:sanctionedSee sanctioned countries 2



  1. The Europe continent includes all countries geographically located in Europe. This includes Russia, Turkey, Ukraine, United Kingdom, etc. Use list:eu to include only EU member states.

  2. Sanctioned countries (source: OFAC): Iran, North Korea, Cuba, Syria, Belarus, Democratic Republic of the Congo, Russia, Libya, Central African Republic, Iraq, Myanmar, Lebanon, Somalia, Venezuela, Zimbabwe, China, Sudan