Geographic Proximity

Status: Phase 1 Specs archived

Original requirements developed under MassLNC.

NOTE – On 11/14/2019, the ECDI voted to suspend this project.  New requirements for two smaller and related projects will be developed utilizing previous work and further input from ECDI members and advisers.  These projects will seek development of a “limit to available” feature in appropriate interfaces as well as a feature to search and sort based on geographic proximity.

Description

This project will provide a means for the public catalog to identify the user’s location, sort library holdings by geographic proximity, and display those holdings on a map.

Requirements

  1. The public catalog record page will provide an option for users to sort holdings by geographic proximity to the user.
  2. These requirements will sometimes refer to a default location that the system should try to set for the user. This default location should be set as follows:
    1. A config.tt2 setting should determine which of the following options should be used as the first choice for setting a default location:
      1. The home address for the logged-in user’s record. If this option is configured and the patron is not logged in, the catalog should then attempt to determine the default location with the option described in (ii) below.
      2. The preferred library that displays as the first library in the copies table when a preferred library is present. The system currently identifies this library based on the search library, patron’s preferred search library, patron’s home library, or physical_loc parameter (when present).
  3. A new config.tt2 setting should be available to determine what the default copy sort should be after retrieving a record. The options should be:
    1. The current sort method used in the copies table (preferred library followed by alphabetical sort). (See Mockup 1)
    2. When a default location can be determined as described in requirement 2, by geographic proximity to that default location. If no default location can be determined, sorting would fall back to the current default.
  4. The following elements should display above the copies table, allowing the user to sort by copies closest to a location:
    1. a text input that displays and allows the user to manually set their location. A ‘Go’ button allows the the user to submit this input.
    2. a location marker icon that, when pressed, will invoke the HTML5 GeoLocation API to automatically detect the user’s current location, with the user’s permission.
  5. A user should be able to enter a zip code, city/state, or exact address in the text input.
  6. The text input should display the current location when copies are being sorted geographically.
    1. The location should never display as geographical coordinates in the text input, except in cases where the user entered the location as geographical coordinates.
      1. If the location was retrieved via the HTML5 Geolocation API, the preferred library or patron address, it should display the Town/City, State, Zip Code in this input. The actual sorting should be by the exact location.
      2. If the user manually entered the location, the input should display whatever the user entered
  7. After clicking the ‘Go’ button, the copies should sort by proximity to the location that was submitted. (See Mockup 2)
    1. If the user submitted an invalid or null value:
      1. The system should try to identify a default location as described in requirement 2 and automatically sort by proximity to that location. This location should now populate the text input.
        1. A message should also display saying the system didn’t not recognize the entered location and is using xxxx as a location instead. (See Mockup 4)
      2. If no default location can be determined, a message should display asking the user to enter a location. The copies should continue to sort by the current Evergreen default. (See Mockup 3)
  8. If the user clicks the location marker icon, the browser should attempt to automatically detect the user’s current location using the HTML5 Geolocation API. The catalog should then sort copies by proximity to the detected location.
    1. If the user declines to reveal their location via the API or the location detection otherwise fails, the system should try to identify a default location as described in requirement 2 and automatically sort by proximity to that location. This location should populate the text input.
      1. A message should also display saying the system didn’t not recognize the entered location and is using xxxx as a location instead. (See Mockup 4)
    2. If no default location can be determined, a message should display asking the user to enter a location. The copies should continue to sort by the current Evergreen default. (See Mockup 3)
  9. Geographic proximity sorting should be sorted ascending by geographic distance from the set location. In cases where geographic proximity is equal, sorting should be alphabetical by library name.
  10. When copies are sorted by geographic proximity, the distance from the set location should also display.
    1. The system should be able to display this distance in either miles or kilometers. The unit of measurement should be chosen based on the user’s browser locale (preferred), an Evergreen setting, or some other means recommended by the developer.
    2. A class should be applied to the span of text displaying the distance to allow for customization.
  11. To allow users to remove the geographic sort, the Location column heading to the copies table should be clickable to sort first by preferred library then alphabetically.
    1. A visual cue should display to show that the column is sortable.
  12. A View Map link should also be available where users set their geographical locations. See Mockup 5
    1. When clicked, the catalog should display a popup dialog with a map that shows the locations of the closest libraries with holdings.
    2. The map view should also include a list of libraries that are currently visible on the map.
      1. The library name should be a link that goes to the same destination as the library name link in the copies table (the Library Info page or a URL designated in the Library Settings Editor).
      2. The library’s distance from the current location, in either miles or kilometers, should display. (See related requirement 10a)
      3. This interface should also indicate whether the library has an available copy(ies) or not.
    3. The map interface should also have a text input at the top of the window, similar to the one that will display above the copies table, that allows users to set/view the current location.
      1. Changing/setting the location from the map should follow the same behavior as previously described in requirements 4-8.
  13. When selecting an API for this project
    1. Preference should be given to open-source APIs, provided they are able to support the requested functions.
    2. The selected API should allow for growth in the catalog’s use of geographic data. Potential future Evergreen development projects might include limiting search results by location.
    3. The selected API should have a long track record and should have a large user base.

Mockups

The below mockups assume that the patron’s default location (when known) is in Westfield, MA. The user is currently located in Worcester, MA, which is what will be used when automatically detecting the location or when manually entering a location.

Mockup 1 – Record page with traditional sort

Westfield Athenaeum is listed at the top because it is the patron’s preferred library. Remaining libraries are sorted alphabetically. Text input displays offering users option to short by nearest copies. Westfield pre-populates the new text input, but the copies will not sort by proximity to the preferred library until the ‘Go’ button is clicked.

Mockup 2 Geographic sort when location is known

In this case, the browser automatically detected the user’s location to address in Worcester. Although the location only displays as Worcester, the distances are using the exact coordinates of the user’s location. If the user rejected the browser’s request to detect the location, we would see a similar display with Westfield, MA as the current location either because this is where the user’s preferred library is located or because it’s the town for the patron’s home address. Once again, even though we display the town here, the distances are calculated based on the geographical coordinates of the preferred library’s address or the patron’s full address.

If the library’s config.tt2 setting defaults to sorting geographically, when a default address is known, the display would be similar to this one as well, but would use the Westfield, MA location.

Mockup 3 Unknown Location after Go button or Location Marker are Clicked, No Default Location

The user has either entered an invalid location or null value in the text-entry or has clicked the location icon, but the browser is unable to obtain the location. The user is not logged in, does not have a preferred library or physical location set in some other way, and has scoped the search to the entire consortium. Sorting remains alphabetical, and an alert asks the user to manually enter an address.

Mockup 4 Unknown Location after Go button or Location Marker are Clicked, Default Location is Available

Mockup 5 Map View