# Japan Public Tenders & Procurement Monitor (KKJ API) (`terselogic/jp-public-tenders-monitor`) Actor

Monitor new Japanese government and municipal procurement tenders via the official KKJ API. Supports automatic date-slice pagination past 1,000 hits, KVS deduplication (onlyNewItems mode charges only for new tenders), and English/Japanese normalized JSON output.

- **URL**: https://apify.com/terselogic/jp-public-tenders-monitor.md
- **Developed by:** [terse logic](https://apify.com/terselogic) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.80 / 1,000 tenders

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Japan Public Tenders & Procurement Monitor (KKJ API)

Monitor newly published Japanese government, municipal, and public agency procurement tenders (官公需・公共調達・入札案件) using the official SME Agency **KKJ (官公需情報ポータルサイト) Search API**.

Built for **automated daily/weekly monitoring**, **AI agent / MCP pipelines**, and **n8n / Make / Slack notifications** with built-in deduplication so you only pay for newly discovered tenders.

***

### Key Features

- **Incremental Diff Mode (`onlyNewItems: true`)**: Tracks previously seen `tenderId` keys in a named Key-Value Store (`jp-tenders-diff-state`). Already-delivered tenders are skipped and **never charged again** on scheduled runs.
- **Automatic Date & Prefecture Split Past 1,000 Hits**: Overcomes the KKJ API's 1,000-result limit by recursively splitting date ranges (and prefecture codes if needed) so high-volume queries never silently truncate.
- **AI/RAG-Ready Normalized Schema**: Outputs clean English field names (`tenderId`, `title`, `organization`, `prefectureName`, `issueDate`, `documentUrl`, `attachments`) alongside a `coverageScore` (`0.00` to `1.00`).
- **Fast & Lightweight**: Pure HTTP + XML parsing (`256MB–512MB` RAM, zero browser overhead).
- **Limited Permissions**: Runs safely with Apify Limited Permissions, compatible with AI agents and Agentic Payments.

***

### Input Example

```json
{
  "queries": ["AI OR 生成AI", "システム開発 ANDNOT 保守"],
  "prefectureCodes": ["13", "27"],
  "lookbackDays": 7,
  "onlyNewItems": true,
  "stateKey": "kkj-tokyo-osaka-it",
  "maxItems": 200
}
```

***

### Output Example

```json
{
  "tenderId": "c2hpenVva2EvaXdhdGFfY2l0eS8yMDI2LzIwMjYxMTE3XzAyMTE4Cg==",
  "title": "令和8年度 竜洋海洋公園流水プールろ過機ポンプモーター取替修繕",
  "organization": "静岡県磐田市",
  "prefectureCode": "22",
  "prefectureName": "静岡県",
  "cityCode": "222119",
  "cityName": "磐田市",
  "issueDate": "2026-11-17",
  "publishedAt": "2026-11-17T19:05:49+09:00",
  "documentUrl": "https://www.city.iwata.shizuoka.jp/_res/projects/default_project/_page_/001/017/162/koukokubun.pdf",
  "fileType": "pdf",
  "fileSizeBytes": 225985,
  "attachments": [],
  "description": "...",
  "matchedQuery": "AI OR システム開発 | ALL",
  "source": "KKJ (Chusho Kigyocho)",
  "coverageScore": 1,
  "fetchedAt": "2026-11-18T07:50:00.000Z"
}
```

***

### n8n / Make / Webhook Integration

Run this Actor synchronously from n8n, Make, or any automation workflow using the Apify API (`?method=POST` supported for GET-only webhooks):

```text
POST https://api.apify.com/v2/acts/terselogic~jp-public-tenders-monitor/run-sync-get-dataset-items?token=YOUR_API_TOKEN
```

Schedule this Actor daily via Apify Schedules with `onlyNewItems: true` to receive only new tenders published since the previous run.

***

### Pricing & Free Tier

- Charged per newly discovered tender (`tender-fetched`) written to the dataset.
- Free-tier Apify accounts are capped at **25 items per run** and exit gracefully with a status message. Upgrade to any paid Apify plan for higher limits and tier discounts.

### Data Attribution

Data is retrieved from the official [官公需情報ポータルサイト (KKJ)](https://www.kkj.go.jp/) API provided by the Small and Medium Enterprise Agency of Japan (中小企業庁). Users are responsible for complying with KKJ terms of use and attribution requirements when redistributing data.

# Actor input Schema

## `queries` (type: `array`):

KKJ search expressions (supports AND, OR, ANDNOT, NOT). Each query runs separately and results are deduplicated by tenderId.

## `projectName` (type: `string`):

Optional substring filter matched against tender project titles.

## `organizationName` (type: `string`):

Optional substring filter matched against issuing government/municipal organization names.

## `prefectureCodes` (type: `array`):

Optional 2-digit JIS prefecture codes (e.g., 13 for Tokyo, 27 for Osaka). Leave empty to search nationwide.

## `issueDateFrom` (type: `string`):

Start date for CFT_Issue_Date. When omitted, defaults to lookbackDays before today (JST).

## `issueDateTo` (type: `string`):

End date for CFT_Issue_Date. When omitted, defaults to today (JST).

## `lookbackDays` (type: `integer`):

Number of days to look back from today when issueDateFrom is omitted.

## `onlyNewItems` (type: `boolean`):

When enabled, previously seen tenderId keys stored in the named Key-Value Store are skipped and not charged. Enable this for scheduled monitoring runs (prefilled false for one-off/default test runs; defaults to true when omitted via API).

## `stateKey` (type: `string`):

Key name inside the named Key-Value Store (jp-tenders-diff-state) used to track already-seen tender IDs.

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

Maximum number of new tender records to output and charge per run (Free tier runs are capped at 25 items).

## `maxDescriptionLength` (type: `integer`):

Truncate full announcement text to this character length (0 keeps full text).

## `requestDelayMs` (type: `integer`):

Delay between KKJ API requests in milliseconds to avoid overloading the public endpoint.

## Actor input object example

```json
{
  "queries": [
    "AI OR システム開発"
  ],
  "prefectureCodes": [],
  "lookbackDays": 7,
  "onlyNewItems": false,
  "stateKey": "kkj-seen-keys",
  "maxItems": 200,
  "maxDescriptionLength": 2000,
  "requestDelayMs": 1000
}
```

# Actor output Schema

## `overview` (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 = {
    "queries": [
        "AI OR システム開発"
    ],
    "onlyNewItems": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("terselogic/jp-public-tenders-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 = {
    "queries": ["AI OR システム開発"],
    "onlyNewItems": False,
}

# Run the Actor and wait for it to finish
run = client.actor("terselogic/jp-public-tenders-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 '{
  "queries": [
    "AI OR システム開発"
  ],
  "onlyNewItems": false
}' |
apify call terselogic/jp-public-tenders-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,terselogic/jp-public-tenders-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/ZQbkacRVwQ8LZUW1p/builds/5F9Cp04gt6p5Lds7T/openapi.json
