11Estimated Location
22==================
33
4+ .. image :: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/estimated-locations/is-estimated-flag.png
5+ :target: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/estimated-locations/is-estimated-flag.png
6+ :alt: Estimated location flag
7+
48.. important ::
59
610 The **Estimated Location ** feature is **disabled by default **.
711
8- Before enabling it, the :doc: `WHOIS Lookup feature <whois >` must be
9- enabled. Then set
10- :ref: `OPENWISP_CONTROLLER_ESTIMATED_LOCATION_ENABLED ` to ``True ``
12+ Before enabling it, the :ref: `WHOIS Lookup feature
13+ <controller_setup_whois_lookup>` must be enabled.
14+
15+ Then set :ref: `OPENWISP_CONTROLLER_ESTIMATED_LOCATION_ENABLED ` to
16+ ``True ``.
1117
1218.. contents :: **Table of contents**:
1319 :depth: 1
@@ -16,72 +22,102 @@ Estimated Location
1622Overview
1723--------
1824
19- This feature automatically creates or updates a device’ s location based on
20- latitude and longitude information retrieved from the WHOIS Lookup
25+ This feature automatically creates or updates a device' s location based on
26+ latitude and longitude information retrieved from the :doc: ` whois `
2127feature.
2228
23- Trigger Conditions
24- ------------------
29+ It is very useful for those users who have devices scattered across
30+ different geographic regions and would like some help to place the devices
31+ on the map, while being gently reminded to improve the precision of the
32+ location with a direct link for doing so.
2533
26- This feature is triggered when:
34+ It also significantly reduces the effort required to assign a geographic
35+ location manually when many devices are deployed in large buildings like
36+ schools, offices, hospitals, libraries, etc. Improve the precision of the
37+ estimated location just once and all the other devices sharing the same
38+ public IP will automatically inherit the same location.
2739
28- - A **fresh WHOIS lookup ** is performed for a device.
29- - Or when a WHOIS record already exists for the device’s IP **and **:
40+ The feature is not useful in the following scenarios:
3041
31- - The device’s last IP address is **public **.
32- - WHOIS lookup and Estimated Location is **enabled ** for the device’s
33- organization.
42+ - Most devices are deployed in one single location.
43+ - Most devices are mobile (e.g. moving vehicles).
3444
35- Behavior
36- --------
45+ Visibility of Estimated Status
46+ ------------------------------
3747
38- The system will ** attach the already existing matching location ** of
39- another device with same ip to the current device if :
48+ The estimated status of a location is visible in the admin interface in
49+ several ways :
4050
41- - Only one device is found with that IP and it has a location.
42- - The current device **has no location ** or that location is
43- **estimated **.
51+ - The location name will mention the *IP address * from which it was
52+ estimated.
53+ - A *warning message * appears at the top of the location list page as in
54+ the image below.
4455
45- If there are multiple devices with location for the same IP, the system
46- will **not attach any location ** to the current device and a notification
47- will be sent suggesting the user to manually assign/create a location for
48- the device.
56+ .. image :: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/estimated-locations/estimated-warning.png
57+ :target: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/estimated-locations/estimated-warning.png
58+ :alt: Estimated location warning
4959
50- If there is **no matching location **, a new estimated location is created
51- or the existing one is updated using coordinates from the WHOIS record,
52- but only if the existing location is estimated.
60+ - The *Is Estimated? * flag is displayed both in the location list page and
61+ in the location detail page, as in the images below.
5362
54- If two devices share the same IP address and are assigned to the same
55- location, and the last IP of one of the devices is updated, the system
56- will create a new estimated location for that device.
63+ .. image :: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/estimated-locations/admin-list.png
64+ :target: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/estimated-locations/admin-list.png
65+ :alt: Estimated location admin list
5766
58- Visibility of Estimated Status
59- ------------------------------
67+ .. image :: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/estimated-locations/is-estimated-flag.png
68+ :target: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/estimated-locations/is-estimated-flag.png
69+ :alt: Estimated location flag
70+
71+ - The device list page also allows filtering devices which are associated
72+ with estimated locations as shown in the image below.
6073
61- The estimated status of a location is visible on the location page if the
62- feature is enabled for the organization. The location admin page also
63- includes indicators for the estimated status.
74+ .. image :: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/estimated-locations/filter-devices-by-estimated- location.png
75+ :target: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/estimated-locations/filter-devices-by-estimated- location.png
76+ :alt: Filter devices associated to estimated locations
6477
65- - The name of the location will have suffix **(Estimated Location :
66- <ip_address>) **.
67- - A warning on top of the page.
68- - **Is Estimated ** field.
78+ Any change to the geographic coordinates of an estimated location will set
79+ the ``is_estimated `` field to ``False ``.
6980
70- Changes to the ``coordinates `` and ``geometry `` of the estimated location
71- will set the ``is_estimated `` field to ``False `` and remove the
72- "(Estimated Location)" suffix with IP from the location name.
81+ When manually increasing the precision of estimated locations, it is
82+ highly recommended to also change the auto-generated location name.
7383
74- In REST API, the field will be visible in the :ref: `Device Location
75- <device_location_estimated>`, :ref: `Location list
84+ In the REST API, the `` is_estimated `` field is visible in the :ref: `Device
85+ Location <device_location_estimated>`, :ref: `Location list
7686<location_list_estimated>`, :ref: `Location Detail
77- <location_detail_estimated>` and :ref: `Location list (GeoJson)
78- <location_geojson_estimated>` if the feature is **enabled **. The field can
79- also be used for filtering in the location list (including geojson)
80- endpoints and in the :ref: `Device List <device_list_estimated_filters >`.
87+ <location_detail_estimated>` and :ref: `Location list (GeoJSON)
88+ <location_geojson_estimated>` endpoints if the feature is enabled. The
89+ field can also be used for filtering in the location list endpoints,
90+ including the GeoJSON endpoint, and in the :ref: `Device List
91+ <device_list_estimated_filters>`.
92+
93+ Triggers and Record Management
94+ ------------------------------
95+
96+ The feature is triggered automatically when all the following conditions
97+ are met:
98+
99+ - A WHOIS lookup is performed.
100+ - The last IP is a public IP address.
101+ - Both WHOIS lookup and Estimated Location features are enabled for the
102+ device's organization.
103+
104+ If no matching location exists, a new estimated location is created using
105+ coordinates from the WHOIS record. If an estimated location already
106+ exists, it will be updated with the new coordinates.
107+
108+ If another device with the same IP already has a location, the system will
109+ assign the same location for any device having the same IP and not being
110+ assigned to any other location.
111+
112+ If two devices share the same IP and are assigned to the same location,
113+ and one of them updates its last IP, the system will create a new
114+ estimated location for that device.
81115
82- Managing Older Estimated Locations
83- ----------------------------------
116+ When multiple devices with the same IP already have a location assigned
117+ but the locations differ, the system will send a notification to network
118+ administrators asking to manually resolve the ambiguity.
84119
85- Whenever location related fields in WHOIS records are updated as per
86- :ref: `Managing WHOIS Older Records <whois_older_records >`; the location
87- will also be updated automatically.
120+ When WHOIS records are updated as described in :ref: `the WHOIS Lookup
121+ section <controller_whois_auto_management>`, any related estimated
122+ location will also be updated, if needed and only if the estimated
123+ location has not been manually modified to increase precision.
0 commit comments