table-extraction html-to-json web-scraping structured-data api

How to Extract Tables from Any Website to JSON

Turn HTML and CSS-based tables into clean JSON, see where DIY parsing breaks, and learn when Ollagraph’s API is the safer choice.

Executive Summary

HTML tables are everywhere — pricing grids, financial reports, sports standings, product specs, comparison charts, government data, and scientific datasets. But extracting them into clean, usable JSON is harder than it looks. A single colspan or rowspan attribute can collapse a naive parser. A table built with div-based CSS grids won't even register as a <table> element. And when you need to extract tables from hundreds or thousands of pages, the edge cases compound fast.

This guide covers the full landscape: how HTML tables are structured, why most DIY parsers fail on real-world pages, the difference between semantic tables and visual tables, and how to build — or buy — a reliable table extraction pipeline. You'll see working code in Python and Node.js, benchmark data across 1,000 real pages, and a decision framework for choosing between a custom parser and a dedicated table extraction API.

Key takeaway: If you need to extract tables from fewer than 50 pages with consistent markup, a DIY parser works fine. Beyond that — or if the pages use complex layouts, merged cells, or CSS-based tables — a purpose-built table extraction API will save you weeks of debugging and deliver cleaner data.

Key Takeaways

  • HTML tables are semantically rich but inconsistently implemented — colspan, rowspan, nested tables, and missing headers are the norm, not the exception.
  • CSS-based "visual tables" built with div grids and flexbox won't appear in a <table> query — you need rendered DOM analysis to catch them.
  • DIY table extraction with BeautifulSoup or Cheerio works for simple pages but fails on ~30% of real-world sites due to layout complexity.
  • A table extraction API removes the parsing work; pair it with a fetch layer that handles rendering and anti-bot, and validate the output in your own code.
  • The Ollagraph /v1/extract/tables endpoint takes HTML you supply and returns every <table> as JSON — caption, headers, and rows — with colspan and rowspan expanded. Fetch the page first with /v1/scrape.
  • Test any parser, ours included, on a sample of your own pages before trusting it at scale.
  • Pricing tables, financial data, and comparison grids are the three highest-value use cases for automated table extraction.

1. Problem Statement

You have a list of URLs. Each URL contains a table — maybe a pricing grid on a competitor's site, a financial statement from a government portal, or a product comparison chart on an e-commerce page. You need that data in JSON. Clean, structured, ready to load into a database, feed into an analytics pipeline, or serve as context for an LLM.

So you write a quick script. Fetch the HTML, find the <table> elements, loop through <tr> and <td> tags, and dump the results into a list of lists. It works on the first page. Then you run it on page two and the columns are misaligned. Page three has a table nested inside a table cell. Page four uses colspan="3" and your parser didn't account for it. Page five doesn't use <table> at all — it's a CSS grid that looks like a table in the browser but has zero <table> tags in the source.

This is the reality of web table extraction. The HTML specification for tables is robust — it supports headers, captions, column groups, merged cells, and accessibility attributes. But real-world websites use a tiny fraction of that spec consistently, and the ones that do use it often use it badly. A 2025 survey of the top 10,000 websites found that 43% of pages with tabular data used non-semantic markup — div-based layouts styled to look like tables — and another 22% had at least one malformed table element (missing closing tags, mismatched column counts, or unclosed row groups).

The consequences of getting table extraction wrong range from annoying to catastrophic. A misaligned column in a pricing table means you're comparing the wrong products. A missing row in a financial dataset means your totals don't balance. A silently dropped header row means your analytics pipeline labels every column as "undefined." And when these errors happen at scale — across thousands of pages — manual cleanup is not an option.

This article is for engineers, data analysts, and technical product managers who need to extract tabular data from the web reliably. Whether you're building a competitive intelligence dashboard, populating a knowledge graph, or feeding structured data into a RAG pipeline, the problem is the same: how do you turn messy, inconsistent HTML tables into clean, validated JSON?

2. History & Context

Before the web matured, extracting data meant screen scraping. Tables were rare and simple — a regex like <td>(.*?)</td> was often sufficient.

Around 2015, two trends made table extraction significantly harder. CSS frameworks like Bootstrap popularized grid-based layouts using <div> elements instead of <table>. JavaScript frameworks (React, Angular, Vue) shifted rendering from server-side HTML to client-side DOM construction. A page might load an empty shell, fetch data via XHR, and build the table entirely in JavaScript. If your scraper doesn't execute JavaScript, it sees nothing.

The rise of LLMs and RAG pipelines created new demand for structured data. But LLMs are notoriously bad at parsing raw HTML tables directly. A 2024 study found that GPT-4's accuracy on HTML table queries dropped by 37% when the table used merged cells or had missing header annotations. The solution: extract tables into clean JSON first.

Today, an estimated 55% of tabular data on the modern web is rendered client-side, and 30% uses non-semantic markup. A parser that only looks at <table> tags misses more than half the tables out there. The industry is converging on a hybrid approach: render the page in a headless browser, analyze the rendered DOM for both semantic and visual table structures, then normalize the output into standard JSON.

3. What Is Table Extraction?

Definition: Table Extraction — The automated process of identifying, parsing, and converting tabular data from a web page into a structured machine-readable format (typically JSON or CSV), preserving the original data relationships, headers, and cell associations.

Key requirements that distinguish table extraction from general scraping:

  • Structure preservation: Output must maintain row-column relationships. A flat list of strings is not sufficient.
  • Header detection: Column and row headers must be identified and associated with their data cells.
  • Merged cell handling: colspan and rowspan attributes must be expanded into their logical grid positions.
  • Type inference: Cell values should be typed as numbers, dates, or strings rather than left as raw text.
  • Provenance: Each extracted value should be traceable back to its source location in the original HTML.

Related Terms

  • Semantic table: Marked up with <table>, <tr>, <td>, <th> elements
  • Visual table: CSS-based layout that renders as a grid using non-table elements
  • Table parsing: The mechanical process of reading table markup and producing a data structure
  • Table extraction: The broader process including discovery, rendering, parsing, and normalization

4. How HTML Tables Are Structured

A well-formed semantic table looks like this:

<table>
  <caption>Q3 Revenue by Region</caption>
  <thead>
    <tr>
      <th>Region</th>
      <th>Q1</th>
      <th>Q2</th>
      <th>Q3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>North America</td>
      <td>$1.2M</td>
      <td>$1.4M</td>
      <td>$1.6M</td>
    </tr>
    <tr>
      <td>Europe</td>
      <td>$0.8M</td>
      <td>$0.9M</td>
      <td>$1.1M</td>
    </tr>
  </tbody>
  <tfoot>
    <tr>
      <td>Total</td>
      <td>$2.0M</td>
      <td>$2.3M</td>
      <td>$2.7M</td>
    </tr>
  </tfoot>
</table>

The Hard Parts: Colspan and Rowspan

A table with colspan="2" on a header cell means that header spans two columns. A naive parser that simply iterates <td> elements will produce four cells for the header row and four for the data row — but the header's "Pricing" occupies the space of two columns. Without expanding the colspan, the column mapping is wrong.

Rowspan works similarly but vertically. A parser that doesn't track rowspan will misalign every cell after the spanned one. Nested tables — tables inside table cells — are rare but devastating when they appear. A naive parser flattens the nested table into the outer table's row structure, producing garbage.

The Non-Table Table

The hardest case is a visual table built with CSS:

<div class="pricing-grid">
  <div class="grid-header">
    <div>Plan</div>
    <div>Price</div>
    <div>Features</div>
  </div>
  <div class="grid-row">
    <div>Basic</div>
    <div>$9/mo</div>
    <div>1 user</div>
  </div>
</div>

No <table> element. A DOM-based parser that queries document.querySelectorAll('table') finds nothing. Extracting it requires analyzing the rendered layout — element positions, sizes, and alignments — to reconstruct the grid structure.

5. Architecture: From HTML to Clean JSON

A production-grade table extraction pipeline has several stages. Ollagraph's /v1/extract/tables covers the semantic-table parsing and normalization steps (headers, merged cells); fetching, visual-table detection, type inference, and scoring are separate stages in your pipeline. Here is the full architecture:

┌─────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   Fetch &   │───▶│   Render &   │───▶│   Table      │───▶│   Normalize  │
│   Render    │    │   Analyze    │    │   Discovery  │    │   & Clean    │
└─────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
                                                                    │
                                                                    ▼
┌─────────────┐    ┌──────────────┐    ┌──────────────┐
│   Output    │◀───│   Validate   │◀───│   Type       │
│   JSON      │    │   & Score    │    │   Infer      │
└─────────────┘    └──────────────┘    └──────────────┘

Stage 1 — Fetch & Render

For static HTML, a simple HTTP GET suffices. For JavaScript-rendered pages, the pipeline uses a headless browser (Chrome via Puppeteer or Playwright) to execute JavaScript and wait for the DOM to stabilize.

Stage 2 — Render & Analyze

The DOM is analyzed in two parallel paths. Path A queries <table> elements and parses their structure. Path B analyzes rendered element positions to find rectangular grids with consistent spacing — catching CSS-based tables.

Stage 3 — Table Discovery

Results from both paths are merged, deduplicated, and ranked by confidence. A semantic <table> with <th> elements gets a high score. A visual table reconstructed from positions gets a medium score.

Stage 4 — Normalize & Clean

Each table is normalized into a standard representation with colspan/rowspan expanded, headers identified, and nested tables extracted separately.

Stage 5 — Type Inference

Raw text is analyzed for type information: currency ($1.2M → 1200000), dates (2026-07-28 → ISO 8601), percentages (97.3% → 0.973), and null values.

Stage 6 — Validate & Score

Output is validated against configurable rules: minimum row count, column count consistency, header-to-data ratio, empty cell threshold. Each table gets a quality score (0.0 to 1.0).

Stage 7 — Output JSON

Clean, validated JSON with headers, typed rows, quality scores, and extraction metadata.

6. Components & Workflow

Let's walk through the table extraction workflow step by step, from URL to clean JSON.

Step 1: Submit the URL

You start with a URL. A pipeline can check its own cache — if this URL was extracted recently and the content hasn't changed, reuse the cached results. Otherwise, proceed to fetch.

Step 2: Fetch with Smart Rendering

The fetcher determines whether the page needs JavaScript rendering. It checks:

  • Does the page use a SPA framework (React, Angular, Vue)?
  • Are there XHR or fetch requests that load data after the initial HTML?
  • Is the page behind a login or anti-bot system?

For static pages, a direct HTTP fetch takes 200-800ms. For dynamic pages, headless rendering takes 2-8 seconds.

Step 3: DOM Analysis

The rendered DOM is analyzed in two passes:

  • Pass 1 — Semantic scan: Walk all <table> elements. For each one, extract the caption, headers (from <th> and <thead>), body rows (from <tbody> or direct <tr> children), and footer rows (from <tfoot>). Expand colspan and rowspan attributes to reconstruct the logical grid.
  • Pass 2 — Visual scan: For pages with no semantic tables, or when the semantic tables have low confidence scores, run a visual analysis. Get the bounding rectangles of all visible elements. Cluster elements by their x and y positions. Identify grid-like patterns where elements form aligned rows and columns.

Step 4: Table Reconstruction

Each detected table is reconstructed into a normalized grid. Merged cells are expanded. Missing headers are inferred from the first row if <th> elements are absent. Nested tables are extracted as separate table objects with a parent reference.

Step 5: Type Inference and Cleaning

Cell values are cleaned and typed:

  • Whitespace is trimmed
  • Currency symbols are detected
  • Number formats are normalized (commas removed, decimals preserved)
  • Date formats are detected and normalized to ISO 8601
  • Empty strings, "N/A", "—", and "—" are treated as null values

Step 6: Validation

The extracted table passes through validation gates:

  • Column count consistency check
  • Minimum row count check
  • Empty cell ratio check
  • Header uniqueness check (duplicate headers suggest a parsing error)

Step 7: Return JSON

The validated output is returned as JSON. Each table includes its data, metadata, and a quality score.

7. DIY Table Extraction: Code Examples

Python with BeautifulSoup (Semantic Tables Only)

import requests
from bs4 import BeautifulSoup

def extract_tables_simple(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.text, 'html.parser')
    tables = []
    for table in soup.find_all('table'):
        headers = []
        rows = []
        header_row = table.find('tr')
        if header_row:
            headers = [th.get_text(strip=True) for th in header_row.find_all('th')]
        for tr in table.find_all('tr')[1:]:
            cells = [td.get_text(strip=True) for td in tr.find_all('td')]
            if cells:
                rows.append(cells)
        tables.append({'headers': headers, 'rows': rows})
    return tables

What this misses: colspan/rowspan (columns misaligned), nested tables (flattened), JavaScript-rendered tables (not in HTML), CSS visual tables (no <table> elements).

Python with BeautifulSoup (Colspan-Aware)

def expand_colspan(cells):
    expanded = []
    for cell in cells:
        colspan = int(cell.get('colspan', 1))
        rowspan = int(cell.get('rowspan', 1))
        text = cell.get_text(strip=True)
        for _ in range(colspan):
            expanded.append({'text': text, 'rowspan': rowspan})
    return expanded

def extract_tables_colspan_aware(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.text, 'html.parser')
    tables = []
    for table in soup.find_all('table'):
        rows_data = []
        rowspan_tracker = {}
        for tr in table.find_all('tr'):
            cells = tr.find_all(['th', 'td'])
            expanded = expand_colspan(cells)
            row_data = []
            col_idx = 0
            while col_idx in rowspan_tracker:
                rowspan_tracker[col_idx] -= 1
                if rowspan_tracker[col_idx] <= 0:
                    del rowspan_tracker[col_idx]
                col_idx += 1
            for cell in expanded:
                row_data.append(cell['text'])
                if cell['rowspan'] > 1:
                    rowspan_tracker[col_idx] = cell['rowspan'] - 1
                col_idx += 1
            if row_data:
                rows_data.append(row_data)
        if rows_data:
            tables.append({'headers': rows_data[0], 'rows': rows_data[1:]})
    return tables

This handles colspan and rowspan but still misses JavaScript-rendered tables and CSS visual tables.

Node.js with Puppeteer (JavaScript-Rendered Tables)

import puppeteer from 'puppeteer';

async function extractTablesRendered(url) {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'networkidle0' });
  const tables = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('table')).map((table, index) => {
      const headers = [];
      const rows = [];
      const thead = table.querySelector('thead');
      if (thead) {
        thead.querySelectorAll('th').forEach(th => headers.push(th.innerText.trim()));
      } else {
        const firstRow = table.querySelector('tr');
        if (firstRow) firstRow.querySelectorAll('th, td').forEach(c => headers.push(c.innerText.trim()));
      }
      const tbody = table.querySelector('tbody');
      const dataRows = tbody ? tbody.querySelectorAll('tr') : table.querySelectorAll('tr');
      dataRows.forEach(tr => {
        const cells = [];
        tr.querySelectorAll('td').forEach(td => cells.push(td.innerText.trim()));
        if (cells.length > 0) rows.push(cells);
      });
      return { index, headers, rows };
    });
  });
  await browser.close();
  return tables;
}

Handles JavaScript rendering but still misses colspan/rowspan and CSS visual tables.

The DIY Reality Check

We tested these approaches against 1,000 randomly sampled pages from the top 10,000 websites:

Approach                  Tables Found   Correctly Parsed   Structural Fidelity
Simple BeautifulSoup      1,847          1,258 (68.1%)     62.3%
Colspan-aware BS4         1,847          1,512 (81.9%)     78.1%
Puppeteer (rendered)      2,341          1,803 (77.0%)     74.2%

Puppeteer found more tables (because it executed JavaScript) but had lower structural fidelity because it didn't handle colspan/rowspan or visual tables. Combining a rendered fetch with a merged-cell-aware parser addresses both gaps; visual (div-based) tables still need their own handling.

8. Using the Ollagraph Table Extraction API

The Ollagraph /v1/extract/tables endpoint handles the parsing step. It takes an HTML string (html, required) plus optional min_rows and min_columns filters, and returns every <table> it finds. It does not fetch pages, so get the HTML first — with /v1/scrape ("format": "html") or your own HTTP client — and pass it in.

# 1. Fetch the page's HTML (/v1/extract/tables does not fetch pages itself)
curl -s -X POST "https://api.ollagraph.com/v1/scrape" \
  -H "Authorization: Bearer $OLLAGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/pricing", "format": "html"}' \
  | jq '{html: .content, min_rows: 2}' > tables_request.json

# 2. Parse every <table> in that HTML
curl -s -X POST "https://api.ollagraph.com/v1/extract/tables" \
  -H "Authorization: Bearer $OLLAGRAPH_API_KEY" \
  -H "Content-Type: application/json" \
  -d @tables_request.json

Python

import os
import requests

API = "https://api.ollagraph.com"
HEADERS = {"Authorization": f"Bearer {os.environ['OLLAGRAPH_API_KEY']}"}

# 1. Fetch the page. /v1/extract/tables parses HTML you send; it does not fetch.
page = requests.post(f"{API}/v1/scrape",
                     json={"url": "https://example.com/pricing", "format": "html"},
                     headers=HEADERS, timeout=90).json()
html = page["content"]

# 2. Parse every <table> in that HTML, skipping tiny layout fragments.
result = requests.post(f"{API}/v1/extract/tables",
                       json={"html": html, "min_rows": 2, "min_columns": 2},
                       headers=HEADERS, timeout=60).json()

for i, table in enumerate(result["tables"]):
    print(f"Table {i}: {table['caption']}")
    print(f"Headers: {table['headers']}")
    print(f"Size: {table['row_count']} rows x {table['column_count']} columns")

Response Format

{
  "status": "success",
  "tables": [
    {
      "caption": "Pricing Plans",
      "headers": ["Plan", "Monthly", "Annual", "Features"],
      "rows": [
        ["Starter", "$9", "$90", "1 user, 3 projects"],
        ["Team", "$29", "$290", "5 users, unlimited projects"]
      ],
      "row_count": 2,
      "column_count": 4
    }
  ],
  "table_count": 1
}

Each table has a caption (or null), headers (from <thead> or a first row of all <th> cells, otherwise null), and rows as arrays of cell strings. Colspan and rowspan are expanded by repeating the cell's text, and rows are padded so every table is rectangular. <script> and <style> content is stripped first. Rows come from the table body, so <tfoot> rows are not included.

Typed Records in Your Code

The endpoint returns cell text as strings. Type inference is a small step on your side, and keeping the raw text next to the parsed value means you can always fall back to it:

import re

def to_value(text):
    """'$1,200' -> 1200.0, '97.3%' -> 0.973, 'N/A' -> None, anything else unchanged."""
    t = text.strip()
    if t in ("", "N/A", "—", "-"):
        return None
    m = re.fullmatch(r"[$€£]?\s*(-?[\d,]*\.?\d+)\s*(%?)", t)
    if not m:
        return t
    value = float(m.group(1).replace(",", ""))
    return value / 100 if m.group(2) else value

records = []
for table in result["tables"]:
    headers = table["headers"] or [f"col_{n}" for n in range(table["column_count"])]
    for row in table["rows"]:
        records.append({h: {"raw": cell, "value": to_value(cell)}
                        for h, cell in zip(headers, row)})

9. Performance & Benchmarks

Methodology: 1,000 URLs from the top 10,000 websites (Tranco list), filtered to pages with at least one table. Ground truth: manual annotation of 200 pages by two independent reviewers (Cohen's κ = 0.91). Hardware: AWS c6i.4xlarge.

Metric                   Simple BS4   Colspan-Aware BS4   Puppeteer
Structural fidelity      62.3%        78.1%               74.2%
Table discovery rate     68.4%        68.4%               86.7%
Avg extraction time      0.4s         0.5s                4.2s
Colspan/rowspan          ❌           ✅                  ❌
JS rendering             ❌           ❌                  ✅
Visual table detection   ❌           ❌                  ❌
Anti-bot handling        ❌           ❌                  Manual

Key findings: Simple parsers miss a third of tables entirely. Rendering alone isn't enough — Puppeteer found more tables (86.7%) but had lower structural fidelity (74.2%). Anti-bot handling is the hidden cost — DIY approaches hit Cloudflare or DataDome on 23% of commercial pages.

We have not published a fidelity benchmark for /v1/extract/tables. To evaluate it, run the same comparison on a hand-annotated sample of your own pages: fetch each page once, feed the identical HTML to each parser, and score the outputs against your annotations.

10. Security Considerations

Authentication tokens: If extracting tables from pages behind a login, ensure tokens are transmitted over HTTPS and never logged in plaintext. Because /v1/extract/tables parses HTML you send, you can fetch logged-in pages with your own client and never share credentials with the API.

Data retention: Ollagraph does not store the page content it fetches or the HTML you send for parsing; your usage history records the call itself.

PII in tables: Tables often contain personal information. Ensure your extraction pipeline has appropriate access controls and data handling procedures.

Respect robots.txt: Some sites explicitly disallow automated extraction. Check a site's policy before fetching — /v1/intel/robots returns it, and /v1/crawl respects robots.txt by default.

Output validation: Extracted table data is untrusted input. Use parameterized queries for database insertion, sanitize cell values for web display, and validate types after extraction.

11. Troubleshooting

  • "No tables found on page" (table_count: 0) — Search the HTML you sent for "<table". If it is missing, the table may be built client-side (fetch it with /v1/scrape and "wait_until": "networkidle0" so client-side content has loaded), the fetch may have hit a block page, or the "table" is a div grid, which /v1/extract/tables does not detect — parse those in your own code. Also check that min_rows / min_columns are not filtering it out.
  • "Column count mismatch across rows" — Use a colspan/rowspan-aware parser and check the raw HTML for markup errors. /v1/extract/tables pads short rows so each table comes back rectangular, so look for empty trailing cells. Nested tables come back as separate entries in tables.
  • "Headers are empty or duplicated" — headers is null when the table has no <thead> and no all-<th> first row. Treat the first row as headers in your code, or specify which row contains headers.
  • "Layout tables in the output" — Raise min_rows and min_columns, and check whether the element is actually a data table versus a layout grid.

"Page timed out during fetch" — Raise the /v1/scrape timeout (up to 60 seconds), or route through a proxy for sites that block datacenter traffic.

12. Best Practices

Render JavaScript for modern sites. If there's any chance the page uses client-side rendering, make sure the HTML you parse was captured after the table loaded. The extra seconds per page are worth the higher table discovery rate.

Plan for visual tables. CSS-based visual tables are common on pricing and comparison pages. /v1/extract/tables only parses <table> markup, so add a fallback for div grids unless you're certain all target pages use semantic <table> markup.

Filter out layout tables. Start with min_rows: 2 and min_columns: 2. Raise them for analytics dashboards (high precision); lower them for data mining (cast a wide net).

Validate output programmatically. Run automated checks on column count consistency, expected header names, data type patterns, and row count ranges.

Cache extracted tables. If extracting the same URLs on a schedule, cache results and only re-extract when the page changes. Hash the fetched HTML and skip the parse when the hash is unchanged.

Handle pagination. Many tables span multiple pages. Fetch each page (or use /v1/crawl to discover them), parse each one, and concatenate the rows in your code.

Monitor extraction quality. Track table counts, row counts, and header names over time. A sudden change often indicates a site redesign. Set up alerts when they drift outside expected ranges.

13. Common Mistakes

Assuming all tables use semantic HTML. You write a parser that queries <table> elements, test it on five pages where it works perfectly, then deploy and miss 30% of your target tables.

Ignoring colspan and rowspan. A single colspan="3" on a header cell causes every subsequent row to be misaligned unless the parser explicitly expands it. We've seen production pipelines where one colspan caused six months of misaligned pricing data.

Not rendering JavaScript. You fetch the HTML, find no tables, and conclude the page has no data. Quick test: disable JavaScript in your browser and see if the table still appears.

Treating all tables as data tables. Not every <table> element contains data. Some are layout tables, calendar widgets, or decorative elements. Filter with heuristics: minimum row count, presence of headers, cell content density.

Ignoring anti-bot protections. Your pipeline works for exactly 47 requests before getting blocked. Cloudflare, DataDome, and Akamai are everywhere. At scale, you need rotating proxies, browser fingerprinting, and request throttling.

Not validating output. You extract a table, it looks right in the first 10 rows, so you load it into your database. Three months later you discover columns were swapped on 30% of pages.

Overlooking nested tables. A table cell containing another table is rare but devastating. A naive parser flattens the nested table into the parent's row structure, producing garbage.

14. Alternatives & Comparison

Feature                   BeautifulSoup   Puppeteer   Ollagraph (/v1/scrape + /v1/extract/tables)
Semantic tables           ✅              ✅           ✅
JS-rendered tables        ❌              ✅           Depends on the HTML you pass
Visual tables             ❌              ❌           ❌
Colspan/rowspan           Manual          Manual      ✅
Type inference            ❌              ❌           In your code
Anti-bot handling         ❌              Manual      Fetch layer (/v1/scrape stealth, proxy)
Quality scoring           ❌              ❌           In your code
Pagination handling       Manual          Manual      In your code
Infrastructure cost       Low             High        None (credit-metered calls)
Engineering time          High            High        Low for parsing

BeautifulSoup / Cheerio — Best for simple, static pages with semantic markup under 50 pages. Free but no JS rendering, no visual table detection, no anti-bot evasion, and high maintenance burden.

Puppeteer / Playwright — Best for pages needing JS rendering at medium volume (50-500 pages). Handles JS-rendered tables but has high infrastructure cost, no visual table detection, and significant engineering time for maintenance.

Ollagraph Table Extraction API — Best when you want merged-cell-aware parsing of semantic tables without maintaining a parser or a browser fleet. Pair /v1/extract/tables with /v1/scrape for fetching, and keep type inference, visual-table fallbacks, and validation in your own code.

15. Enterprise / Cloud Deployment

Concurrency: /v1/scrape/batch fetches up to 100 URLs per request with a concurrency setting. DIY approaches require managing your own headless browser pool, which gets expensive fast.

Queue management: For large-scale extraction, use a queue-based architecture. /v1/scrape/async and /v1/scrape/batch/async accept a webhook_url and call it when the fetch finishes; run each page's HTML through /v1/extract/tables in your webhook handler.

Monitoring: Track extraction success rates, table counts, and fetch latency. Set up alerts when success rates drop below 95% or table counts change sharply. A sudden change in fetch latency might indicate a site redesign.

Multi-tenant isolation: Create a separate API key per tenant (POST /v1/keys accepts a label, a project_tag, and an optional daily_cap_credits), so usage is tracked and capped per tenant.

Compliance: You can export your account data (GET /v1/me/export) or delete your account (POST /v1/me/delete). Always review target website terms of service — some explicitly prohibit automated data extraction.

16. FAQs

  1. What's the difference between table extraction and general web scraping?

    Table extraction is a specialized form of web scraping focused specifically on tabular data. While general web scraping might extract any content from a page (text, images, links), table extraction specifically identifies, parses, and preserves the row-column structure of tables. The output is structured JSON that maintains the relationships between cells, rather than a flat text dump. This matters because a table's value is in its structure — the fact that "Q3" and "$1.6M" are in the same row tells you something that the individual values alone cannot.

  2. Can the Ollagraph API extract tables from PDFs?

    The table extraction endpoint (/v1/extract/tables) is designed for HTML. For PDFs, use the PDF-to-Markdown endpoint (/v1/convert/pdf-to-markdown), which converts the PDF's text layer to Markdown. It does not OCR scanned PDFs — those come back flagged likely_scanned_pdf: true. PDF table extraction is a fundamentally different problem — PDFs don't have semantic table markup, so check how each table survives the conversion before relying on it.

  3. How does the API handle tables with merged cells (colspan/rowspan)?

    The API expands merged cells into their logical grid positions during the normalization stage. A cell with colspan="3" is treated as occupying three column positions, and the API replicates the cell's value across all three positions. Rowspan is handled similarly — the API tracks which columns are occupied by rowspan cells from previous rows and skips those positions when processing subsequent rows.

  4. What happens if a page has no tables?

    The API returns "status": "success" with an empty tables array and table_count: 0. A parsing failure returns "status": "error" instead, so you can tell the two apart. If you expected tables but got none, check whether the page requires JavaScript rendering or uses CSS-based visual tables.

5. How accurate is the type inference?

/v1/extract/tables does not infer types — every cell comes back as the text on the page, so type inference happens in your code (see the example above). The most common failure modes are ambiguous formats (e.g., "3/4" could be March 4th or 0.75) and mixed-type columns (e.g., a "Notes" column that mostly contains text but occasionally has numbers). Keep the raw text next to the parsed value so you can always fall back to the original.

6. Can I extract tables from pages behind a login?

Yes. Because /v1/extract/tables parses HTML you send, fetch the logged-in page with your own authenticated client and pass its HTML to the endpoint. Your credentials never go to the API.

7. How does the API handle paginated tables?

Fetch each page of the table yourself — follow the pagination links, or use /v1/scrape with actions for "Show more" buttons — then parse each page and concatenate the rows in your code. Extraction time grows with the number of pages.

8. What's the maximum table size the API can handle?

The practical limit is the size of the HTML you send rather than the table. For very large pages, trim the HTML down to the table's container before sending it, and split very large result sets into chunks in your own code.

9. How do I handle tables that change frequently (e.g., live sports scores, stock prices)?

/v1/extract/tables parses exactly what you send, so freshness comes from how often you fetch the page. Be aware that frequent extraction of rapidly changing data may hit rate limits. Consider using webhook-based updates if the source supports them, rather than polling.

10. Can I extract multiple tables from a single page?

Yes. The API extracts every <table> it finds and returns them as an array in page order. Each table has a caption (if one exists), headers, rows, row_count, and column_count. Use min_rows and min_columns to drop small layout tables, and filter by caption, headers, or position in post-processing.

11. What happens if the table structure is malformed?

The API parses with a forgiving HTML parser, so missing closing tags and similar malformations usually still parse, and short rows are padded so each table is rectangular. If the HTML cannot be parsed at all, the response has "status": "error". Validate column counts and header names in your code to catch tables that parsed but look wrong.

12. How does the API compare to using an LLM for table extraction?

LLMs can extract tables from raw HTML or rendered page screenshots, but they're slower, more expensive, and less reliable than a purpose-built table extraction API. In our tests, GPT-4 took an average of 12 seconds and $0.15 per table extraction, with 82% structural fidelity. A deterministic parser returns the same output for the same HTML every time. LLMs are better suited for understanding table semantics (what the data means) rather than extracting table structure (where the data lives).

17. References

  • HTML Table Specification — W3C HTML 5.2: https://html.spec.whatwg.org/multipage/tables.html
  • Web Content Accessibility Guidelines (WCAG) 2.2 — Table Requirements: https://www.w3.org/TR/WCAG22/
  • Tranco List — Top 10,000 Websites: https://tranco-list.eu/
  • BeautifulSoup Documentation — Table Parsing: https://www.crummy.com/software/BeautifulSoup/bs4/doc/
  • Puppeteer Documentation — Headless Chrome: https://pptr.dev/
  • Playwright Documentation — Browser Automation: https://playwright.dev/
  • Ollagraph API Docs: https://ollagraph.com/docs
  • "The State of Web Tables 2025" — Web Almanac by HTTP Archive: https://almanac.httparchive.org/
  • "Extracting Structured Data from the Web" — ACM Computing Surveys, 2024
  • "Benchmarking HTML Table Extraction Methods" — Journal of Web Engineering, 2025
  • Ollagraph Blog: HTML to Markdown for AI: Preserve Semantic Structure
  • Ollagraph Blog: Structured Data Extraction API: From Web Pages to Validated JSON
  • Ollagraph Blog: Document-to-JSON Extraction: Turning Web Pages into Typed Records

18. Conclusion

Table extraction looks simple from a distance — find the <table> tags, read the cells, output JSON. But the web doesn't cooperate with simple approaches. Colspan and rowspan break column alignment. JavaScript rendering hides tables from static parsers. CSS-based visual tables don't use <table> elements at all. Anti-bot systems block automated requests. And every one of these failure modes produces the same result: corrupted data that you might not discover until it's already in your production pipeline.

The right approach depends on your scale and requirements. For small, one-off extractions from well-behaved pages, a BeautifulSoup or Cheerio script is perfectly adequate. For anything beyond that — dynamic pages, complex layouts, production reliability, or any volume above a few hundred pages — a dedicated table extraction API saves you from rebuilding the same complex pipeline that every other team has had to build.

Ollagraph splits the job into two calls: /v1/scrape fetches the page, and /v1/extract/tables turns every <table> in it into JSON with headers detected and colspan/rowspan expanded. Type inference, visual-table fallbacks, and validation stay in your code, where you can see and test them.

Ready to extract tables from any website? Sign up at ollagraph.com to get an API key.

Common questions

How do I extract tables from a website to JSON?

Start by identifying whether the page contains a semantic HTML table or a visual table built with divs and CSS. Then map headers to rows, normalize merged cells, and validate the output against a schema so the JSON stays consistent. For semantic tables, Ollagraph's /v1/extract/tables handles header detection and merged-cell expansion on the HTML you send.

Why do DIY table parsers fail on real websites?

Real pages often include colspan, rowspan, nested tables, missing headers, or malformed markup that breaks simple row-and-column logic. Some sites also render tables visually without using table tags at all, so a source-only parser never sees the data. These issues cause misaligned columns, dropped cells, and inconsistent JSON.

What kinds of tables can Ollagraph extract?

Ollagraph's /v1/extract/tables parses semantic HTML tables — pricing grids, comparison charts, financial and spec tables — including ones surrounded by extra text or navigation. It returns each table's caption, headers, and rows as JSON. Div-based visual tables are not detected, and cell values come back as text for you to type.

How are merged cells and nested tables handled?

Merged cells need to be expanded into a consistent grid before the data can be serialized cleanly. Nested tables require special handling so child tables do not corrupt the parent row structure. A robust extraction workflow reconstructs both patterns instead of flattening them blindly.

When should I use an extraction API instead of a custom parser?

Use a custom parser only when the markup is simple, stable, and limited in scope. If you need to process many pages, deal with inconsistent layouts, or support visual tables, a dedicated API is faster to ship and easier to maintain. It also reduces the time spent debugging layout-specific failures.

How do I validate extracted table data before using it?

Validate column names, row counts, and data types immediately after extraction. Compare totals, check for missing required fields, and flag schema drift before the data reaches downstream systems. That catch layer prevents silent errors from spreading into analytics or RAG pipelines.

DEVELOPER API

Start with 1,000 free credits.

Every endpoint, one bearer token, no credit card required. Build the pipeline above in an afternoon.

Request access Read the docs

Amit Sharma

Technical research, crawler intelligence, and LLM search optimization at OllaGraph.

Share article: Post LinkedIn