Sort by Geographic Proximity: Configuration
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 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.