NLB Singapore Catalogue API Skill

Search and retrieve bibliographic records from Singapore's National Library Board catalog.

Critical: Things Claude Won't Know Without This Skill

API key is required — two headers on every request

The NLB API requires both an API key and an app code:

X-API-KEY: your-api-key
X-APP-Code: your-app-code

Without these, all endpoints return 401. Apply for free keys at https://go.gov.sg/nlblabs-form (contact: nlblabs@nlb.gov.sg).

Set environment variables NLB_API_KEY and NLB_APP_CODE, or pass them to the Python client constructor.

Two search endpoints with different strengths

SearchTitles: ?Keywords=singapore+history&Limit=10
GetTitles:    ?Title=singapore&Author=lee&Limit=10

BRN is the primary record identifier

BRN (Bibliographic Record Number) is NLB's internal ID. Use it for GetTitleDetails and GetAvailabilityInfo lookups. Found in search results under records[].brn or brn.

Native language fields for CJK content

Most text fields have native-language variants: title/nativeTitle, author/nativeAuthor, seriesTitle/nativeSeriesTitle. Always check both for Chinese, Malay, and Tamil titles.

Endpoints

Key Search Parameters

SearchTitles

GetTitles

Response Structure

Search Results

{
  "totalRecords": 999,
  "count": 20,
  "hasMoreRecords": true,
  "nextRecordsOffset": 20,
  "titles": [
    {
      "title": "Singapore: A Biography",
      "nativeTitle": "",
      "author": "Frost, Mark Ravinder",
      "nativeAuthor": "",
      "records": [
        {
          "brn": 13737742,
          "isbns": ["9789814385169"],
          "publisher": ["Editions Didier Millet"],
          "publishDate": "2009",
          "subjects": ["Singapore -- History"],
          "format": {"code": "BK", "name": "Books"}
        }
      ]
    }
  ],
  "facets": [...]
}

Title Detail Fields

Full records include 50+ fields: brn, title, nativeTitle, author, nativeAuthor, publisher, publishDate, isbns, subjects, summary, contents, edition, physicalDescription, language, format, allowReservation, availability, activeReservationsCount.

Availability Info

{
  "items": [
    {
      "brn": 13737742,
      "callNumber": "959.57 FRO",
      "location": {"code": "TRL", "name": "Lee Kong Chian Reference Library"},
      "transactionStatus": {"code": "S", "name": "Available on Shelf"},
      "media": {"code": "BOOK", "name": "Book"}
    }
  ]
}

Transaction status codes: S (on shelf), L (on loan), H (on hold), I (in transit), T (transferred).

Python Script

from scripts.nlb_api import NlbAPI
nlb = NlbAPI()  # reads NLB_API_KEY and NLB_APP_CODE from env

# Keyword search (search() returns the full response dict;
# search_titles() returns just the list of title dicts)
data = nlb.search("singapore history", limit=10, languages=["Chinese"])
results = nlb.search_titles("singapore history", limit=10)

# Field-specific search (title, author, subject, isbn, keywords)
found = nlb.get_titles(title="dream of the red chamber", author="Cao")

# Title details by BRN
detail = nlb.get_title_details(brn=13737742)

# Check availability
avail = nlb.get_availability(brn=13737742)
for item in avail:
    print(f"{item['location']['name']}: {item['transactionStatus']['name']}")

# New arrivals
new = nlb.get_new_titles(date_range="Weekly", limit=20)

# Summarize
for r in results:
    print(nlb.summarize(r))

Library Branch Codes

Key locations: TRL (Lee Kong Chian Reference Library), WRL (Woodlands Regional Library), CMPL (Chinatown Public Library), AMKPL (Ang Mo Kio), BIPL (Bishan), JWPL (Jurong West), TPPL (Tampines).

API Etiquette

• Free API key required (apply at https://go.gov.sg/nlblabs-form)
• Rate limits enforced (429 on excess) — exact thresholds undocumented
• Data licensed under Singapore Open Data Licence

Related Skills

• hathitrust-catalog: Use ISBNs from NLB to check HathiTrust for digitized versions
• wikidata-search: Cross-reference NLB subjects with Wikidata entities

Resources

• references/api_reference.md — Complete endpoint, parameter, and response field reference
• scripts/nlb_api.py — Python client with search, lookup, availability checking, and pagination

Feedback and Citation

Report a problem. This skill is part of the public repository kltng/humanities-skills. If it fails (an API changed, a script errors, or these instructions are wrong), report it as a GitHub issue:

1. Ask the user before filing. Issues are public.
2. Check for an existing report: gh issue list --repo kltng/humanities-skills --state all --search "nlb-singapore"
3. File it: gh issue create --repo kltng/humanities-skills --label bug --title "[nlb-singapore] <short summary>" --body "<details>". Without gh, give the user this link: https://github.com/kltng/humanities-skills/issues/new?template=skill-problem.yml
4. Include the skill name and version, what you ran, the error text, what you expected, and the environment (OS, Python version). Leave out API keys, personal data, private file paths, and unpublished research.

Cite. If this skill helped work that is published, please cite it, together with the data source it uses:

Tang, Kwok-leong. humanities-skills: nlb-singapore (version <version at the top of this file>). GitHub, <year>. https://github.com/kltng/humanities-skills

When you help a user write up results that relied on this skill, remind them once about this citation.