webcat.hkpl.gov.hk APIwebcat.hkpl.gov.hk ↗
Search the HKPL catalog and retrieve real-time book availability, bibliographic details, and per-branch holdings across Hong Kong's public library system.
curl -X GET 'https://api.parse.bot/scraper/983d33d9-e887-4aed-994c-ae7876761f37/search_books?page=1&query=Harry+Potter' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for books in the HKPL catalog by keyword. Returns paginated results with basic metadata and availability summaries.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number of search results |
| queryrequired | string | Search keyword to find books in the catalog |
{
"type": "object",
"fields": {
"page": "integer current page number",
"books": "array of book objects with title, author, chamo_id, call_number, publisher, and availability_summary",
"total_results": "integer total number of matching results"
},
"sample": {
"data": {
"page": 1,
"books": [
{
"title": "Harry Potter : cinematic guide / [by Felicity Baker].",
"author": "Baker, Felicity",
"chamo_id": "chamo:3460423",
"publisher": "London : Scholastic Ltd., 2016.",
"call_number": "791.4375 BAK",
"availability_summary": "在館內架上可供外借的數目：312. 香港中央圖書館有 1 項在館內架上"
}
],
"total_results": 430
},
"status": "success"
}
}About the webcat.hkpl.gov.hk API
This API provides 2 endpoints for querying the Hong Kong Public Libraries catalog, returning book metadata and live branch-level availability. Use search_books to find titles by keyword with paginated results including author, call number, and availability summary, or use get_book_details to pull full bibliographic fields and holdings across every HKPL branch for a specific title.
Search the HKPL Catalog
The search_books endpoint accepts a query string and an optional page integer, returning an array of book objects alongside a total_results count. Each book in the results includes title, author, chamo_id, call_number, publisher, and an availability_summary — enough context to identify a title and assess whether it's worth drilling into. Pagination is handled through the page parameter, so you can walk through large result sets systematically.
Per-Branch Holdings and Bibliographic Detail
Once you have a chamo_id (formatted as chamo:<numeric_id>, e.g. chamo:3460417), pass it to get_book_details to retrieve the full record. The response includes a details object of key-value bibliographic fields (edition, language, subject headings, ISBN, and others as cataloged), plus a holdings array. Each holding entry specifies the branch location, call_number, status (e.g. available, on loan, reserved), and collection type. This makes it straightforward to check whether a specific branch currently has a copy on the shelf.
Identifiers and Cross-Referencing
The chamo_id is the internal HKPL catalog identifier and is returned in every search_books result, making it easy to chain the two endpoints. Search by keyword, collect chamo_id values from the results, then fetch granular holdings for each title of interest. The call_number field appears at both the record level and within individual holdings, which can differ if copies are shelved in specialized collections.
- Check real-time branch availability for a reading list before visiting a specific HKPL library
- Build a catalog search tool that surfaces Hong Kong library holdings alongside commercial book data
- Track which branches hold copies of a title using the per-holding
locationandstatusfields - Aggregate bibliographic metadata (publisher, call number, subject fields) for a corpus of titles held by HKPL
- Monitor availability changes for high-demand titles by polling
get_book_detailsholdings over time - Filter search results by
call_numberprefix to explore titles within a specific Dewey classification range
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does the Hong Kong Public Libraries system offer an official developer API?+
What does the `holdings` array in `get_book_details` actually tell me?+
holdings contains four fields: location (the branch name), call_number (as shelved at that branch), status (current loan or availability state), and collection (the sub-collection within that branch, such as adult lending or reference). If a title has copies at multiple branches, each copy appears as a separate entry, so a single book record can produce many holding rows.Can I search by ISBN, author name, or title specifically, rather than a general keyword?+
search_books endpoint takes a single query string with no dedicated field filters — there is no separate isbn, author, or title parameter. You can pass an ISBN or author name as the query string and the catalog will return matching results, but field-specific scoping is not exposed. You can fork this API on Parse and revise it to add a field-type filter parameter if your use case requires it.Does the API cover eBook or digital resource holdings?+
location, call_number, status, and collection fields oriented toward branch-shelved items. Digital or eBook records that HKPL may catalog are not currently distinguished as a separate resource type in the response. You can fork this API on Parse and revise it to add an endpoint that filters or flags digital-format holdings.How should I handle pagination when iterating through large search result sets?+
search_books response includes a total_results integer and a page integer indicating the current page. Increment the page parameter on successive requests to walk through results. There is no explicit per_page field in the response, so you will need to observe the size of the returned books array on the first request to infer page size before calculating the number of pages needed.