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?query=Harry+Potter' \ -H 'X-API-Key: $PARSE_API_KEY'
Search the HKPL catalog. Returns paginated results (10 per page) with basic metadata per book: title, author, chamo_id, call number, publisher, and a Chinese-language availability summary showing which branches hold copies on-shelf. Pagination advances via the page parameter (1-based, defaults to the first page); total_results reflects the full hit set and is 0 when nothing matches. By default the query is matched against any field; the field parameter restricts it to one catalog index such as ISBN, title, or author, which is the reliable way to look up a standard number because the all-fields index may not match exact ISBNs. When the exact query matches nothing and the catalog instead offers a spelling suggestion, this endpoint does NOT return the suggestion's hits: books is empty, total_results is 0, and suggested_query carries the catalog's proposed alternative term so the caller can decide whether to re-search with it; otherwise suggested_query is null. One request per call.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number of search results (1-based) |
| field | string | Catalog index to search; omit to match the term against any field. Values outside the set are rejected before any request. |
| queryrequired | string | Search term to match in the catalog (keywords, a title, an author name, or a standard number such as an ISBN when combined with the matching field). |
{
"type": "object",
"fields": {
"page": "integer current page number",
"books": "array of book objects with title, author, chamo_id, call_number, publisher, and availability_summary; empty when nothing matched the exact query",
"field": "string catalog index the search was run against (wire code of SearchField)",
"total_results": "integer total number of hits for the query (0 when nothing matched)",
"suggested_query": "string alternative term the catalog proposed when the exact query had no hits, otherwise null"
},
"sample": {
"data": {
"page": 1,
"books": [
{
"title": "崖上の波妞 = Ponyo on the cliff by the sea / [宮崎駿原作 ; 林子傑, 張文俊譯].",
"author": "宮崎駿 1941-",
"chamo_id": "chamo:2926141",
"publisher": "台北 : 台灣東販股份有限公司 ; 香港 : 萬里機構出版有限公司, 2009.",
"call_number": "992.7 3027",
"availability_summary": "在館內架上可供外借的數目：1804. 柴灣公共圖書館有 1 項在館內架上06. 大會堂公共圖書館有 1 項在館內架上"
}
],
"field": "isbn",
"total_results": 1,
"suggested_query": null
},
"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 | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. 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.