# HIRA Specialty Opening Velocity Radar (`zinin/hira-specialty-opening-velocity-radar`) Actor

Unofficial, independent Actor; not affiliated with or endorsed by any named source publisher. Measure recent specialty opening declarations for time-sensitive market research.

- **URL**: https://apify.com/zinin/hira-specialty-opening-velocity-radar.md
- **Developed by:** [Tim Zinin](https://apify.com/zinin) (community)
- **Categories:** Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $25.50 / 1,000 hira specialty opening velocity radars

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## HIRA Specialty Opening-Date Cohort Radar

Compare survivorship-biased opening-date cohorts for time-sensitive market research.

![HIRA Specialty Opening-Date Cohort Radar buyer-input to evidence-to-decision diagram](https://raw.githubusercontent.com/TimmyZinin/apify-actor-assets/39b3eebd2b836f8315464db721642e3ee5847cbe/country20/hira-specialty-opening-velocity-radar/readme-hero.webp)

> **POST-REMEDIATION ACCEPTANCE EVIDENCE.** The bounded private canary `SLyhXKfOt1kZdfRCL` on immutable build `uusw4y8BlFzxOrbMz` delivered one paid signal and passed the signed runtime, source, billing, and COGS gates. Publication still requires the separate final-promotion checkpoint.

### What you get

HIRA Specialty Opening-Date Cohort Radar turns **Official current HIRA provider declaration file, Opening dates and segment fields, Pinned source receipt** into a bounded **survivorship-biased opening-date cohort comparison signal**. The useful product is not a country-labelled scrape. It is an evidence-to-action unit that can be scheduled, called from an API, or placed inside a monitored operations chain.

A successful row gives you Survivorship-biased opening-date cohort signal, Current versus prior cohort counts, Research, review or monitor. Its stable identity is based on **HIRA-OPENING-V3 namespace + canonical customer criteria + source vintage; source declarations retain encrypted provider ID + provider type + region + specialty + opening date**. Customer enrichment is limited to **customer objective, specialty, provider type, target region, explicit peer regions and opening-date cohort windows**. That separation matters: the source supplies observed facts; the buyer supplies criteria; the Actor supplies a reproducible rule application.

#### Product contract

- **Country/source context:** Republic of Korea; official-file.
- **Buyer:** Korean healthcare partnerships and territory research teams.
- **Primary decision noun:** survivorship-biased opening-date cohort comparison signal.
- **Billable event:** `opening-velocity-signal`.
- **Price per verified event:** $0.03.
- **Stable identity:** HIRA-OPENING-V3 namespace + canonical customer criteria + source vintage; source declarations retain encrypted provider ID + provider type + region + specialty + opening date.
- **Accepted private run:** `SLyhXKfOt1kZdfRCL` on build `uusw4y8BlFzxOrbMz`; Dataset rows 1; measured platform usage $0.007287; signed receipt `ed453c80f059f9035dbef047fe384273a1f7ee74ae5a03929ca32ce4e3ce2b53`.
- **Boundary:** Use the cohorts only to prioritize research. They are not net growth, closure-adjusted change, or historical snapshot comparisons; verify the provider before any commercial action.

#### The evidence chain

1. Validate the fixed official/public source route and response semantics.
2. Extract the named business identifiers and domain facts rather than arbitrary links or array positions.
3. Normalize buyer inputs: Specialty and region, Current and prior opening-date cohort windows, Cohort comparison thresholds.
4. Apply Validate declarations surviving in the pinned file, Compare adjacent opening-date cohorts, Apply cohort comparison thresholds.
5. Deliver Survivorship-biased opening-date cohort signal, Current versus prior cohort counts, Research, review or monitor with source receipt and disclaimer.
6. Link the Dataset delivery to the named PPE event and reconcile the run in OUTPUT.

The Actor does not convert an HTTP 200 response into a billable row by default. Source-specific type, marker, identity, row-count, unit, chronology, and completeness checks run before a decision can be delivered.

### Who uses it

The primary users are **Korean healthcare partnerships and territory research teams**. They usually have a concrete operational question: which item needs review, where an observed benchmark differs from policy, whether an official change deserves routing, or how to prioritize a bounded set without losing the supporting evidence.

#### Good fit

Use this Actor when the question can be expressed using Specialty and region, Current and prior opening-date cohort windows, Cohort comparison thresholds and the intended downstream states align with Survivorship-biased opening-date cohort signal, Current versus prior cohort counts, Research, review or monitor. A good workflow can name its human owner, evidence-retention rule, acceptable source period, and response to monitor/review/action outcomes.

#### Not a good fit

Do not use it as a general-purpose crawler, unrestricted lead database, professional opinion, safety guarantee, credit or eligibility decision, valuation, or proof of customer intent. Do not expand the fixed source boundary with arbitrary URLs, authenticated pages, personal accounts, or silent residential-proxy fallback.

### How to run

The workflow below belongs to execution: it maps the validated evidence chain into a run, reconciliation, and downstream automation.

![HIRA Specialty Opening-Date Cohort Radar automation and operational workflow diagram](https://raw.githubusercontent.com/TimmyZinin/apify-actor-assets/39b3eebd2b836f8315464db721642e3ee5847cbe/country20/hira-specialty-opening-velocity-radar/readme-workflow.webp)

#### Apify Console

1. Open the Actor Input tab.
2. Start from the bounded public example.
3. Replace the durable `requestId` or `monitorId` only when you are creating a genuinely new operation. Keep it unchanged for safe retries.
4. Review source-specific criteria, thresholds, and maximum total charge.
5. Run the Actor.
6. Read both Dataset and KVS `OUTPUT`. Dataset contains item evidence; OUTPUT contains delivery, payment, withholding, and replay truth.

#### Exact accepted private-canary input

The following input was read back from Apify KVS INPUT for accepted run `SLyhXKfOt1kZdfRCL`. Its canonical SHA-256 is `287d6674f67e8bf3d8bda07365afd9234f95ee948d69fbb42fd6d813a3b606f5`. IDs are synthetic campaign identities, not secrets.

```json
{
  "requestId": "c20_hira_specialty_opening_velocity_radar_55f6a1a74993",
  "targetRegion": {
    "province": "서울특별시",
    "district": "강남구"
  },
  "peerRegions": [
    {
      "province": "서울특별시",
      "district": "강남구"
    },
    {
      "province": "서울특별시",
      "district": "서초구"
    },
    {
      "province": "서울특별시",
      "district": "송파구"
    }
  ],
  "providerTypes": [
    "의원"
  ],
  "specialties": [
    "내과"
  ],
  "lookbackMonths": 24,
  "objective": "new_opening_outreach",
  "maxTotalChargeUsd": 1
}
```

#### API start

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/MFiN8xdfSeTyWUfv6/runs?token=$APIFY_TOKEN&waitForFinish=60" \
  -H 'content-type: application/json' \
  --data @input.json
```

A successful POST only proves that a run was created. Always follow the returned run ID, wait for a terminal state, then read Dataset and OUTPUT. Do not resend an ambiguous POST with a new identity.

#### Scheduling

Schedule according to the upstream publication cadence, not an arbitrary high-frequency polling loop. Retain the same monitor identity for change products. For one-shot decision products, use a new request identity only for a new buyer decision, criteria set, or source observation that should be independently billed.

### Pricing

This Actor uses Pay Per Event. The named result event is **`opening-velocity-signal`**, priced at **$0.03 per verified survivorship-biased opening-date cohort comparison signal**. Apify also applies its standard Actor start event according to the published pricing record and memory rules.

#### What is paid

A result event is charged only when the corresponding verified Dataset row or batch is delivered through linked PPE delivery. The runtime checks the live pricing contract before work, compares both the Apify platform cap and customer input cap, and refuses a result it cannot afford.

#### What is free at result level

- `error`
- `partial`
- `duplicate`
- `withheld`

Baselines for stateful monitors are free. A duplicate committed request is free. A pending/uncertain claim is withheld rather than re-delivered. Source validation failures, zero qualifying decisions, and budget stops do not masquerade as paid successes.

#### Accepted economics evidence

Accepted run `SLyhXKfOt1kZdfRCL` reports usage $0.007286942 and event counts:

```json
{
  "apify-actor-start": 1,
  "opening-velocity-signal": 1
}
```

This is evidence for that bounded canary, not a promise of future cost, speed, volume, margin, or savings. Source size, platform pricing, memory, and result count can change. Use `maxTotalChargeUsd` and monitor your own runs.

### Input contract

The Input schema rejects unknown fields. Every required field, enum, pattern, minimum, maximum, array bound, and description is part of the public contract. Do not rely on undocumented coercion.

| Field | Type | Required | Default | Bounds | Meaning |
| --- | --- | --- | --- | --- | --- |
| requestId | string | yes | none | pattern ^\[A-Za-z0-9\_-]{8,64}$ | Stable idempotency key without personal data. |
| targetRegion | object | yes | none | schema/type constraints only | Exact HIRA province and district labels. |
| peerRegions | array | yes | none | minItems 2; maxItems 20 | Two to 20 exact HIRA regions, including the target. |
| providerTypes | array | yes | none | minItems 1; maxItems 20 | One to 20 exact official 요양종별 labels. |
| specialties | array | yes | none | minItems 1; maxItems 20 | One to 20 exact official 표시과목명 labels. |
| lookbackMonths | integer | yes | 24 | min 1; max 120 | Adjacent opening-date cohort windows ending at the pinned source vintage; records must still be present in that one current file. |
| objective | string | yes | "new\_opening\_outreach" | enum new\_opening\_outreach | Prioritize research around survivorship-biased opening-date cohorts, not net provider growth. |
| maxTotalChargeUsd | number | yes | 1 | min 0.005; max 100 | Maximum total run charge in addition to the platform cap. |

#### Input design rules

- IDs are idempotency controls, not labels to randomize on every retry.
- Thresholds must express an operational policy that a reviewer understands.
- Customer facts remain customer facts; the Actor does not pretend the source verified them.
- Lists are bounded to protect source terms, runtime, Dataset size, and customer spend.
- `maxTotalChargeUsd` is a customer-side ceiling; the platform run option is authoritative when stricter.
- Secrets do not belong in source URLs, criteria text, Dataset fields, or README examples.

#### Validation before automation

Run one bounded Console example, inspect every Dataset field and OUTPUT, then create the schedule or webhook. If the decision would cause a consequential action, require human approval after the Actor and before the action.

### Real happy, partial, and failure output

#### Accepted Dataset example

The following is a representative Dataset example documenting the public row schema. Accepted run `SLyhXKfOt1kZdfRCL` produced one paid row; its exact Dataset SHA-256 is `6ec44749f2cf385c1a22af60023582172d53a252cf1330e3a177b79822bf08ce`.

```json
[
  {
    "schemaVersion": "1.0",
    "product": "hira-specialty-opening-velocity-radar",
    "country": "KR",
    "decision": "specialty opening velocity signal",
    "stableId": "HIRA-OPENING:2025-12:d2365bd917cac876cde7b799",
    "sourceVintage": "2025-12",
    "sourceRowCount": 104775,
    "uniqueProviderIdsObserved": 104257,
    "uniqueDeclarationIds": 104775,
    "duplicateDeclarationRows": 0,
    "openingDateParseRate": 1,
    "objective": "new_opening_outreach",
    "criteriaSha256": "d2365bd917cac876cde7b79915de406903affeb50f8ae5a67b0d40516ee33b79",
    "periodEnd": "2025-12-31",
    "cutoffDate": "2024-01-01",
    "target": {
      "province": "서울특별시",
      "district": "강남구",
      "regionKey": "서울특별시|강남구",
      "specialtyDeclarationCount": 100,
      "recentOpeningDeclarations": 12,
      "annualizedOpeningDeclarations": 6,
      "recentOpeningDeclarationShare": 0.12,
      "volumePercentile": 100,
      "scarcityPercentile": 0,
      "openingVelocityPercentile": 100,
      "score": 100,
      "action": "prioritize_recent_opening_research"
    },
    "peerBenchmarks": [
      {
        "province": "서울특별시",
        "district": "강남구",
        "regionKey": "서울특별시|강남구",
        "specialtyDeclarationCount": 100,
        "recentOpeningDeclarations": 12,
        "annualizedOpeningDeclarations": 6,
        "recentOpeningDeclarationShare": 0.12,
        "volumePercentile": 100,
        "scarcityPercentile": 0,
        "openingVelocityPercentile": 100,
        "score": 100
      },
      {
        "province": "서울특별시",
        "district": "송파구",
        "regionKey": "서울특별시|송파구",
        "specialtyDeclarationCount": 84,
        "recentOpeningDeclarations": 7,
        "annualizedOpeningDeclarations": 3.5,
        "recentOpeningDeclarationShare": 0.08333333,
        "volumePercentile": 50,
        "scarcityPercentile": 50,
        "openingVelocityPercentile": 50,
        "score": 50
      },
      {
        "province": "서울특별시",
        "district": "서초구",
        "regionKey": "서울특별시|서초구",
        "specialtyDeclarationCount": 71,
        "recentOpeningDeclarations": 6,
        "annualizedOpeningDeclarations": 3,
        "recentOpeningDeclarationShare": 0.08450704,
        "volumePercentile": 0,
        "scarcityPercentile": 100,
        "openingVelocityPercentile": 0,
        "score": 0
      }
    ],
    "shortlist": [
      {
        "province": "서울특별시",
        "district": "강남구",
        "regionKey": "서울특별시|강남구",
        "specialtyDeclarationCount": 100,
        "recentOpeningDeclarations": 12,
        "annualizedOpeningDeclarations": 6,
        "recentOpeningDeclarationShare": 0.12,
        "volumePercentile": 100,
        "scarcityPercentile": 0,
        "openingVelocityPercentile": 100,
        "score": 100
      },
      {
        "province": "서울특별시",
        "district": "송파구",
        "regionKey": "서울특별시|송파구",
        "specialtyDeclarationCount": 84,
        "recentOpeningDeclarations": 7,
        "annualizedOpeningDeclarations": 3.5,
        "recentOpeningDeclarationShare": 0.08333333,
        "volumePercentile": 50,
        "scarcityPercentile": 50,
        "openingVelocityPercentile": 50,
        "score": 50
      },
      {
        "province": "서울특별시",
        "district": "서초구",
        "regionKey": "서울특별시|서초구",
        "specialtyDeclarationCount": 71,
        "recentOpeningDeclarations": 6,
        "annualizedOpeningDeclarations": 3,
        "recentOpeningDeclarationShare": 0.08450704,
        "volumePercentile": 0,
        "scarcityPercentile": 100,
        "openingVelocityPercentile": 0,
        "score": 0
      }
    ],
    "confidence": "medium",
    "source": {
      "url": "https://www.data.go.kr/data/15051057/fileData.do",
      "attachmentId": "FILE_000000003601192",
      "route": "github-cache:TimmyZinin/hira-open-data-cache@bulk-2025-12",
      "bytes": 20252483,
      "sha256": "bb10d7930007af3190cc595fa3e90d353e46f05c1ec7b617ac1d094abea10723",
      "vintage": "2025-12",
      "retrievedAt": "2026-08-14T08:29:51.106Z"
    },
    "attribution": "Source: Health Insurance Review & Assessment Service (HIRA) via data.go.kr, KOGL Type 1.",
    "sourceCaveat": "HIRA states that provider data is based on provider declarations and may contain reporting errors or omissions; this signal is not regulatory certification or HIRA endorsement.",
    "methodologyCaveat": "Opening velocity counts provider-specialty declarations, not certified unique clinics or verified sales leads. Confirm the organization, demand, regulation, and outreach eligibility before acting.",
    "baseline": false,
    "billable": true
  }
]
```

#### Accepted terminal OUTPUT

This exact KVS OUTPUT was captured from the same accepted run; OUTPUT SHA-256 is `e00cdbbebf7a8ed95c5bf5cd1538ef273fbe2ea59949772a678a6818baab3d0f`.

```json
{
  "schemaVersion": "1.0",
  "status": "ok",
  "product": "hira-specialty-opening-velocity-radar",
  "delivered": 1,
  "paid": 1,
  "withheld": 0,
  "replaySafe": false,
  "publicationAuthorized": false,
  "finishedAt": "2026-08-14T08:30:36.226Z"
}
```

#### Partial contract shape

The runtime uses a free partial/withheld state when source completeness or delivery certainty is insufficient. This is a contract illustration, not claimed as an additional accepted run:

```json
{
  "schemaVersion": "1.0",
  "status": "partial",
  "product": "hira-specialty-opening-velocity-radar",
  "delivered": 0,
  "paid": 0,
  "withheld": 1,
  "replaySafe": false,
  "publicationAuthorized": false,
  "error": "source-specific validation stopped before verified delivery"
}
```

#### Failure contract shape

A bounded source or input failure is free at result level and never claims replay safety unless the runtime can prove it. This is a contract illustration:

```json
{
  "schemaVersion": "1.0",
  "status": "failed",
  "product": "hira-specialty-opening-velocity-radar",
  "delivered": 0,
  "paid": 0,
  "withheld": 0,
  "replaySafe": false,
  "publicationAuthorized": false,
  "error": "bounded source or input contract failure"
}
```

#### Reading terminal truth

- `delivered` must reconcile to Dataset rows.
- `paid` must reconcile to billable rows and the named event count.
- `withheld` signals that a row or operation was intentionally not repeated or delivered.
- `replaySafe` is true only for states the runtime can safely replay.
- `publicationAuthorized` is a release boundary, not a customer decision field.

### Field dictionary

#### Dataset

| Dataset field | Type | Operational meaning |
| --- | --- | --- |
| schemaVersion | string | Verified schemaVersion field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| product | string | Verified product field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| country | string | Verified country field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| decision | string | Verified decision field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| stableId | string | Verified stableId field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| sourceVintage | string | Verified sourceVintage field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| sourceRowCount | integer | Verified sourceRowCount field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| uniqueProviderIdsObserved | integer | Verified uniqueProviderIdsObserved field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| uniqueDeclarationIds | integer | Verified uniqueDeclarationIds field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| duplicateDeclarationRows | integer | Verified duplicateDeclarationRows field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| openingDateParseRate | number | Verified openingDateParseRate field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| objective | string | Verified objective field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| criteriaSha256 | string | Verified criteriaSha256 field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| periodEnd | string | Verified periodEnd field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| cutoffDate | string | Verified cutoffDate field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| priorCutoffDate | string | Verified priorCutoffDate field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| comparisonWindowMonths | integer | Verified comparisonWindowMonths field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| cohortBasis | string | Verified cohortBasis field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| notMeasured | array | Verified notMeasured field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| target | object | Verified target field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| peerBenchmarks | array | Verified peerBenchmarks field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| shortlist | array | Verified shortlist field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| confidence | string | Verified confidence field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| source | object | Verified source field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| attribution | string | Verified attribution field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| sourceCaveat | string | Verified sourceCaveat field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| methodologyCaveat | string | Verified methodologyCaveat field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| baseline | boolean | Verified baseline field in the accepted survivorship-biased opening-date cohort comparison signal row. |
| billable | boolean | Verified billable field in the accepted survivorship-biased opening-date cohort comparison signal row. |

#### Cross-product evidence fields

- **stableId** — domain identity derived from HIRA-OPENING-V3 namespace + canonical customer criteria + source vintage; source declarations retain encrypted provider ID + provider type + region + specialty + opening date; never a source array position.
- **source** — route, official IDs, period, byte/hash receipt, and retrieval time needed to audit the observation.
- **action** — the explicit routing result after applying buyer criteria to validated source facts.
- **criteriaSha256** — integrity fingerprint for normalized criteria; it is not a score.
- **baseline** — true only when a stateful monitor stores its first comparable snapshot for free.
- **billable** — true only when the row is eligible for the named linked delivery event.
- **attribution/disclaimer** — reuse credit and decision boundary that downstream systems should retain.

#### KVS OUTPUT

OUTPUT is the authoritative run-level receipt. It should be stored beside a workflow execution ID. It does not replace Dataset evidence, and Dataset evidence does not replace OUTPUT billing/replay truth. A robust integration rejects mismatched counts rather than guessing.

### Evidence and boundaries

#### Evidence preserved

The adapter retains the official identity and observed facts required for survivorship-biased opening-date cohort comparison signal. It also retains source URL/route, source period or publication identity, retrieval timestamp, response or release hash, normalized criteria fingerprint, and the exact action reason exposed by the domain adapter.

#### Semantic source validation

The source contract is **official-file** on route **github-cache:TimmyZinin/hira-open-data-cache@bulk-2025-12**, a verbatim public mirror of the pinned bulk file (open KOGL-licensed dataset, republished with attribution on GitHub Releases), sha256-verified against the contract before every use, with an unchanged **apify-datacenter** fetch of the original data.go.kr endpoint as fallback when the mirror is unavailable or fails verification. Validation is domain-specific: expected content type, fixed host/path or official catalog relationship, required identifiers, bounded bytes, structural fields, chronology, duplicate identity, and semantic error bodies are checked before delivery. An upstream login page, generic app shell, consent page, empty report, or malformed file must fail closed.

#### Security boundary

Network destinations are fixed to approved official/public hosts. Redirects are either disabled or independently revalidated. DNS and address checks reject local/private targets. Responses are streamed under declared byte limits. Buyer input cannot turn the Actor into SSRF, an open proxy, an authenticated crawler, or a credential relay.

#### Interpretation boundary

Use the cohorts only to prioritize research. They are not net growth, closure-adjusted change, or historical snapshot comparisons; verify the provider before any commercial action. The Actor reports observed evidence plus a deterministic rule application. It does not prove causality, future behavior, legal status beyond the cited publication, quality, solvency, safety, intent, or permission to contact.

#### Privacy boundary

Submit only operationally necessary criteria. Do not provide passwords, access tokens, private correspondence, sensitive personal data, or arbitrary URLs. If the official source exposes public entity facts, retain them only for the documented decision and according to your own legal basis and retention policy.

### Decision routing

#### Route states

- **Monitor** — evidence is valid but does not cross a review threshold. Store the receipt and wait for the next comparable observation.
- **Review** — evidence crosses a bounded review rule or needs professional confirmation. Create a queue item with source and factors.
- **Action-oriented state** — the explicit rule crosses the action threshold. Require the owner and safeguards appropriate to the domain.
- **Partial** — source completeness is insufficient. Do not interpret missing rows as negative evidence.
- **Withheld/uncertain** — the runtime will not repeat a potentially delivered item. Reconcile by run ID.
- **Failed** — no decision claim was made. Fix the input/source boundary or wait for the official source; do not randomize the request ID.

#### Routing record

Every downstream task should carry stableId, action, factors, source identity, reference period, criteria fingerprint, run ID, Dataset ID, and a link to OUTPUT. This makes it possible to answer “what did we know, which rule ran, and what happened to delivery?” without reconstructing the workflow from logs.

#### Human review

Human review is not a vague disclaimer. Define the reviewer role, response time, evidence they must inspect, allowed dispositions, and whether a changed source observation is required before action. Keep the reviewer decision separate from the Actor row.

### Commercial playbooks

#### 1. Qualification desk

Use Specialty and region, Current and prior opening-date cohort windows, Cohort comparison thresholds to decide which records deserve analyst time. Preserve the cited source fields beside the action so a reviewer can reproduce why the row was routed.

#### 2. Scheduled monitor

Run on the cadence of the official source, keep the same durable request or monitor identity where the product supports state, and send only verified changes or decision rows downstream.

#### 3. CRM enrichment

Map Survivorship-biased opening-date cohort signal, Current versus prior cohort counts, Research, review or monitor into evidence fields instead of overwriting customer master data. Keep the source URL, observation period, stable ID, and disclaimer visible.

#### 4. Operational review queue

Treat “review” as a routing state. Assign an owner, retain the evidence receipt, confirm the current source state, and record the human disposition outside the Actor.

#### 5. Portfolio comparison

Run the same bounded criteria over comparable customer items. Compare factors and source periods, not a bare score detached from its evidence and limitations.

#### 6. Audit export

Export Dataset rows and the KVS OUTPUT receipt together. The Dataset explains each delivered item; OUTPUT explains paid, free, withheld, partial, and replay state for the run.

### Integration recipes

#### JavaScript client

```js
const actorId = 'MFiN8xdfSeTyWUfv6';
const input = {
  "requestId": "c20_hira_specialty_opening_velocity_radar_e6a81a54d994",
  "targetRegion": {
    "province": "서울특별시",
    "district": "강남구"
  },
  "peerRegions": [
    {
      "province": "서울특별시",
      "district": "강남구"
    },
    {
      "province": "서울특별시",
      "district": "서초구"
    },
    {
      "province": "서울특별시",
      "district": "송파구"
    }
  ],
  "providerTypes": [
    "의원"
  ],
  "specialties": [
    "내과"
  ],
  "lookbackMonths": 24,
  "objective": "new_opening_outreach",
  "maxTotalChargeUsd": 1
};
const start = await fetch(`https://api.apify.com/v2/acts/${actorId}/runs?waitForFinish=60&token=${process.env.APIFY_TOKEN}`, {
  method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input),
});
const run = (await start.json()).data;
if (!['SUCCEEDED', 'FAILED', 'ABORTED', 'TIMED-OUT'].includes(run.status)) throw new Error('poll run to terminal');
const [rowsResponse, outputResponse] = await Promise.all([
  fetch(`https://api.apify.com/v2/datasets/${run.defaultDatasetId}/items?clean=true&token=${process.env.APIFY_TOKEN}`),
  fetch(`https://api.apify.com/v2/key-value-stores/${run.defaultKeyValueStoreId}/records/OUTPUT?token=${process.env.APIFY_TOKEN}`),
]);
const rows = await rowsResponse.json();
const terminal = await outputResponse.json();
if (terminal.delivered !== rows.length) throw new Error('delivery reconciliation failed');
```

#### Python client

```python
import os, requests
actor_id = 'MFiN8xdfSeTyWUfv6'
input_payload = {
  "requestId": "c20_hira_specialty_opening_velocity_radar_e6a81a54d994",
  "targetRegion": {
    "province": "서울특별시",
    "district": "강남구"
  },
  "peerRegions": [
    {
      "province": "서울특별시",
      "district": "강남구"
    },
    {
      "province": "서울특별시",
      "district": "서초구"
    },
    {
      "province": "서울특별시",
      "district": "송파구"
    }
  ],
  "providerTypes": [
    "의원"
  ],
  "specialties": [
    "내과"
  ],
  "lookbackMonths": 24,
  "objective": "new_opening_outreach",
  "maxTotalChargeUsd": 1
}
run = requests.post(
    f'https://api.apify.com/v2/acts/{actor_id}/runs',
    params={'token': os.environ['APIFY_TOKEN'], 'waitForFinish': 60},
    json=input_payload, timeout=75,
).json()['data']
rows = requests.get(
    f"https://api.apify.com/v2/datasets/{run['defaultDatasetId']}/items",
    params={'token': os.environ['APIFY_TOKEN'], 'clean': 'true'}, timeout=30,
).json()
output = requests.get(
    f"https://api.apify.com/v2/key-value-stores/{run['defaultKeyValueStoreId']}/records/OUTPUT",
    params={'token': os.environ['APIFY_TOKEN']}, timeout=30,
).json()
assert output['delivered'] == len(rows)
```

#### n8n

1. **Schedule Trigger** or Webhook receives the bounded buyer criteria.
2. **HTTP Request** starts the Actor with an Apify credential stored in n8n credentials, never in the input URL committed to source control.
3. **Wait/Poll** follows the returned run ID to terminal state.
4. Two **HTTP Request** nodes read Dataset and OUTPUT.
5. **Code** checks delivered/paid counts, allowed status, stableId, source period, and action.
6. **Switch** routes monitor, review, action, partial, withheld, and failed states separately.
7. Destination nodes write to Sheets/CRM/ticketing while preserving evidence and disclaimer.

#### Google Sheets

Use one sheet for decision rows keyed by `stableId`, and a second run ledger keyed by `runId`. Recommended decision columns are source period, action, factors, source URL, criteria hash, observation time, and reviewer disposition. Recommended run columns are Dataset ID, delivered, paid, withheld, replaySafe, usage, and OUTPUT link.

#### CRM

Create an evidence/enrichment activity rather than replacing the CRM’s authoritative legal name, valuation, risk status, or account owner. Store the source identity and observation date. Route review/action states into a task with a named owner; leave monitor states as timeline evidence unless policy says otherwise.

#### Webhooks

Use an Apify run-succeeded webhook only as a wake-up signal. Fetch the terminal run, Dataset, and OUTPUT using their IDs, then reconcile. Do not trust arbitrary webhook body fields as the complete decision record, and make the receiver idempotent by run ID plus stableId.

### Operating guide

#### Before launch

- Confirm the official source route and reuse boundary remain current.
- Validate public Input schema descriptions and bounded defaults in the rendered Console.
- Run the small example and retain INPUT, Dataset, OUTPUT, build ID, pricing events, and usage.
- Confirm the source observation period is appropriate for the buyer decision.
- Define downstream owners and allowed dispositions.
- Set a customer cap and monitor actual spend.

#### Daily or scheduled operation

Check terminal status, Dataset count, OUTPUT reconciliation, source period, source hash change, partial flags, and review backlog. When the source has not published a new comparable period, do not fabricate change by rotating an identity. When a source revision changes a prior period, keep both the revision evidence and customer decision history.

#### Incident runbook

1. Stop automatic consequential actions while preserving monitor collection.
2. Identify the exact run, build, INPUT hash, Dataset hash, OUTPUT hash, and source receipt.
3. Determine whether the fault is input validation, source availability, semantic source drift, budget, linked delivery, or downstream mapping.
4. For an ambiguous POST or pending delivery, reconcile the existing run; never start a replacement with a new identity merely to obtain a clean status.
5. For source schema drift, update source-specific fixtures and validators, build a new immutable candidate, and rerun acceptance.
6. Restore automation only after a bounded canary and replay test prove the corrected path.

#### Change management

Treat input/output schemas, identity basis, decision rules, source URLs, legal boundary, and pricing noun as product contracts. Version changes deliberately. A README-only edit must not silently redefine runtime behavior, and a runtime change must update examples and field dictionary before release.

#### Quality checklist

For this product the release gate verifies: Specialty and region, Current and prior opening-date cohort windows, Cohort comparison thresholds; Official current HIRA provider declaration file, Opening dates and segment fields, Pinned source receipt; Validate declarations surviving in the pinned file, Compare adjacent opening-date cohorts, Apply cohort comparison thresholds; and Survivorship-biased opening-date cohort signal, Current versus prior cohort counts, Research, review or monitor. It also checks private candidate provenance, exact build source, PPE configuration, bounded accepted run, free error/duplicate behavior, replay and concurrency safety, two immutable diagrams, README length/sections, rendered Store/Input pages, and all-20 wave balance.

### FAQ

#### Is this a generic country scraper?

No. It is the HIRA Specialty Opening-Date Cohort Radar, designed around survivorship-biased opening-date cohort comparison signal and the named official/public source contract. Geography explains the source, not the product category.

#### Does it crawl accounts or private pages?

No. The implementation is pinned to the source routes documented below. It does not log in, bypass an account, collect messages, or broaden itself to arbitrary customer URLs.

#### Can a customer supply an arbitrary URL?

No. Source hosts and paths are fixed or derived only through bounded official catalog routes. Buyer inputs select criteria and customer facts; they do not turn the Actor into an open proxy.

#### What is the primary billable unit?

The single pricing noun is **survivorship-biased opening-date cohort comparison signal**, charged through the named event `opening-velocity-signal` only when a verified billable Dataset item is linked to delivery.

#### Are errors charged as result events?

No. The contract identifies error, partial, duplicate, withheld as free result states. Apify platform start charges are separate and visible in the run pricing record.

#### What makes an ID stable?

The identity basis is: HIRA-OPENING-V3 namespace + canonical customer criteria + source vintage; source declarations retain encrypted provider ID + provider type + region + specialty + opening date. Mutable ranking, source position, or array offset is not treated as the business identity.

#### Is the score a random hash?

No. The production adapter parses named source fields and applies the explicit rules described in the output. Hashes are used for integrity, criteria fingerprints, and idempotency—not as business scores.

#### Can I treat an action as a professional conclusion?

No. Use the cohorts only to prioritize research. They are not net growth, closure-adjusted change, or historical snapshot comparisons; verify the provider before any commercial action.

#### How fresh is the data?

Freshness follows the official source and the observation/reference period in the Dataset row. The Actor does not invent a real-time claim when the upstream source is monthly, daily, or a published report.

#### Why preserve a source hash?

It proves which response or release was used and helps distinguish a changed upstream publication from a changed customer criterion. It does not replace the official source URL.

#### What happens on an upstream HTML challenge or error page?

Semantic validators reject the body before decision delivery. A 2xx status alone is not enough; required columns, identifiers, counts, content type, and source-specific markers must pass.

#### Does this require a local proxy?

No, not on the primary path. The accepted product route is the route in the contract: **github-cache:TimmyZinin/hira-open-data-cache@bulk-2025-12**, a verbatim public GitHub Releases mirror of the pinned bulk file, sha256-verified against the contract before use. If that mirror is unavailable or fails verification, the Actor falls back to the original **apify-datacenter** fetch of the same pinned data.go.kr file — never residential, never a silent or undeclared route.

#### How do retries work?

Reuse the same durable request/monitor identity. A committed request returns a free duplicate state; an uncertain pending delivery is withheld rather than repeated blindly. Inspect OUTPUT before authorizing any new request ID.

#### Can two concurrent runs double-deliver?

The runtime claims a tenant-scoped durable operation before linked delivery. A competing claim is returned as duplicate or withheld. The release gate separately stress-tests this behavior before publication.

#### Where is the authoritative run summary?

KVS record OUTPUT. Dataset rows carry item evidence; OUTPUT carries run-wide counts and replay safety. Store both when the workflow needs auditability.

#### Can I remove the disclaimer downstream?

Do not. Preserve attribution, the product disclaimer, source URL, reference period, and the human-review boundary in any CRM, report, or webhook payload.

#### Does the Actor predict the future?

No. It converts observed official/public evidence and customer criteria into an operational benchmark, monitor, or routing decision. It is not marketed as a forecast unless the product contract explicitly says so—which this one does not.

#### Does it contain personal data?

The product scope is limited to the documented public/aggregate fields and buyer-supplied operational criteria. Do not submit secrets or unnecessary personal data. Review Dataset examples before connecting another system.

#### How should I choose thresholds?

Start with the bounded public example, compare decisions against your own review policy, and change one rule at a time. The Actor exposes Survivorship-biased opening-date cohort signal, Current versus prior cohort counts, Research, review or monitor so threshold effects remain visible.

#### Why is publicationAuthorized false in canary OUTPUT?

Private acceptance runs deliberately hard-code the publication boundary. Public release is a separate all-20 transaction after source, billing, replay, visual, Store, and anonymous-page gates pass.

#### What sources are contacted?

`https://www.data.go.kr/data/15051057/fileData.do`, `https://www.data.go.kr/cmm/cmm/fileDownload.do?atchFileId=FILE_000000003601192&fileDetailSn=1&insertDataPrcus=N`

#### Can n8n or Make call it?

Yes. Start a run through the Apify API, wait for terminal status, read Dataset items and OUTPUT, then branch on explicit action/status fields. Never branch only on HTTP 201 from the run-start request.

#### Can I write results to Google Sheets?

Yes. Use stableId as the row key, source reference period as the observation column, and action as a review-routing column. Keep OUTPUT in a separate run ledger sheet.

#### Can I push into a CRM automatically?

Yes, but write evidence into a dedicated enrichment object or timeline entry. Do not silently overwrite authoritative customer fields, and require human review for consequential actions.

#### What should support requests include?

Provide the Actor name, run ID, build number, OUTPUT, source receipt/hash, and a redacted input. Never paste the Apify token or another secret.

#### How do I audit a threshold change?

Keep the old and new normalized criteria, their fingerprints, the same comparable source period, and both decision rows. Explain which of Specialty and region, Current and prior opening-date cohort windows, Cohort comparison thresholds changed and why the new policy is authorized.

#### Can I compare different source periods?

Yes, when the domain adapter exposes comparable periods and units. Keep revision and seasonality caveats visible. Never compare ranks or scores across changed definitions without documenting the break.

#### What if the official source revises history?

Retain both source hashes and observation timestamps. A revision is new evidence, not proof that the earlier Actor run was defective. Re-run only under an authorized identity/revision policy.

#### What if the source removes a record?

A stateful product reports removal only when the source contract and completeness checks can distinguish a real removal from a partial response. Otherwise the run is partial or withheld.

#### Should I schedule it every minute?

Usually no. Match the upstream publication cadence and buyer response time. Excess polling adds cost and load without creating fresher official evidence.

### Sources and rights

#### Exact source routes

- https://www.data.go.kr/data/15051057/fileData.do
- https://www.data.go.kr/cmm/cmm/fileDownload.do?atchFileId=FILE\_000000003601192\&fileDetailSn=1\&insertDataPrcus=N
- https://github.com/TimmyZinin/hira-open-data-cache/releases/download/bulk-2025-12/hira\_bulk.bin (verbatim mirror of the file above, attribution preserved)

The implementation uses only the route family defined in `contract.json`: kind `official-file`, host `www.data.go.kr`, origin route `apify-datacenter`, primary route `github-cache:TimmyZinin/hira-open-data-cache@bulk-2025-12` (a verbatim public mirror of that exact origin file, sha256-pinned, republished under the source's KOGL Type 1 attribution licence). Source metadata, licence/reuse labels, attribution, and product-specific exclusions must be rechecked at production acceptance because public terms and endpoints can change.

#### Reuse and attribution

This is an unofficial Actor, not affiliated with or endorsed by any named source publisher. Preserve emitted attribution and official disclaimers. Do not broaden reuse rights to excluded content, accounts, listings, messages, or customer data.

#### 한국어 출처 및 검색 용어

**Search/source terms:** 공공데이터, 출처 근거, 의사결정 신호, 모니터링, 검토, 조치.

출처 기록은 근거로 보존되며 결과는 법률·금융·의료 판단이나 성과 보장이 아닙니다.

The local-language labels help operators find and verify the official source. The binding product contract, input schema, field dictionary, pricing noun, and safety boundary remain the English Store documentation above.

#### Product-specific boundary

- Source evidence: Official current HIRA provider declaration file; Opening dates and segment fields; Pinned source receipt.
- Transformation: Validate declarations surviving in the pinned file; Compare adjacent opening-date cohorts; Apply cohort comparison thresholds.
- Delivered fields: Survivorship-biased opening-date cohort signal; Current versus prior cohort counts; Research, review or monitor.
- Required interpretation: Use the cohorts only to prioritize research. They are not net growth, closure-adjusted change, or historical snapshot comparisons; verify the provider before any commercial action.
- Excluded expansion: arbitrary URLs, account access, messages, private datasets, silent proxy fallback, and claims not supported by cited evidence.

#### Support evidence

When reporting a source or decision issue, provide run ID `SLyhXKfOt1kZdfRCL`-style identifiers, build number, redacted INPUT, Dataset and OUTPUT hashes, source period and source receipt. Never send an Apify token, password, private correspondence, or unnecessary personal data.

# Actor input Schema

## `requestId` (type: `string`):

Stable idempotency key without personal data.

## `targetRegion` (type: `object`):

Exact HIRA province and district labels.

## `peerRegions` (type: `array`):

Two to 20 exact HIRA regions, including the target.

## `providerTypes` (type: `array`):

One to 20 exact official 요양종별 labels.

## `specialties` (type: `array`):

One to 20 exact official 표시과목명 labels.

## `lookbackMonths` (type: `integer`):

Adjacent opening-date cohort windows ending at the pinned source vintage; records must still be present in that one current file.

## `objective` (type: `string`):

Prioritize research around survivorship-biased opening-date cohorts, not net provider growth.

## `maxTotalChargeUsd` (type: `number`):

Maximum total run charge in addition to the platform cap.

## Actor input object example

```json
{
  "requestId": "hira_opening_demo_01",
  "targetRegion": {
    "province": "서울특별시",
    "district": "강남구"
  },
  "peerRegions": [
    {
      "province": "서울특별시",
      "district": "강남구"
    },
    {
      "province": "서울특별시",
      "district": "서초구"
    },
    {
      "province": "서울특별시",
      "district": "송파구"
    }
  ],
  "providerTypes": [
    "의원"
  ],
  "specialties": [
    "내과"
  ],
  "lookbackMonths": 24,
  "objective": "new_opening_outreach",
  "maxTotalChargeUsd": 1
}
```

# Actor output Schema

## `results` (type: `string`):

Validated paid decisions and explicit free baseline/error rows.

## `OUTPUT` (type: `string`):

Source hash, delivery, billing and replay-safety counters.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "requestId": "hira_opening_demo_01",
    "targetRegion": {
        "province": "서울특별시",
        "district": "강남구"
    },
    "peerRegions": [
        {
            "province": "서울특별시",
            "district": "강남구"
        },
        {
            "province": "서울특별시",
            "district": "서초구"
        },
        {
            "province": "서울특별시",
            "district": "송파구"
        }
    ],
    "providerTypes": [
        "의원"
    ],
    "specialties": [
        "내과"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("zinin/hira-specialty-opening-velocity-radar").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "requestId": "hira_opening_demo_01",
    "targetRegion": {
        "province": "서울특별시",
        "district": "강남구",
    },
    "peerRegions": [
        {
            "province": "서울특별시",
            "district": "강남구",
        },
        {
            "province": "서울특별시",
            "district": "서초구",
        },
        {
            "province": "서울특별시",
            "district": "송파구",
        },
    ],
    "providerTypes": ["의원"],
    "specialties": ["내과"],
}

# Run the Actor and wait for it to finish
run = client.actor("zinin/hira-specialty-opening-velocity-radar").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "requestId": "hira_opening_demo_01",
  "targetRegion": {
    "province": "서울특별시",
    "district": "강남구"
  },
  "peerRegions": [
    {
      "province": "서울특별시",
      "district": "강남구"
    },
    {
      "province": "서울특별시",
      "district": "서초구"
    },
    {
      "province": "서울특별시",
      "district": "송파구"
    }
  ],
  "providerTypes": [
    "의원"
  ],
  "specialties": [
    "내과"
  ]
}' |
apify call zinin/hira-specialty-opening-velocity-radar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,zinin/hira-specialty-opening-velocity-radar"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MFiN8xdfSeTyWUfv6/builds/do0EeLk2R3fv4IRKk/openapi.json