FAQ content

API: Overview of the LibInsight API

In this article

What can you do with LibInsight's API?

Like widgets, LibInsight's API allows you to create POST requests to add data to certain dataset types and to submit GET requests for data analysis within another set of dataset types. The big difference between widgets and the API is that an API allows you to create your own custom app or script that posts data from another source.

For example, if your security gate has an API for retrieving gate count readings, you could develop your own script that takes the data from your gate and post it to your gate count dataset in LibInsight.

APIs are intended for users who have some programming know-how. If you are looking for a simple way to manually record data from outside of LibInsight, consider using widgets instead.


API Authentication

To request or post data to LibInsight via the API, you must first set up an application. This will provide you with a unique Client ID and Client Secret that you will need to obtain an access token. A valid token is required for LibInsight to return data to your app—if you do not include an access token, or the token is expired, an error message will be returned.

Your existing applications will be displayed under the Manage API Authorization tab.

To create a new application:

  1. Go to Admin > Widgets & APIs.
  2. Click on the Manage API Authentication tab.
  3. Click the Create Application button. 
The Create New Application button
  1. On the Add Application modal, set the Application Name. This is only used to help you organize your applications, so you know which ID/Secret pairs you're using with your different apps.
  2. Optionally, you can add an Application Description to provide more info about how you're using this application.
  3. Click the Save button to save your changes. Your Client ID and Client Secret will appear in the Applications table.
The Add Application modal
  1. To obtain an access token, use the /1.1/oauth/token endpoint for your site's API. You'll find this information in the Obtaining an Access Token panel of the Manage API Authentication tab.
    • The LibInsight API uses OAuth 2.0 for authentication and supports the Client Credentials grant type.
  2. When submitting your API request, you'll need to provide that token in the Authorization header.
    • You can find an example for your site in the Authorizing your API Requests panel of the page.
The Obtaining an Access Token and Authorizing your API Requests boxes

Available endpoints

Full details for using each endpoint are available in LibInsight under the API Endpoints tab—click on the endpoint's panel on the page to view its specific documentation and example requests.

links under the Endpoints tab
To view the full documentation for an endpoint, click on its link in the URL column.

GET APIs

  • Acquisitions datasets
    • /acquisitions/{id}/overview: Returns Acquisitions dataset Overview stats.
    • /acquisitions/{id}/groups: Returns Acquisitions dataset Groups stats.
    • /acquisitions/{id}/classifications: Returns Acquisitions dataset Classification stats.
    • /acquisitions/{id}/popular: Returns Acquisitions dataset Popular stats.
    • /acquisitions/{id}/trends: Returns Acquisitions dataset Trends stats.
  • Calendar datasets
    • /calendar/{id}/overview: Returns Calendaring dataset Overview stats.
    • /calendar/{id}/trends: Returns Calendaring dataset Trends stats.
  • Circulation datasets
    • /circulation/{id}/overview: Returns Circulation dataset Overview stats.
    • /circulation/{id}/groups: Returns Circulation dataset Groups stats.
    • /circulation/{id}/classifications: Returns Circulation dataset Classification stats.
    • /circulation/{id}/popular: Returns Circulation dataset Popular stats.
    • /circulation/{id}/trends: Returns Circulation dataset Trends stats.
  • Counts/Aggregate datasets
    • /counts-aggregate/{id}/fields: Returns Counts/Aggregat dataset Fields metadata stats.
    • /counts-aggregate/{id}/overview: Returns Counts/Aggregate dataset Overview stats.
    • /counts-aggregate/{id}/field-aggregates: Returns Counts/Aggregat dataset Field Aggregates stats.
    • /counts-aggregate/{id}/distribution: Returns Counts/Aggregat dataset Distribution stats.
    • /counts-aggregate/{id}/trends: Returns Counts/Aggregate dataset Trends stats.
  • Custom/Shared datasets
    • /custom-dataset/{id}/data-grid: Returns the paginated Custom or Shared Dataset records based on the filters you passed.
  • Finance datasets
    • /finance/{id}/categories: Returns Finance dataset Categories
    • /finance/{id}/overview: Returns Finance dataset Overview stats.
    • /finance/{id}/trends: Returns Finance dataset Trends stats.
    • /finance/{id}/distribution: Returns Finance dataset Line Item stats.
  • Gate Count datasets
    • /gate-count/{id}/overview: Returns Gate Count dataset Overview stats.
    • /gate-count/{id}/trends: Returns Gate Count dataset Trends stats.
  • Google Analytics datasets
    • /google-analytics/{id}/overview: Returns Google Analytics dataset Overview stats.
    • /google-analytics/{id}/trends: Returns Google Analytics dataset Trends stats.
  • Interlibrary Loans (ILL) datasets
    • /interlibrary-loan/{id}/overview: Returns ILL dataset Overview stats.
    • /interlibrary-loan/{id}/details: Returns ILL dataset Details stats.
  • LibGuides datasets
    • /libguides/{id}/overview: Returns LibGuides dataset Overview stats.
    • /libguides/{id}/guides: Returns LibGuides dataset Guides stats.
    • /libguides/{id}/trends: Returns LibGuides dataset Trends stats.
  • Reference datasets
    • /reference/{id}/overview: Returns Reference dataset Overview stats.
    • /reference/{id}/trends: Returns Reference dataset Trends stats.

POST APIs

  • Custom/Shared datasets
    • /custom-dataset/{id}/type/{type}/save: Add records to a Custom or Shared dataset.
    • /custom-dataset/{id}/type/{type}/fields: Return all fields from a Custom or Shared dataset.
  • Gate Count datasets
    • /gate-count/{id}/save: Add records to a Gate Count dataset.
    • /gate-count/{id}/libraries: Returns Gate Count dataset Libraries.
Using the POST API

For your POST request to be successful, please note the following:

  • Only System Field and Custom Field keys can be passed.
    • System Field keys are optional (they can be omitted from the POST request body).
    • Custom Field keys are required to be passed, but their values are optional (unless a specific field has been set as required in your dataset's settings, in which case you would have to pass a value for that field).
  • You cannot pass a Custom Field key that is not listed in the API code.