Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

Library Hours API

Alma Library Hours API

Introduction

Tarrant County College uses the Alma Library Hours API to present the open and close times of each of our five libraries.
We present the information in 3 ways in various locations:
  1. On our library homepage, we post the open/close hours for the current day. If the library is open that day, we also post a message reading either "Currently Open" or "Currently Closed"
  2. On our library calendar, we post the hours for each day of a chosen month for a chosen campus library.
  3. On our LibAnswers home page, we post the open/close hours for each library on the LibAnswers home page.

Please note that while I've included a version for Python 2.7 with Flask, I have never used Python or Flask in a production environment. The python zip files contain simple instructions for running the code in a virtualenv, but for running it in a production environment on a server, you're on your own. :-)

Parameters

Since we use the Alma hours API in these different ways, the PHP (or Python) code accepts GET parameters for library code, start date, end date, and format. The format parameter allows us to return XML, JSON, or a text snippet depending on our needs. For our purposes here at TCC, these are acceptable parameters (all parameters are optional):
  • campus
    default:Northeast
    parameters: Northeast, Northwest, South, Southeast, or TrinityRiv
    You would change these to your library code
  • start
    default: the current date
    parameters: a date in the format YYYY-MM-DD which must occur chronologically before or equal to the end parameter, if present
  • end
    default: the current date
    parameters: a date in the format YYYY-MM-DD which must occur chronologically equal to or after the start parameter
  • format
    default: 'today'
    parameters:
    • 'today' - returns a string for the current date; e.g.,
      <div class='alma_hours_open'>7:45am - 10:00pm</div>
      <div class='alma_hours_message alma_hours_message_open'>Currently Open</div>
      
    • 'html' - returns a string for multiple dates; e.g.,
      <div id='alma_hours'>
         <div class='alma_hours_library'>Northeast</div>
         <div class='alma_hours_date'>Jun 6, 2018</div>
         <div class='alma_hours_time'>7:45am - 10:00pm</div>
      </div>
      <div id='alma_hours'>
         <div class='alma_hours_library'>Northeast</div>
         <div class='alma_hours_date'>Jun 7, 2018</div>
         <div class='alma_hours_time'>7:45am - 10:00pm</div>
      </div>
                                                                         
      
    • 'fullCalendar' - returns a json string for a full month
    • 'xml' - returns the raw data from the Alma library hours API in xml format
    • 'json' - returns the raw data from the Alma library hours API in json format

Examples

Example calls:
  • https://my.server.edu/almahours.php?format=today
    returns a string with the library hours for the current day:
    <div class='alma_hours_open'>7:45am - 10:00pm</div><div class='alma_hours_message alma_hours_message_open'>Currently Open</div>
    
  • https://my.server.edu/almahours.php?format=html&start=2018-06-03&end=2018-06-09
    returns a string with the library code, date, and hours of daily info for a week:
    <div id='alma_hours'>
       <div class='alma_hours_library'>Northeast</div>
       <div class='alma_hours_date'>Jun 3, 2018</div>
       <div class='alma_hours_time'>Closed</div>
    </div>
    <div id='alma_hours'>
       <div class='alma_hours_library'>Northeast</div>
       <div class='alma_hours_date'>Jun 3, 2018</div>
       <div class='alma_hours_time'>7:45am - 10:00pm</div>
    </div>
    ...
    <div id='alma_hours'>
       <div class='alma_hours_library'>Northeast</div>
       <div class='alma_hours_date'>Jun 9, 2018</div>
       <div class='alma_hours_time'>Closed</div>
    </div>
                                               
    
  • https://my.server.edu/almahours.php?format=fullCalendar
    returns a json string for the current month to be used with FullCalendar
    
  • https://my.server.edu/almahours.php?format=xml&start=2018-01-01&end=2018-01-31
    returns the raw xml data for January 2018
    

Instructions

Instructions:
  1. Download the PHP file and place on your PHP server.
  2. Edit the PHP file with a code editor:
    1. Add your API key
      if(!defined("ALMA_API_KEY")) define("ALMA_API_KEY",  "YOUR API KEY GOES HERE");
      
    2. Add your library code or a default library code if you have more than one library
      if(!defined("LIBRARY_CODE")) define("LIBRARY_CODE",  "YOUR LIBRARY CODE (OR A DEFAULT LIBRARY CODE) GOES HERE");
      
  3. Test your access: http://my.server.edu/path/to/almahours.php?format=today
  4. Sample HTML file using jQuery:
    <!DOCTYPE html>
    <html lang="en">
    <head>
       <meta charset="utf-8" />
       <title>Alma Hours API Example</title>
       <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
       <script>
          $(document).ready( function(){
             $.get('http://my.server.edu/path/to/almahours.php',{format:today})
              .done( function(data) {
                $('#todays_hours').html(data);
              });
          });
       </script>
    </head>
    <body>
       <div id='todays_hours'></div>
    </body>
    </html>
                                               
    
  5. FullCalendar requires jQuery, moment, FullCalendar css, and FullCalendar javascript to work.
    For example, this should be included in your HTML document to use FullCalendar:
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/fullcalendar/3.9.0/fullcalendar.min.css" />
    <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.22.2/moment.min.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/fullcalendar/3.9.0/fullcalendar.js"></script>
                                               
    
  6. Examples

Contact

Collection and Records Management
Tarrant County College