HIRA Specialty Opening-Date Cohort Radar

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

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.

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.

{
  "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

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:

{
  "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.

[
  {
    "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.

{
  "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:

{
  "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:

{
  "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

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

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.