Gov 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.
What is the Gov 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.
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'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace webcat-hkpl-gov-hk-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.hong_kong_public_libraries_hkpl_api import HKPL, Book, BookSummary, Holding
client = HKPL()
# Search for books about Harry Potter
for summary in client.booksummaries.search(query="Harry Potter", limit=5):
print(summary.title, summary.author, summary.chamo_id)
# Get full details for the first result
book = summary.details()
print(book.title, book.call_number)
# Explore holdings across library branches
for holding in book.holdings:
print(holding.location, holding.status, holding.collection)
Search the HKPL catalog by keyword. Returns paginated results (10 per page) with basic metadata per book: title, author, call number, publisher, and a Chinese-language availability summary showing which branches hold copies on-shelf. Pagination advances via the page parameter. The total_results count reflects the full hit set.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number of search results (1-based) |
| 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": "在館內架上可供外借的數目：2"
}
],
"total_results": 430
},
"status": "success"
}
}About the Gov API
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.
The Gov API is a managed, monitored endpoint for webcat.hkpl.gov.hk — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when webcat.hkpl.gov.hk changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official webcat.hkpl.gov.hk API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- 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 | 100 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.