Holding — Provider API v0.6.3

GET /holdings

Get holdings

Bearer token GetHoldings

Example request

cURL

curl -X GET "$PLAS_BASE_URL/holdings?publication_ids=310552&version=0.6.3" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $PLAS_TOKEN"

JavaScript

const response = await fetch(`${process.env.PLAS_BASE_URL}/holdings?publication_ids=310552&version=0.6.3`, {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": `Bearer ${process.env.PLAS_TOKEN}`,
  },
});
const data = await response.json();

Python

import os
import requests

response = requests.get(
    f"{os.environ['PLAS_BASE_URL']}/holdings",
    params={
        "publication_ids": "310552",
        "version": "0.6.3",
    },
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {os.environ['PLAS_TOKEN']}",
    },
)
data = response.json()

The host and token are environment variables: PLAS_BASE_URL the provider’s base URL · PLAS_TOKEN an access token.

Parameters

publication_idsrequired: query · array of string
A list of agent publication IDs, each publication ID should be url encoded and separated by a comma.
Example: 310552
show_to: query · array of string
A list of show_to values, where each value is url encoded and separated by a comma.
This tells the provider that the returned data is intended to be shown to a specific group of users, and all returned data must be filtered appropriately.
If no groups are given, all data should be returned.
Example: public
patron_id: query · string
The patron ID of the active patron.
Example: 40218873

Shared across operations: version. See the shared contract on the version page.

Responses

200 The response will contain a mapping from each publication ID to an array of holdings. GetHoldingResponseBody

If a publication ID represents a periodical, there can be from zero to many holdings for that publication ID, and each holding will represent a unique issue of that periodical.

If a publication ID does not represent a periodical, there can be from zero to one holding for that publication ID.

Generated from the schema

Example

{
  "holdings": {
    "holding-310552": [
      {
        "locations": [
          {
            "items": [
              {
                "availableState": "available",
                "itemId": "03011042557129",
                "lendingDays": 28,
                "loanableState": "loanable",
                "pickupLocations": [
                  {
                    "branchId": "nordby-main",
                    "branchName": "Nordby Main Library",
                    "sections": [
                      {
                        "id": "nordby-main-children",
                        "name": "Children’s department",
                        "type": "department"
                      }
                    ]
                  }
                ],
                "reserveId": "7730015"
              }
            ],
            "location": {
              "branchId": "nordby-main",
              "branchName": "Nordby Main Library",
              "path": [
                {
                  "id": "nordby-main-children",
                  "name": "Children’s department",
                  "type": "department"
                }
              ]
            },
            "pickupLocations": [
              {
                "branchId": "nordby-main",
                "branchName": "Nordby Main Library",
                "sections": [
                  {
                    "id": "nordby-main-children",
                    "name": "Children’s department",
                    "type": "department"
                  }
                ]
              }
            ],
            "shelfmark": "839.82 Und"
          }
        ],
        "numberOfReservations": 5,
        "periodical": {
          "grouping": [
            {
              "type": "year",
              "value": "2025"
            }
          ],
          "name": "Kari Nordmann"
        },
        "publicationId": "310552",
        "reserveId": "7730015"
      }
    ]
  }
}

Schema

GetHoldingResponseBody

holdingsmap of array of Holdingrequired
Show 1 fieldHide 1 field
- any keyarray of Holding
  Show 5 fieldsHide 5 fields
  - locationsarray of HoldingLocationrequired
    See HoldingLocation in the schema index
  - numberOfReservationsinteger
    This tells how many reservations there exist on the publication (or periodical).
    If this is unknown, the field is not set.
  - periodicalHoldingPeriodical
    See HoldingPeriodical in the schema index
  - publicationIdstringrequired
    The publication ID
  - reserveIdstringrequired
    This is the Reserve ID to be used for reserving this publication (or periodical). If this is empty, the publication (or periodical) is not reservable.
    If the holding represents a periodical, this reserve ID is still all that is required to reserve that issue.

400 The list of errors. Errors

Shared response, defined once for the whole API. See the shared contract on the version page.

Generated from the schema

Example

{
  "errors": [
    {
      "code": 200103,
      "info": "200103: invalid/unsupported query parameter value"
    }
  ]
}

Schema

Errors

errorsarray of Errorrequiredmin items 1
The first error should always be the most relevant.
Show 2 fieldsHide 2 fields
- codeintegerrequired
  A number representing the type of error.
  List of error codes:
  - \<error code\>: \<error description\>
  - 500: System error
  - 600: Unsupported Open Library API version
  - 10001: Endpoint disabled
  - 71001: Consent has not been given for 'loan history'
  - 100001: Wrong patron username or password
  - 100023: Patron ID not found
  - 100211: maxNumberOfEmailAddresses exceeded
  - 100215: maxNumberOfPhoneNumbers exceeded
  - 100221: Pickup location cannot contain sections
  - 100411: Updating patron consent failed
  - 100611: Updating patron notification settings failed
  - 101001: Reservation ID not found
  - 101047: Branch ID cannot be used as pick up branch
  - 101053: Section ID cannot be used as pick up branch
  - 102001: Loan ID not found
  - 102301: Loan not renewable, because it is an interlibrary loan
  - 102311: Loan not renewable, because it is reserved
  - 110001: Branch ID not found
  - 200001: Publication ID not found
  - 200077: ui language not supported
  - 200101: missing required query parameter
  - 200103: invalid/unsupported query parameter value
  - 300001: Initialize payment should not be used
  - 300005: Initialize payment should be used
  - 300009: Payment method not supported
  - 300013: Payment method does not support partial payment
  - 300301: Finalized payment can not de changed
  - 300311: FinalizePaymentRequest.fees contains fees with the same ID
  - 310001: Loan history ID not found
  - 310011: Loan history ID already exists
  - 330001: List ID not found
  - 330011: List ID already exists
  - 330101: List item ID not found
  - 330111: List item ID already exists
  One of: 500 · 600 · 100001 · 100023 · 100211 · 100215 · 100221 · 100411 · 100611 · 101001 · 101047 · 101053 · 102001 · 102301 · 102311 · 110001 · 200001 · 200077 · 200101 · 200103 · 300001 · 300005 · 300009 · 300013 · 300301 · 300311 · 310001 · 310011 · 330001 · 330011 · 330101 · 330111
- infostringrequired
  Starts with the text matching the error code field (defined above), and a describing text could be added.

401 Bearer token invalid, missing, or expired.

Shared response, defined once for the whole API. See the shared contract on the version page.

No response body.