Alma Search (npm package)

This is intended to be an importable npm package for searching Alma APIs from ExLibris.

Requirements

You will need an Alma API key with bib read permissions to use this.

Installation

npm install @kenxirwin/alma-search

SearchBibs

The first (only so far) module is SearchBibs. It allows searching by barcode, mms_id, holdings_id, ie_id, representation_id, nz_mms_id, cz_mms_id, or other_system_id.

Import the package with

import {SearchBibs} from @kenxirwin/alma-search

Instantiate the search object with:

const searchBibs = new SearchBibs({
baseUrl: 'https://api-na.hosted.exlibrisgroup.com', // or other regional url
apiKey: 'your-api-key',
verbose: 'true' // defaults to false
});

The "verbose" param may be omitted, and defaults to false. If set to true, the system writes a log message to the console identifying the URL requested with each request.

Methods

barcodeLookup(barcode: string | number): Promise<AlmaItem>

Returns item data for a barcode.

Returns: Promise<AlmaItem>
Validated against: almaItemSchema

For barcode searching use:

import { SearchBibs, almaItemSchema } from '@kenxirwin/alma-search';
import type { AlmaItem } from '@kenxirwin/alma-search';
const response: AlmaItem = searchBibs.barcodeLookup('123456789');

idLookup(params: BibLookupParams): Promise<AlmaBibResponse>

Returns bibliographic data for an MMS ID or other Alma IDs.

Returns: Promise<AlmaBibResponse>
Validated against: almaBibResponseSchema

import { SearchBibs, almaBibResponseSchema } from '@kenxirwin/alma-search';
import type { AlmaBibResponse } from '@kenxirwin/alma-search';
const response: AlmaBibResponse = await searchBibs.idLookup({
mms_id: '99939650000541,99939680000541', // supports multiple ids
});

Accepts these params:

interface BibLookupParams {
  mms_id?: string;
  holdings_id?: string;
  ie_id?: string;
  representation_id?: string;
  nz_mms_id?: string;
  cz_mms_id?: string;
  other_system_id?: string;
}

holdingsByMmsId(mms_id: string): Promise<AlmaBibHoldings>

Returns holdings associated with a bibliographic record.

Returns: Promise<AlmaBibHoldings>
Validated against: almaBibHoldingsSchema

Once you receive the bib item record by a lookup process, you can view holdings details looking up by mms_id, e.g.:

import { SearchBibs, almaBibHoldingsSchema } from '@kenxirwin/alma-search';
import type { AlmaBibHoldings } from '@kenxirwin/alma-search';
const response: AlmaBibHoldings = await searchBibs.holdingsByMmsId('99939650000541');

holdingsItemsByMmsId(mms_id: string): Promise<AlmaItemHoldingsResponse>

Returns item and holdings data for a bibliographic record.

Returns: Promise<AlmaItemHoldingsResponse>
Validated against: almaItemApiResponseSchema

You can get item-level data from an MmsId with:

import { SearchBibs, almaItemApiResponseSchema } from '@kenxirwin/alma-search';
import type { AlmaItemApiResponse } from '@kenxirwin/alma-search';
const response: AlmaItemApiResponse = await searchBibs.holdingsItemsByMmsId('99939650000541');

or

const response = await searchBibs.holdingsItemsByMmsId('99939650000541', {limit: 20, offset: 20});

The holdingsItemsByMmsId functions supports all queryString params as well as the holding_id param described in the documentation

followLink(inputUrl: string): Promise<any>

Returns: Promise<any>

You can also follow any of the links returned to you by earlier searches with the followLink method. As with other methods, the API key will be added to the search by by the followLink method. Example:

import { SearchBibs } from '@kenxirwin/alma-search';
const response: any = await searchBibs.followLink(
'https://api-na.hosted.exlibrisgroup.com/almaws/v1/bibs/99939680000541/holdings'
);