# Hlídač Státu + ARES (`fetchfinch/hlidac-statu-ares-monitor`) Actor

Search and monitor Czech public contracts from Hlídač státu. Filter by buyer or supplier IČO, keywords, dates, value, and attention indicators; enrich each organization with official ARES company data. Export clean results or schedule monitoring for newly published contracts.

- **URL**: https://apify.com/fetchfinch/hlidac-statu-ares-monitor.md
- **Developed by:** [Fetch Finch](https://apify.com/fetchfinch) (community)
- **Categories:** Automation, Lead generation, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 ares-enriched contracts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## Hlídač Státu + ARES

Search the Czech Register of Contracts with **Hlídač státu intelligence**, enrich every identified buyer and supplier with the official **ARES business register**, or schedule the same search and receive only newly seen contracts.

The Actor uses official APIs directly. No browser or proxy is required. Results are designed for Apify tables, CSV/Excel export, automation, and downstream APIs.

### Why use this Actor?

- Search without learning Hlídač query syntax: buyer/supplier IČOs, keywords, dates, value, and contract categories have dedicated inputs.
- Receive one analysis-ready row per contract, including flat spreadsheet columns and complete nested source data.
- Enrich Czech entities with official ARES identity, address, legal-form code, tax ID, CZ-NACE activities, registration status, and source update date.
- Screen contracts using explainable Hlídač indicators: issues, missing price, procurement-threshold proximity, political connections, and invalid/superseded records.
- Monitor a saved search for new contracts without repeat output on every scheduled run.
- See explicit `coverage` on every result, including unavailable, partial, and not-requested enrichment.
- Retain source attribution and licence provenance in every record.

Attention indicators are screening aids. They are not fraud scores, allegations, legal conclusions, or substitutes for due diligence.

### No API key setup

Hlídač státu API access is managed by the Actor. Customers do not need to register on the Czech-language source website or provide a token. The managed credential is stored as an encrypted Actor secret and is never written to logs, datasets, monitor state, or run summaries.

The undocumented `firmy/GetDetailInfo` company-profile integration is disabled for public runs because the live endpoint currently returns an unexplained `403`. Contract collection and ARES enrichment do not depend on it.

### Guided contract search

```json
{
  "operation": "search",
  "searchTerms": "cloud",
  "buyerIcos": ["00007064"],
  "publishedFrom": "2026-01-01",
  "minValueCzk": 1000000,
  "categories": ["it"],
  "maxItems": 100,
  "aresEnrichment": true
}
```

Guided filters are combined with `AND`. Multiple values inside `buyerIcos`, `supplierIcos`, or `categories` are combined with `OR`. The generated query uses the documented `icoPlatce`, `icoPrijemce`, `zverejneno`, `podepsano`, `cena`, and `oblast` prefixes.

Expert users can add `advancedQuery`; it is ANDed with all guided filters. See the [official Hlídač search help](https://www.hlidacstatu.cz/napoveda) for its Elastic-style syntax.

### Attention-indicator filters

The following options filter normalized Hlídač results locally because Hlídač does not document stable search prefixes for them:

- `onlyWithIssues`
- `onlyMissingPrice`
- `onlyNearProcurementLimit`
- `onlyPoliticalLink`

When any is enabled, `scanLimit` controls how many source matches are inspected to find up to `maxItems` qualifying output records. Customers are charged only for emitted dataset results, not scanned or rejected source records.

### Monitor for new contracts

```json
{
  "operation": "monitor",
  "buyerIcos": ["00007064"],
  "categories": ["it"],
  "maxItems": 500,
  "monitorKey": "interior-ministry-it",
  "firstRunBehavior": "baseline_only",
  "aresEnrichment": true
}
```

Create an Apify Task, schedule it, and keep the same `monitorKey` and filters. The default first run stores a quiet baseline; later runs emit only previously unseen contract IDs as `NEW`. Choose `emit_current` to return the initial result set too.

This release deliberately promises **new-contract detection**, not complete amendment detection. A newest-first search cannot guarantee that an old amended contract will return to the result window. Updates observed inside the active window are counted in the run summary but are not emitted as guaranteed alerts.

Monitor configuration is fingerprinted. Changing its query, post-filters, scan window, enrichment, or attachment settings requires a new `monitorKey` or `resetState: true`. An unexpected empty result protects established state rather than silently replacing it.

Events use deterministic `eventId` values for downstream deduplication. Delivery is intentionally at-least-once.

Monitor state stores compact IDs, fingerprints, and timestamps rather than full enriched records. It retains the 20,000 most recently observed contracts to remain safely below key-value-store record limits during long-running schedules.

### Output

Every contract includes flat export columns:

```json
{
  "recordType": "contract",
  "eventType": "SNAPSHOT",
  "detectedAt": "2026-08-14T14:25:40.250Z",
  "contractId": "39127674",
  "subject": "IT services",
  "publishedAt": "2026-08-14T13:41:29+02:00",
  "signedAt": "2026-08-10T00:00:00+02:00",
  "valueCzk": 981016.58,
  "buyerIco": "00007064",
  "buyerName": "Ministerstvo vnitra",
  "supplierIcos": ["04767543"],
  "supplierNames": ["Example s.r.o."],
  "issueCount": 0,
  "missingPrice": false,
  "nearProcurementLimit": false,
  "politicalLink": false,
  "validRecord": true,
  "hlidacUrl": "https://www.hlidacstatu.cz/Detail/39127674",
  "coverage": {
    "hlidacContract": "available",
    "hlidacCompanyProfile": "not_requested",
    "aresBuyer": "available",
    "aresSuppliers": "complete"
  }
}
```

The same item also contains nested `event`, `contract`, `buyer`, `suppliers`, `signals`, and `provenance` objects. This preserves detail for API users while keeping Apify's table and CSV exports immediately usable.

Attachment metadata is optional. Binary copies and full extracted attachment text are always removed to control dataset size and reduce unnecessary personal-data processing.

### Disabled company-profile integration

The implementation for Hlídač company profiles is retained behind the owner-only `HLIDAC_COMPANY_PROFILES_ENABLED=true` feature flag, but there is no public input that enables it. Raw customer input cannot activate the integration while the flag is off.

If the endpoint becomes reliable, the integration can be restored without rebuilding it from scratch. Profiles remain allowlist-normalized, and related-person and subsidiary arrays remain excluded.

### Pay-per-event setup

The code contains these atomic dataset-and-billing hooks:

- `contract-result`
- `ares-enriched-contract`
- `new-contract`
- `ares-enriched-new-contract`
- `company-dossier` (legacy compatibility hook; the workflow is disabled unless the Actor owner sets `HLIDAC_COMPANY_DOSSIERS_ENABLED=true`)

Configure event prices in Apify Console. Quiet monitor baselines, unchanged checks, rejected post-filter candidates, summaries, and failures are not charged. Suggested launch tests remain approximately $0.003 for a plain contract and $0.006 for an ARES-enriched contract or new-contract event; adjust after measuring conversion and API cost.

Before every paid dataset write, the Actor checks whether the customer's remaining spending limit can cover that event. When the limit is exhausted, the run ends successfully, reports delivered and deferred counts, and does not attempt an over-budget charge. Monitor state records only newly detected contracts that were actually delivered, so deferred events remain eligible for the next scheduled run.

The legacy company-dossier workflow is also retained behind an owner-only feature flag but disabled for public runs. Its pricing event can be removed while the flag remains off.

### Sources, licence, and responsible use

Hlídač státu data is used under [CC BY 3.0 CZ](https://creativecommons.org/licenses/by/3.0/cz/) unless you have a separate commercial agreement. Each result contains attribution, the licence URL, and a modification marker. Do not remove or obscure attribution when redistributing results unless your licence permits it.

ARES is operated by the Ministry of Finance of the Czech Republic and is used as the official entity/registry enrichment layer. Customers remain responsible for source terms, lawful use, retention, and personal-data obligations applicable to their workflow.

Before operating a managed multi-customer Hlídač token or enabling restricted/commercial endpoints, confirm the intended commercial arrangement with Hlídač státu.

### Operational behavior

- Hlídač requests are rate-limited below the documented four requests per second and retry throttling/server failures with exponential backoff.
- `maxItems` and `scanLimit` are capped at 2,500 because contract search exposes at most 250 pages.
- ARES lookups are deduplicated by IČO within each run.
- IČOs are normalized to eight digits and checksum-validated. Entity names are never fuzzy-matched to an IČO.
- Required Hlídač contract-search or ARES failures fail the run rather than implying complete output.
- Customer spending limits stop output gracefully without lowering the Actor success rate or silently losing monitor events.
- Full-text query totals describe the source result set before local attention-indicator filters.

### Local development

```bash
npm install
npm run check
npm run build
apify run --input-file input.local.json
```

Use [`examples/search.json`](./examples/search.json) or [`examples/monitor.json`](./examples/monitor.json) as a starting point. For local development, either set `HLIDAC_STATU_API_TOKEN` or keep a legacy `hlidacApiToken` only in `input.local.json`, which is ignored by Git.

# Actor input Schema

## `operation` (type: `string`):

Search returns current matches. Monitor stores a baseline and returns only contracts not seen on earlier scheduled runs.

## `searchTerms` (type: `string`):

Words searched across the contract register. Czech inflection and Hlídač full-text behavior apply. Clear this when another guided filter is sufficient.

## `buyerIcos` (type: `array`):

Return contracts where any of these entities is the payer/buyer. IČOs are normalized and checksum-validated.

## `supplierIcos` (type: `array`):

Return contracts where any of these entities is a recipient/supplier.

## `publishedFrom` (type: `string`):

Optional inclusive Register-of-Contracts publication date.

## `publishedTo` (type: `string`):

Optional inclusive publication end date.

## `signedFrom` (type: `string`):

Optional inclusive contract signing date.

## `signedTo` (type: `string`):

Optional inclusive signing end date.

## `minValueCzk` (type: `number`):

Minimum Hlídač-calculated contract value including VAT.

## `maxValueCzk` (type: `number`):

Maximum Hlídač-calculated contract value including VAT.

## `categories` (type: `array`):

Optional top-level categories assigned by Hlídač. A contract may match more than one selected category.

## `onlyWithIssues` (type: `boolean`):

Post-filter retrieved contracts to those with at least one Hlídač issue record.

## `onlyMissingPrice` (type: `boolean`):

Post-filter contracts where no positive supplied or calculated value is available.

## `onlyNearProcurementLimit` (type: `boolean`):

Post-filter using Hlídač's near-threshold analytical hint.

## `onlyPoliticalLink` (type: `boolean`):

Post-filter using current, recent, historical, or analytical political-connection fields from Hlídač.

## `maxItems` (type: `integer`):

Maximum visible results written to the dataset and charged in this run.

## `scanLimit` (type: `integer`):

Used when attention-indicator post-filters are enabled. A larger scan can find more qualifying results but performs more source requests. It never increases output above maxItems.

## `aresEnrichment` (type: `boolean`):

Add registered name/address, legal-form code, tax ID, CZ-NACE activities, source status, and update date for buyers and suppliers.

## `includeAttachments` (type: `boolean`):

Include pages, content type, extraction quality, word counts, and redaction statistics. Binary files and full extracted text are always excluded.

## `sort` (type: `string`):

Monitor mode always scans newest published contracts first.

## `advancedQuery` (type: `string`):

Optional raw Hlídač query clause ANDed with the guided filters. Intended for users familiar with Hlídač/Elastic query syntax.

## `monitorKey` (type: `string`):

Stable ID reused by scheduled runs. Use a different key for each saved search.

## `firstRunBehavior` (type: `string`):

Store baseline only avoids an initial flood. Emit current contracts returns the first snapshot as NEW events.

## `resetState` (type: `boolean`):

Delete the baseline for this monitor key before the run.

## `stateStoreName` (type: `string`):

Named key-value store shared by scheduled runs.

## `requestTimeoutSecs` (type: `integer`):

Per-request timeout.

## `maxRequestRetries` (type: `integer`):

Retries for throttling, server errors, and transient network failures.

## Actor input object example

```json
{
  "operation": "search",
  "buyerIcos": [],
  "supplierIcos": [],
  "categories": [],
  "onlyWithIssues": false,
  "onlyMissingPrice": false,
  "onlyNearProcurementLimit": false,
  "onlyPoliticalLink": false,
  "maxItems": 100,
  "scanLimit": 500,
  "aresEnrichment": true,
  "includeAttachments": false,
  "sort": "newest_published",
  "monitorKey": "my-contract-monitor",
  "firstRunBehavior": "baseline_only",
  "resetState": false,
  "stateStoreName": "hlidac-statu-monitor-state",
  "requestTimeoutSecs": 45,
  "maxRequestRetries": 3
}
```

# Actor output Schema

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

No description

## `runSummary` (type: `string`):

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("fetchfinch/hlidac-statu-ares-monitor").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("fetchfinch/hlidac-statu-ares-monitor").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 '{}' |
apify call fetchfinch/hlidac-statu-ares-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fetchfinch/hlidac-statu-ares-monitor"
        }
    }
}

```

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/MDGJBh3U1xF76Uw3s/builds/DKUFVUdBC560UA9pl/openapi.json