(region)=

# Region

Firefox monitors the users region in order to show relevant local
search engines and content. The region is tracked in 2 properties:

- `Region.current` - The most recent location we detected for the user.
- `Region.home` - Where we consider the users home location.

These are tracked separately as to avoid updating the users
experience repeatedly as they travel for example. In general
callers should use `Region.home`.

## Region Updating

Firefox {searchfox}`uses a location service <mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf:modules/libpref/init/all.js#3107>` that is provided by Mozilla. Firefox will
attempt to check for region on first run of a new profile and
{searchfox}`every 7 days thereafter <mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf:toolkit/modules/Region.sys.mjs#106>`. If an update check fails, then the update will be
retried {searchfox}`after an hour <mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf:toolkit/modules/Region.sys.mjs#32-40>` for a {searchfox}`maximum of three times <mozilla-central/rev/b22ec3f983078ff98b04cee7dafe4b90342a42bf:toolkit/modules/Region.sys.mjs#101>`.

If the user is detected in a current region that is not their `home` region
for a continuous period (current 2 weeks) then their `home` region
will be updated.

### Testing

To set the users region for testing you can use:

```javascript
let {Region} = ChromeUtils.importESModule("resource://gre/modules/Region.sys.mjs");
Region._setHomeRegion("US", false)
```

Setting the second parameter (`notify`) to true will send an notification that
the region has changed and trigger a reload of search engines and other content.

## Updating test_Region_geocoding.js data

Note: The geocoding feature is not turned on by default.

The test data used in this test is generated by running the MLS geocoding
service locally:

Follow the Ichnaea location development guide @ <https://ichnaea.readthedocs.io/en/latest/local_dev.html>.

Make a list of test locations in a CSV format, for example:

```shell
23.7818724,38.0531587
23.7728138,38.0572369
1.6780180,48.5973431
1.7034801,48.5979913
1.6978640,48.5919751
```

You can use the MLS raw data files to get a large sample @ <https://location.services.mozilla.com/downloads>

Save a script to run the geocoding in `ichnaea/ichnaea`

```python
import geocode
geocoder = geocode.Geocoder()

f = open("mls.csv", "r")
r = open("mls-lookup-results.csv", "a")

for x in f:
  [lat, long] = x.strip().split(",")
  region = geocoder.region(lat, long)
  r.write("%s\n" % region)
```

Run the script

```shell
make shell
cd ichnaea
python run.py
```

If you want to commit the new test data ~500 seems to be a reasonable
number of data points to test before running into issues with the test length.