hira-hospital_skill

Overview

This skill connects to the HIRA (Health Insurance Review & Assessment Service) hospital information APIs to search hospitals and fetch detailed institution data. It supports list searches by name, region, type, or department and parallel detail lookups for hours, departments, and transport. Authentication uses a local API key file and the service targets data.go.kr endpoints.

How this skill works

The skill calls the hospInfoServicev2 endpoint for list searches and MadmDtlInfoService2.7 for detailed institution data. Search inputs are parsed into region, hospital name, and department intent; a quick search returns a compact hospital list and an optional detail lookup fetches hours, departments, address, phone, and transport. Shell scripts wrap the API calls for batch or scripted usage and output structured results for presentation.

When to use it

• Find nearby clinics or hospitals by specialty (e.g., ENT, pediatrics, dermatology).
• Get detailed operating hours, departments, and transport info for a specific hospital.
• Support automated workflows that need up-to-date public hospital registry data.
• Enrich search results with official registry identifiers for downstream lookups.
• Scripted or batch retrieval of hospital lists for archiving or data pipelines.

Best practices

• Store the data.go.kr API key in ~/.config/data-go-kr/api_key and keep it readable only by the service user.
• Normalize user input into region + specialty tokens before calling the search API to improve match accuracy.
• Use the list search first and only call the detail endpoint for selected institutions to minimize API usage.
• Rate-limit parallel detail lookups and handle partial failures gracefully; retry with exponential backoff.
• Cache stable hospital metadata (address, type) and refresh periodically rather than on every query.

Example use cases

• User asks “nearest ENT clinic” → parse region+department → run hospital_search.sh and return top matches.
• User requests a hospital’s hours → resolve institution code from a prior search and call hospital_detail.sh for hours and transport.
• Batch export of all hospitals in a region for an internal directory or archive.
• Backend enrichment: attach official hospital codes to user-submitted hospital names for consistent analytics.
• Notify users of changes: detect updated contact or address details and send alerts via a messaging connector.