1.. _Region:
2
3======
4Region
5======
6
7Firefox monitors the users region in order to show relevant local
8search engines and content. The region is tracked in 2 properties:
9
10 * ``Region.current`` - The most recent location we detected for the user.
11 * ``Region.home`` - Where we consider the users home location.
12
13These are tracked separately as to avoid updating the users
14experience repeatedly as they travel for example. In general
15callers should use ``Region.home``.
16
17If the user is detected in a current region that is not there `home` region
18for a continuous period (current 2 weeks) then their `home` region
19will be updated.
20
21Testing
22=======
23
24To set the users region for testing you can use ``Region._setHomeRegion("US", false)``, the second parameter ``notify``
25will send a notification that the region has changed and trigger a
26reload of search engines and other content.
27
28Updating test_Region_geocoding.js data
29--------------------------------------
30
31The test data used in this test is generated by running the MLS geocoding
32service locally:
33
34Follow the Ichnaea location development guide @ https://ichnaea.readthedocs.io/en/latest/local_dev.html.
35
36Make a list of test locations in a CSV format, for example:
37
38.. code-block:: shell
39
40  23.7818724,38.0531587
41  23.7728138,38.0572369
42  1.6780180,48.5973431
43  1.7034801,48.5979913
44  1.6978640,48.5919751
45
46You can use the MLS raw data files to get a large sample @ https://location.services.mozilla.com/downloads
47
48Save a script to run the geocoding in ``ichnaea/ichnaea``
49
50.. code-block:: python
51
52  import geocode
53  geocoder = geocode.Geocoder()
54
55  f = open("mls.csv", "r")
56  r = open("mls-lookup-results.csv", "a")
57
58  for x in f:
59    [lat, long] = x.strip().split(",")
60    region = geocoder.region(lat, long)
61    r.write("%s\n" % region)
62
63Run the script
64
65.. code-block:: shell
66
67  $ make shell
68  $ cd ichnaea
69  $ python run.py
70
71If you want to commit the new test data ~500 seems to be a reasonable
72number of data points to test before running into issues with the test length.
73