XLSX Parsing API

Spreadsheets Are Structured Data Trapped in a Visual Layout

An .xlsx file is a zip archive containing SpreadsheetML — XML that encodes cells, types, formulas, merge ranges, and shared strings. Most parsers flatten this into CSV or plain text, destroying merged cells, multi-sheet structure, and cell type information.

AILANG Parse reads SpreadsheetML directly. Merged cells get explicit gridSpan/vMerge metadata from the mergeCell elements. Shared string references are resolved. Each sheet becomes a separate section with its full table structure intact.

Raw SpreadsheetML vs Structured Output

<!-- sharedStrings.xml -->
<sst count="6">
  <si><t>Region</t></si>
  <si><t>Q1</t></si>
  <si><t>Q2</t></si>
  <si><t>EMEA</t></si>
  <si><t>APAC</t></si>
</sst>

<!-- sheet1.xml -->
<mergeCells count="1">
  <mergeCell ref="A1:A2"/>
</mergeCells>
<sheetData>
  <row r="1">
    <c r="A1" t="s"><v>0</v></c>
    <c r="B1" t="s"><v>1</v></c>
    <c r="C1" t="s"><v>2</v></c>
  </row>
  <row r="2">
    <c r="B2"><v>125000</v></c>
    <c r="C2"><v>140000</v></c>
  </row>
  <row r="3">
    <c r="A3" t="s"><v>4</v></c>
    <c r="B3"><v>143000</v></c>
    <c r="C3">
      <f>SUM(B2:B3)</f>
      <v>268000</v>
    </c>
  </row>
</sheetData>

{
  "metadata": {
    "title": "Q1-Q2 Revenue",
    "sheets": ["Revenue", "Summary"]
  },
  "blocks": [
    {
      "type": "heading",
      "level": 2,
      "text": "Revenue"
    },
    {
      "type": "table",
      "headers": [
        {"text": "Region", "vMerge": "restart"},
        {"text": "Q1"},
        {"text": "Q2"}
      ],
      "rows": [
        [
          {"text": "EMEA"},
          {"text": "125000"},
          {"text": "140000"}
        ],
        [
          {"text": "APAC"},
          {"text": "143000"},
          {"text": "268000",
           "formula": "SUM(B2:B3)"}
        ]
      ]
    }
  ]
}

What Gets Extracted

Merged Cells

Financial reports, inventory sheets, and regulatory filings use merged cells extensively for group headers and category labels. XLSX stores these as mergeCell elements with cell range references (e.g., A1:A3). AILANG Parse resolves each range into per-cell gridSpan (horizontal) and vMerge (vertical) attributes.

{
  "type": "table",
  "headers": [
    {"text": "Department", "vMerge": "restart"},
    {"text": "H1", "gridSpan": 2},
    {"text": "H2", "gridSpan": 2}
  ],
  "rows": [
    [{"text": ""}, {"text": "Q1"}, {"text": "Q2"}, {"text": "Q3"}, {"text": "Q4"}],
    [{"text": "Engineering"}, {"text": "$450K"}, {"text": "$480K"}, {"text": "$510K"}, {"text": "$520K"}],
    [{"text": "Sales"}, {"text": "$320K"}, {"text": "$340K"}, {"text": "$355K"}, {"text": "$370K"}]
  ]
}

See Tables & Merged Cells for the full specification.

Multi-Sheet Workbooks

A single XLSX file often contains multiple worksheets: raw data, summaries, pivot tables, configuration. AILANG Parse processes all sheets in workbook order, each becoming a SectionBlock with the sheet name as a heading and the sheet's table data as nested blocks.

{
  "blocks": [
    {"type": "heading", "level": 2, "text": "Raw Data"},
    {"type": "table", "headers": [...], "rows": [...]},
    {"type": "heading", "level": 2, "text": "Summary"},
    {"type": "table", "headers": [...], "rows": [...]},
    {"type": "heading", "level": 2, "text": "Config"},
    {"type": "table", "headers": [...], "rows": [...]}
  ]
}

Use Cases

Try It

CLI

# Parse an XLSX file
ailang run --entry main --caps IO,FS,Env \
  docparse/main.ail financials.xlsx

# Convert XLSX to Markdown tables
./bin/docparse financials.xlsx --convert output.md

# Convert XLSX to HTML
./bin/docparse financials.xlsx --convert output.html

API

curl -X POST https://docparse.ailang.sunholo.com/api/v1/parse \
  -H "Content-Type: application/json" \
  -d '{"filepath":"sample_xlsx_formatting","outputFormat":"markdown","apiKey":"YOUR_API_KEY"}'

Python SDK

from ailang_parse import DocParse

client = DocParse(api_key="YOUR_API_KEY")
result = client.parse("financials.xlsx", output_format="json")

# Iterate sheets (each is a section block)
for block in result.blocks:
    if block.type == "heading":
        print(f"Sheet: {block.text}")
    if block.type == "table":
        print(f"  {len(block.rows)} rows, {len(block.headers)} columns")
        if block.has_merges:
            print("  Contains merged cells")

Parse in Browser    API Reference