# HWPX Text Extractor (Korean Hangul documents) (`koreadatalab/hwpx-text-extractor`) Actor

Extract plain text from Korean HWPX documents (Hangul Word Processor 2014+). Feed it file URLs, get clean text per document. Detects legacy binary .hwp and explains exactly why it cannot be read.

- **URL**: https://apify.com/koreadatalab/hwpx-text-extractor.md
- **Developed by:** [민수 김](https://apify.com/koreadatalab) (community)
- **Categories:** Developer tools, Automation, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

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

## HWPX Text Extractor — Korean Hangul documents to plain text

### What does HWPX Text Extractor do?

**HWPX Text Extractor** pulls clean plain text out of Korean **HWPX documents** (the XML-based format of [Hangul Word Processor](https://www.hancom.com/) 2014+). HWPX is the standard document format across Korean government agencies, public institutions, and enterprises — grant announcements, procurement notices, official forms, and reports are published in it every day. Most text-processing pipelines cannot read it.

Give this Actor a list of file URLs and it returns the extracted text of each document as structured JSON — ready for search indexing, LLM pipelines, translation, or archiving. Running on the Apify platform gives you API access, scheduling, and integrations out of the box.

### Why use HWPX Text Extractor?

- **Korean public-sector data is locked in HWPX.** Government grant portals, procurement systems, and municipal sites attach HWPX files that generic parsers (and most OCR pipelines) skip.
- **No Hangul software required.** No HWP viewer, no Windows, no manual conversion.
- **Honest error reporting.** Legacy binary `.hwp` (HWP 5.x, OLE2) files are *detected and named explicitly* — you get "this is a legacy binary HWP, re-save as HWPX" instead of a silent failure or garbage output.
- **Batch-friendly.** One run processes a whole list of URLs; each file becomes one dataset item, and one broken file never kills the batch.

### How to use it

1. Open the Actor and paste one or more direct HWPX file URLs into **HWPX file URLs**.
2. Click **Start**. The Actor downloads each file and extracts its text.
3. Open the **Output** tab (or the dataset API) and download results as JSON, CSV, or Excel.

### Input

```json
{
    "fileUrls": [
        "https://example.go.kr/files/announcement.hwpx",
        "https://example.go.kr/files/form.hwpx"
    ]
}
```

URLs served with a different extension work too — the Actor checks the actual file bytes, not the filename.

### Output

One dataset item per URL:

```json
{
    "url": "https://example.go.kr/files/announcement.hwpx",
    "filename": "announcement.hwpx",
    "ok": true,
    "text": "전북특별자치도 공고 제2026-1353호 ...",
    "textLength": 13688,
    "sectionCount": 1,
    "error": null
}
```

Failed files stay in the dataset with `ok: false` and a human-readable `error`, so you always know exactly what was skipped and why:

| error | meaning |
|---|---|
| `legacy binary HWP 5.x file (OLE2) ...` | The file is old-format `.hwp`, not HWPX. Re-save it in Hangul 2014+ |
| `not a zip-based HWPX file` | The URL did not return an HWPX document |
| `no Contents/section*.xml inside` | Zip container without HWPX structure |
| HTTP errors (404, 403, timeout) | The file could not be downloaded |

### Pricing

The Actor charges **per successfully parsed document** — failed downloads and unreadable files are free. Parsing is fast (a typical 40-page government announcement takes under a second), so platform usage costs stay minimal.

### Limitations & tips

- **HWPX only.** Legacy binary `.hwp` (HWP 5.x) is intentionally out of scope — it is a completely different, undocumented OLE2 format. The Actor detects it and tells you.
- Text comes out in reading order, paragraph by paragraph. Tables are flattened into text lines; cell structure is not preserved in this version.
- Files over 50 MB are rejected to protect your usage costs.

### FAQ & support

**Is scraping the files legal?** This Actor does not crawl any site — it only downloads the URLs *you* provide. Make sure you have the right to access those files.

**Found a bug or need a feature (table structure, HWP 5.x support, OCR fallback)?** Open an issue on the Actor's **Issues** tab — the roadmap is driven by real requests.

# Actor input Schema

## `fileUrls` (type: `array`):

Direct download URLs of .hwpx files (zip-based HWPX served under any extension works too). One dataset item is produced per URL. Leave empty to run a free demo on a bundled sample document.

## Actor input object example

```json
{
  "fileUrls": []
}
```

# 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 = {
    "fileUrls": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("koreadatalab/hwpx-text-extractor").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 = { "fileUrls": [] }

# Run the Actor and wait for it to finish
run = client.actor("koreadatalab/hwpx-text-extractor").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 '{
  "fileUrls": []
}' |
apify call koreadatalab/hwpx-text-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,koreadatalab/hwpx-text-extractor"
        }
    }
}

```

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/m0MaDQNvAzeoMQEwX/builds/bEgWMLlCGjTcUsjGF/openapi.json