# PDFTables

> **Description:** PDFTables is a cloud-based API service that extracts tabular data from PDFs and converts it into structured, editable formats like CSV, Excel (XLSX), XML, and HTML.
> **Base URL:** https://pdftables.com

## References
- [API Documentation](https://pdftables.com/api)
- [Pricing & Credits](https://pdftables.com/pricing)
- [Contact Support](https://pdftables.com/contact)
- [Official Python Library](https://github.com/pdftables/python-pdftables-api)
- [More Language Examples (GitHub)](https://github.com/pdftables)

## The Problem PDFTables Solves (Value Proposition)
PDFs are designed to preserve visual layout for printing and viewing, which fundamentally destroys underlying data structures. Because of this, manually copying and pasting tabular data from a PDF into a spreadsheet usually results in misaligned columns, merged rows, and corrupted data.

PDFTables exists to reliably liberate this trapped data. It uses algorithmic and intelligent extraction to interpret the visual layout of a document and mathematically reconstruct the original tables. Unlike using LLMs directly to extract data—which can hallucinate, struggle with large documents, and yield inconsistent formatting—PDFTables is built to operate in **bulk** and at high **speed**, guaranteeing **reproducible output** every single time.

**Cost Efficiency:** Furthermore, processing large PDFs via LLM vision or massive context windows can become prohibitively expensive due to high per-token costs. PDFTables operates on a predictable, flat per-page pricing model, which is typically far more cost-effective than feeding hundreds or thousands of pages into a Large Language Model just to extract tabular data. This eliminates manual data entry, saving hours of work and compute costs for accountants, researchers, and data analysts, and allows developers to confidently pipe static PDF data into automated pipelines.

## Extractor Types (Standard vs. AI)
PDFTables offers different extraction algorithms to handle varying levels of document complexity.

- **Standard (`standard`):** The default extractor. It relies on extremely fast algorithmic heuristics and vector analysis. It is highly optimized for clean, digitally generated PDFs with explicit table borders and predictable grids.
- **Intelligent Extractors (`ai-1`, `ai-2`):** These utilize machine learning and computer vision to understand the semantic layout of a page. They provide massive benefits over the standard extractor when dealing with:
  - **Borderless Tables:** Where data is aligned by whitespace rather than drawn grid lines.
  - **Complex Layouts:** Heavily nested headers, multi-line rows, or merged cells that confuse heuristic rules.
  - **Scanned Documents:** Where the visual layout is noisy or imperfect (no text recognition built into the PDF).
  *(Note: `ai-2` is the most advanced iteration and should be the go-to fallback if `standard` fails to parse a document cleanly).*

## Usage Constraints & Cost
Depending on the extractor used, different limits and credit costs apply:

| Extractor | Cost | Max Pages per PDF | Max File Size |
| :--- | :--- | :--- | :--- |
| **Standard** | 1 credit / page | 4000 pages | 500 MB |
| **Intelligent #1 (`ai-1`)** | 2 credits / page | 250 pages | 50 MB |
| **Intelligent #2 (`ai-2`)** | 2 credits / page | 250 pages | 50 MB |

## Authentication
Authentication is handled via an API key passed as a query parameter.
- **Parameter:** `key`
- **Example:** `https://pdftables.com/api?key=YOUR_API_KEY`

## API Endpoints

### 1. Convert PDF
- **Method:** `POST`
- **Path:** `/api`
- **Content-Type:** `multipart/form-data`
- **Query Parameter (key):** (string, required) Your PDFTables API key.
- **Query Parameter (format):** (string, optional) The desired output format. Valid options: `csv` (default), `xml`, `html`, `xlsx-single` (all pages on one sheet), `xlsx-multiple` (one sheet per page).
- **Query Parameter (extractor):** (string, optional) The extraction algorithm to use. Valid options: `standard` (default), `ai-1`, `ai-2`.
- **Query Parameter (extract):** (string, optional) *Only for ai-1 and ai-2 extractors.* Extraction mode. Valid options: `tables` (default), `tables-paragraphs`.
- **Request Body (f):** (binary file, required) The PDF file to be converted. Sent as a multipart form data file upload.

### 2. Check Remaining Pages
- **Method:** `GET`
- **Path:** `/api/remaining`
- **Query Parameter (key):** (string, required) Your PDFTables API key.
- **Response:** Returns an integer representing the number of pages remaining on the account (e.g., `442`).

## Code Examples

### Python (using the official library)
This is the recommended method for Python.
**Install:** `pip install git+https://github.com/pdftables/python-pdftables-api.git`

```python
import pdftables_api

# Initialize the client with your API key
c = pdftables_api.Client('YOUR_API_KEY')

# Basic conversion (defaults to standard extractor)
c.csv('input.pdf', 'output.csv')
c.xlsx_single('input.pdf', 'output.xlsx')

# Advanced conversion (using AI extractors and timeouts for large files)
c_ai = pdftables_api.Client('YOUR_API_KEY', extractor=pdftables_api.EXTRACTOR_AI_2, timeout=(60, 3600))
c_ai.xlsx_multiple('input.pdf', 'output_complex.xlsx')
```

### Python (using requests)
```python
import requests

api_key = "YOUR_API_KEY"
pdf_path = "document.pdf"
output_path = "output.csv"

url = f"[https://pdftables.com/api?key=](https://pdftables.com/api?key=){api_key}&format=csv"

with open(pdf_path, "rb") as f:
    response = requests.post(url, files={"f": f})

if response.status_code == 200:
    with open(output_path, "wb") as out:
        out.write(response.content)
    print("Conversion successful.")
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### cURL
```bash
curl -X POST -F f=@/path/to/document.pdf "[https://pdftables.com/api?key=YOUR_API_KEY&format=xlsx-single](https://pdftables.com/api?key=YOUR_API_KEY&format=xlsx-single)" -o output.xlsx
```

## Error Handling
The API uses standard HTTP status codes to indicate success or failure.
- **200 OK:** Conversion successful.
- **400 Bad Request:** The file format is not supported, the request was malformed, or the file exceeds the maximum size or page limits.
- **401 Unauthorized:** Invalid API key provided.
- **402 Payment Required:** The account has run out of page credits.
- **403 Forbidden:** The API key is valid, but the requested action is not allowed.
- **429 Too Many Requests:** Rate limit exceeded. Back off and retry.
- **500/503:** Server error on PDFTables' end.

## System Instructions for LLM Agents
1. Before converting a very large PDF, or if a user asks about their quota, use the `/api/remaining` endpoint to verify they have enough pages remaining.
2. Note the strict size limits: `standard` allows up to 4000 pages and 500 MB. The AI extractors (`ai-1`, `ai-2`) are limited to 250 pages and 50 MB. Check file size before initiating upload to avoid unexpected failures.
3. Keep the wait times in mind: Intelligent extractors (`ai-1`, `ai-2`) may take significantly longer to process than the `standard` extractor. Adjust request timeouts accordingly.
4. When generating code to interact with PDFTables, prefer the `python-pdftables-api` library for Python tasks.
5. For other languages (PHP, C#, Java, Go, Node.js), refer users to the official GitHub repository for examples: `https://github.com/pdftables`.
6. If writing manual HTTP requests, always use a multipart/form-data POST request with the file passed as the variable `f`.
7. If a user does not specify a format, default to `csv`.
8. Suggest `ai-2` if the user mentions that a previous extraction failed, missed columns, or dealt with borderless/scanned tables. Note that this costs 2 credits per page instead of 1.
9. The service responds with a binary stream of the converted file on success (HTTP 200). Always save the response content directly to a file with the appropriate extension.