--- /dev/null
+= Sort by Geographic Proximity: Configuration
+
+indexterm:[Geographic Sort,Search Results,Searching]
+
+:toc:
+
+The sort by geographic proximity feature allows library patrons to sort
+holdings within a bibliographic record by geographic distance. This
+feature requires a 3rd party geographic location service in order to
+function. Each Evergreen instance will need to secure its own geographic
+location service.
+
+The feature is controlled by three new Library Settings, a new Global
+Flag, two new permissions, and a new interface to configure Geographic
+Location Services. Fields to store latitude and longitude have been
+added to the *Org Unit Configuration* (/eg2/<locale>/staff/admin/server/actor/org_unit) page.
+
+== Library Settings
+
+* *Enable Holdings Sort by Geographic Proximity* - if this is unset it
+will default to FALSE. If set to TRUE, the record details page will
+display the address search box to enable proximity sort. The global flag
+*opac.use_geolocation* must also be enabled.
+* *Geographic Location Service to use for Addresses* - This setting
+specifies which geographic location service to use for converting
+address input to geographic coordinates. Geolocation Services are
+configured via *Server Administration → Geographic Location Services
+Configuration* interface. The value used in this is what is entered in
+the *Name* field of the Geographic Location Services Configuration.
+* *Show Geographic Proximity in Miles* - If set to TRUE, this setting will
+force the OPAC to display distance in miles. If this is unset it will
+default to FALSE, and the OPAC will display distance in kilometers.
+
+== Global Flag
+
+Navigate to *Server Administration → Global Flags* and locate the
+opac.use_geolocation flag. Select the *Enabled* checkbox to enable this
+flag. This flag must be enabled in order for proximity sort to work. The
+*Value* box does not need an entry and in fact any entry in that box
+will be ignored.
+
+== Permissions
+
+Two new permissions, VIEW_GEOLOCATION_SERVICES and
+ADMIN_GEOLOCATION_SERVICES, control viewing and editing values in the
+Geolocation Location Services interface. They are added to the System
+Administrator and Global Administrator permissions groups by default.
+
+== Geographic Location Service Configuration
+
+There is a new administrative interface located at *Server
+Administration → Geographic Location Service*
+(/eg2/<locale>/staff/admin/server/config/geolocation_service) which
+allows administrators to add and configure new geographic location
+services and parameters
+
+Click the button *New Geographic Location Service* to add a service to
+this table. Fields in the modal are:
+
+* _API Key_ - Provided by your geographic location service provider in
+order to authenticate against their service
+** Note that HTTP referrers will not work with this feature, but IP address restrictions will.
+* _Active_ - Specifies whether this particular location service is active
+or not.
+* _ID_ - This is automatically generated by the system.
+* _Name_ - Enter a name for this service in the Library Setting
+*Geographic Location Service to use for Addresses*. Since this value is
+translatable, if you give it a translation the Library Setting will
+automatically update to the translated value.
+* _Owner_ - Indicates which branch owns this service. This gives context
+to the two new permissions noted above but does not otherwise affect the
+* _Service Code_ - Determines which perl module to use for geocoding.
+Valid values are Free, Google, or OSM.
+** As of 2021, the perl module 'Google' uses the https://metacpan.org/pod/Geo::Coder::Google[GeoCoder v3 API]. Administrators are strongly advised to review the current Google API documentation.
+
+You will assign Service Providers to specific Organizational Units using
+the Library Setting *Geographic Location Service to use for Addresses*.
+
+== Other Administration
+
+The feature makes use of the latitude/longitude of each location’s
+physical address, as set in the *Org Unit Configuration*
+(/eg2/<locale>/staff/admin/server/actor/org_unit) page. There is a new
+pair of fields to contain Latitude and Longitude as well as a button
+which will use the physical address to calculate values for these two
+fields.
+
+Navigate to *Server Administration → Organizational Units*. Select the
+relevant Organizational Unit from the tree on the left, select the
+*Addresses* tab, and then select the *Physical Address* subtab. You may
+manually enter Latitude and Longitude values, or select the *Get
+Coordinates* button to generate coordinates from the address entered in
+the Physical Address subtab. Click the *Save* button to save your
+changes.
+
+The latitude and longitude values are available in the *Org Address*
+reporting source.
\ No newline at end of file
projects / evergreen-equinox.git / commitdiff
