# Japan Liquor License Signals (`japan_signal_lab/japan-liquor-license-signals`) Actor

Japan liquor-license leads from official monthly NTA data: new online-sales, wholesale, import/export, and license-change events with source URLs, dates, and English summaries for B2B outreach.

- **URL**: https://apify.com/japan\_signal\_lab/japan-liquor-license-signals.md
- **Developed by:** [Japan Signal Lab](https://apify.com/japan_signal_lab) (community)
- **Categories:** Lead generation, E-commerce, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 liquor-license signal emitteds

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

## Japan Liquor License Signals

**Official Japanese liquor-sales-license events, normalized as source-attributed B2B signals.**

The Actor follows the National Tax Agency's public monthly lists of new and changed liquor-sales licenses across all 47 prefectures. It returns events that are useful for early commercial research: online-sales licenses, wholesale and import/export licenses, business transfers, incorporation, relocation, condition changes, and optionally every general retail new license.

This is **not** a static liquor-store directory, a contact database, a legal opinion, or evidence that a business is ready to buy a product. It is an official-source event feed for a customer's own lawful research and outreach workflow.

### Best fit

- Japanese liquor wholesalers and import/export operators seeking newly licensed counterparties.
- Alcohol-EC platforms, fulfilment providers, cold-chain logistics, packaging, POS and payments teams.
- B2B lead-research, market-intelligence, investment, and Japanese-sake import research teams.

The default purposely excludes ordinary **general retail only** new licenses, such as routine convenience-store openings. Set `includeGeneralRetailNewLicenses` to `true` if comprehensive coverage is needed.

### Signals

Each Dataset row represents one published licence record. `eventType` is the highest-priority signal; `eventTypes` retains every matching signal without duplicating the source row.

| Signal | Official basis |
| --- | --- |
| `new_license` | `処理区分: 新規` |
| `online_sales_license` | `種類区分` contains `通信販売` |
| `wholesale_license` | `卸小売等区分` contains `卸売` or `卸・小売` |
| `import_export_license` | `種類区分` contains `輸出入` |
| `business_transfer` | `処理区分: 事業譲渡` |
| `incorporation` | `処理区分: 法人成り等` |
| `relocation` | `処理区分: 移転` |
| `license_change` | `処理区分: 条件緩和` or `条件解除` |

Rows include the published business/company name, any corporate number printed in the official cell, address, prefecture, effective and application dates, licence categories, Japanese processing category, an English summary, and complete source provenance. The Actor does **not** call a separate company database: a `corporateNumber` is returned only when it is already printed in the NTA source.

### Official source, coverage and use conditions

The source of truth is the NTA's [national liquor-sales-license index](https://www.nta.go.jp/taxes/sake/menkyo/shinki/hambai/03.htm). It links to 12 regional tax bureaux and their prefecture-level monthly PDF lists. The NTA defines the published fields, including effective date, application date, licensee name, selling location, trade category, license category, and processing category. Regional pages state that the lists are normally updated at month-end and retained for one year.

NTA website content may be used under the [Public Data Terms of Use (Version 1.0)](https://www.nta.go.jp/chuijiko/copy.htm), unless a page says otherwise. The terms require attribution and clear disclosure of processing; every output carries both. The Actor requests only ordinary public NTA HTML and PDFs, does not bypass a login, and does not rely on a portal's scraping terms.

Some records concern sole proprietors and can contain a published name and address. The Actor does not add phone numbers, email addresses, or personal enrichment. Users remain responsible for their lawful purpose, privacy obligations, and any marketing/outreach rules that apply to them.

### Input

```json
{
  "prefectures": ["東京都", "大阪府", "北海道"],
  "sourceMonth": "",
  "signalTypes": ["online_sales_license", "wholesale_license", "import_export_license"],
  "includeGeneralRetailNewLicenses": false,
  "maxSignals": 10000
}
```

- `prefectures`: optional; blank scans all 47 prefectures.
- `sourceMonth`: optional `YYYY-MM` coverage month while it is still retained by the NTA; blank selects the latest available publication per prefecture.
- `signalTypes`: optional list of the eight stable signal types; blank selects all.
- `includeGeneralRetailNewLicenses`: defaults to `false` to preserve the B2B-signal focus.
- `maxSignals`: 1–10,000 Dataset safety limit.

### Output example

```json
{
  "eventType": "import_export_license",
  "eventTypes": ["import_export_license", "online_sales_license", "wholesale_license", "new_license"],
  "businessName": "株式会社出光商会",
  "corporateNumber": "1010001065387",
  "address": "港区芝５丁目１３番１８号",
  "prefecture": "東京都",
  "effectiveDate": "2026-06-01",
  "applicationDate": "2026-04-21",
  "licenseTradeCategory": "卸・小売",
  "licenseCategory": "輸出入・一般・通信販売",
  "processingCategory": "新規",
  "englishSummary": "Official NTA record: ...",
  "source": {
    "provider": "National Tax Agency, Japan",
    "sourcePdfUrl": "https://www.nta.go.jp/...",
    "sourcePublicationDate": "2026-07-31",
    "sourceCoverageMonth": "2026-06",
    "sourceConfidence": "official_text_pdf"
  }
}
```

`SUMMARY` records source-row count, scanned/failed publications, emitted signals, skipped low-intent general-retail rows, and run duration. A publication failure is explicit; it is never silently treated as no signal.

### Pay-per-event model

The Actor charges two custom Apify PPE events, with no `apify-default-dataset-item` charge:

- `official-publication-scanned` — $0.02 for one successfully parsed NTA prefecture PDF.
- `liquor-license-signal-emitted` — $0.01 for one emitted Dataset signal.

The runtime refuses an unexpected PPE event configuration, so a default Dataset-item charge cannot be added silently.

### Development

```bash
npm ci
npm test
npm run build
PDF_EXTRACTOR_PYTHON=/path/to/python3 npm run e2e:sample
```

The production Docker image installs a pinned `pdfplumber` extractor. It reads each source PDF from memory and does not persist downloaded PDFs or add corporate-number enrichment.

# Actor input Schema

## `prefectures` (type: `array`):

Choose any prefectures. Leave blank for all 47 prefectures.

## `sourceMonth` (type: `string`):

Use YYYY-MM to replay a month still retained by the NTA. Leave blank for each prefecture's current publication.

## `signalTypes` (type: `array`):

A source row can match more than one signal type. Each row is emitted once with an eventTypes array.

## `includeGeneralRetailNewLicenses` (type: `boolean`):

Off by default to avoid filling a B2B signal feed with ordinary convenience-store and shop openings. Turn on to receive every newly issued general retail license.

## `maxSignals` (type: `integer`):

Safety limit for Dataset output. Source publications are still scanned only until this limit is reached.

## Actor input object example

```json
{
  "prefectures": [
    "東京都",
    "大阪府",
    "北海道"
  ],
  "signalTypes": [
    "new_license",
    "online_sales_license",
    "wholesale_license",
    "import_export_license",
    "business_transfer",
    "incorporation",
    "relocation",
    "license_change"
  ],
  "includeGeneralRetailNewLicenses": false,
  "maxSignals": 10000
}
```

# Actor output Schema

## `licenseSignals` (type: `string`):

One source-attributed record per official license row, with one primary eventType and all matching eventTypes.

## `summary` (type: `string`):

Scanned publications, source-row count, emitted signals, skipped general retail rows, and any publication-level failures.

# 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 = {
    "prefectures": [
        "東京都",
        "大阪府",
        "北海道"
    ],
    "sourceMonth": "",
    "signalTypes": [
        "new_license",
        "online_sales_license",
        "wholesale_license",
        "import_export_license",
        "business_transfer",
        "incorporation",
        "relocation",
        "license_change"
    ],
    "includeGeneralRetailNewLicenses": false,
    "maxSignals": 10000
};

// Run the Actor and wait for it to finish
const run = await client.actor("japan_signal_lab/japan-liquor-license-signals").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 = {
    "prefectures": [
        "東京都",
        "大阪府",
        "北海道",
    ],
    "sourceMonth": "",
    "signalTypes": [
        "new_license",
        "online_sales_license",
        "wholesale_license",
        "import_export_license",
        "business_transfer",
        "incorporation",
        "relocation",
        "license_change",
    ],
    "includeGeneralRetailNewLicenses": False,
    "maxSignals": 10000,
}

# Run the Actor and wait for it to finish
run = client.actor("japan_signal_lab/japan-liquor-license-signals").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 '{
  "prefectures": [
    "東京都",
    "大阪府",
    "北海道"
  ],
  "sourceMonth": "",
  "signalTypes": [
    "new_license",
    "online_sales_license",
    "wholesale_license",
    "import_export_license",
    "business_transfer",
    "incorporation",
    "relocation",
    "license_change"
  ],
  "includeGeneralRetailNewLicenses": false,
  "maxSignals": 10000
}' |
apify call japan_signal_lab/japan-liquor-license-signals --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,japan_signal_lab/japan-liquor-license-signals"
        }
    }
}

```

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/oADiu8kyT9Zo1PP7X/builds/hBUB95LG0OhztjHlq/openapi.json