Geolocating with the Spam Filter

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.

Geofencing

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;

Continents

Code	Name
continent:af	Africa
continent:an	Antarctica
continent:as	Asia
continent:eu	Europe 1
continent:na	North America
continent:oc	Oceania
continent:sa	South America

Pre-defined Lists

Code	Name
list:eu	EU member states
list:sanctioned	See sanctioned countries 2

Footnotes:

Footnotes

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 ↩