Retrieving Alma item record circulation data

To retrieve circulation-related data for an item in Alma, you can use the Items API and the Fulfillment APIs. Below are the details of the endpoints and methods you can use to retrieve the requested information:

1. Item Record Circulation Data

Endpoint:

GET /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items/{item_pid}

Details Retrieved:

Circulation availability status: Available in the base_status field.
Call number: Available in the item_data > description field.
Shelving or library location: Available in the location and library fields.
Suppression value: Available in the /almaws/v1/users/{user_id}/requests field.

Example Request:

http

GET https://api-na.hosted.exlibrisgroup.com/almaws/v1/bibs/123456789/holdings/987654321/items/1122334455?apikey={your_api_key}

Example Response:

json

{
  "item_data": {
    "pid": "1122334455",
    "barcode": "1234567890123",
    "base_status": {
      "value": "1",
      "desc": "Item in place"
    },
    "policy": {
      "value": "02",
      "desc": "2-week loan"
    },
    "suppress_from_publishing": false,
    "location": {
      "value": "main",
      "desc": "Main Library"
    },
    "library": {
      "value": "MAIN",
      "desc": "Main Library"
    },
    "description": "QA76.73.P98"
  }
}

2. Circulation-Specific Data (Due Date, Hold Count)

For circulation data such as due date and hold count, you can use the Loan APIs and the Request APIs.

Retrieve Loan Details

Endpoint:
GET /almaws/v1/users/{user_id}/loans
Details Retrieved:
- Due date: Available in the due_date field.
- User's loan data can also provide circulation information if the item is currently checked out.

Retrieve Hold Count

Endpoint:
GET /almaws/v1/bibs/{mms_id}/requests
Details Retrieved:
- Number of active requests or holds against the bibliographic record.

Example Request (Hold Count):

http

GET https://api-na.hosted.exlibrisgroup.com/almaws/v1/bibs/123456789/requests?apikey={your_api_key}

Example Response (Hold Count):

json

{
  "total_record_count": 3,
  "requests": [
    { "request_id": "5678", "status": "Pending" },
    { "request_id": "91011", "status": "Ready" }
  ]
}

3. Retrieve Item Availability

To retrieve item availability specifically, you can use the Availability APIs:

Endpoint:

GET /almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items

Details Retrieved:

Shows the item's availability, location, and other metadata in a single query.

Example Response

json
{
       "item_data": {
        "pid": "234687730000541",
        "barcode": "75912",
        "policy": {
          "value": ""
        },
        "provenance": {
          "value": ""
        },
        "description": "",
        "library": {
          "value": "MAIN",
          "desc": "Main Library"
        },
        "location": {
          "value": "main",
          "desc": "Stacks"
        },
        "pages": "",
        "pieces": "1",
        "requested": false,
        "creation_date": "2011-12-17Z",
        "modification_date": "2018-06-13Z",
        "base_status": {
          "value": "1",
          "desc": "Item in place"
        },
        "awaiting_reshelving": false,
        "physical_material_type": {
          "value": "BOOK",
          "desc": "Book"
        }
}

Summary of Key Fields and Sources

Data Field	API	Field	Endpoint

Data Field	API	Field	Endpoint
Circulation availability status	Items API	`base_status`	`/items/{item_pid}`
Due date	Loan APIs	`due_date`	`/users/{user_id}/loans`
Hold count	Request APIs	`total_record_count`	`/bibs/{mms_id}/requests`
Call number	Items API	`item_data.description`	`/items/{item_pid}`
Shelving or library location	Items API	`location`, `library`	`/items/{item_pid}`
Suppression value	Items API	`suppress_from_publishing`	`/items/{item_pid}`

Retrieving Alma item record circulation data

1. Item Record Circulation Data

Endpoint:

Details Retrieved:

Example Request:

Example Response:

2. Circulation-Specific Data (Due Date, Hold Count)

Retrieve Loan Details

Retrieve Hold Count

Example Request (Hold Count):

Example Response (Hold Count):

3. Retrieve Item Availability

Endpoint:

Details Retrieved:

Example Response

Summary of Key Fields and Sources

Useful Links