Name: Document & Data API
Brand: quickpod
SKU: api-quickpod-aiquck-document
Availability: InStock
Author: API Market

Anil Singh

# Document & Data API

## Overview

The Document & Data API provides powerful and flexible tools for document parsing and data transformation across various formats, including PDFs, HTML, files, and structured data like XML, JSON, and CSV. This API is designed to streamline data processing workflows by enabling easy conversion, extraction, and normalization of diverse data types into consistent and manageable formats.

Whether you need to extract text and tables from PDFs, clean and make HTML content readable, detect file types, or convert between XML, JSON, and CSV, this API offers a robust solution. It's ideal for normalizing disparate data feeds, integrating with legacy systems, enhancing import pipelines, and automating data processing tasks that demand predictable data structures.

## Features

- **PDF Text Extraction:** Accurately extract full text content from PDF documents, page by page, while preserving character-level fidelity.
- **PDF Table Extraction:** Identify and extract structured tables from PDFs, presenting them as arrays of rows and cells for easy consumption.
- **HTML Text Stripping:** Clean HTML documents, removing navigation, boilerplate, and advertisements to obtain plain, readable text.
- **HTML Readability Enhancement:** Utilize advanced algorithms to extract the main article content and title from any HTML page, focusing on human readability.
- **File Type Detection:** Precisely identify the true MIME type, description, and extension of any uploaded file by inspecting its magic bytes.
- **CSV to JSON Conversion:** Transform CSV strings into JSON arrays of objects, automatically using the header row as keys.
- **JSON to CSV Conversion:** Convert JSON arrays of objects into CSV strings, complete with an auto-generated header row.
- **XML to JSON Transformation:** Parse XML documents into equivalent JSON structures, meticulously preserving element attributes and text content.
- **JSON to XML Serialization:** Serialize JSON objects into well-formed XML documents, allowing for configurable root tag names.

## Use Cases

- **Data Integration & ETL Pipelines:** Normalize incoming data feeds from various sources (e.g., partners providing XML, internal systems exporting CSV, web scraping yielding HTML) into a unified JSON format for easier processing, storage, and analysis in ETL (Extract, Transform, Load) pipelines. This is crucial for data warehouses and business intelligence applications.
- **Content Management Systems (CMS):** Automate the ingestion of external content by extracting clean, readable text from uploaded PDF documents or external HTML articles. Use the API to strip boilerplate from web content before storing it in a CMS, improving searchability and display consistency.
- **Legacy System Modernization:** Bridge the gap between older systems that rely on XML or CSV and modern applications that prefer JSON. This API facilitates seamless communication and data exchange, reducing the complexity and development effort required for integrating disparate technologies.
- **Regulatory Compliance & Reporting:** Extract specific data points or tables from standardized PDF reports for compliance checks or automated report generation. Convert complex data formats into easily auditable CSV or JSON structures for regulatory submissions.
- **Developer Tooling & Middleware:** Provide consistent data structures within backend services and developer tools. For instance, a backend service receiving various document types can use this API to transform them into a standardized JSON payload before passing them to downstream microservices, ensuring predictable input for all components.

## Pricing

- 1 API unit equals 1 image processed.
- Different pricing tiers are available based on usage volume.

## API Documentation

### Base URL

All API requests should be made to: `https://prod.api.market/api/v1/quickpod/aiquck-document`

### Authentication

Authentication is handled via API key. Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Endpoints

#### Service health check

Check the health status of the API.

`GET /api/v1/quickpod/aiquck-document/health`

**Headers:**
- `x-api-market-key` (string, required): Your API.market API Key.

**Responses:**
- **200 OK:**
    ```json
    {
      "ok": true,
      "service": "document-data-api"
    }
    ```

**cURL Example:**
```bash
curl -X GET "https://prod.api.market/api/v1/quickpod/aiquck-document/health" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

#### Extract text from every page of a PDF file

Extracts full text content from a PDF, page by page, with character-level fidelity.

`POST /api/v1/quickpod/aiquck-document/v1/pdf/text`

**Request Body (`multipart/form-data`):**
- `file` (binary, required): PDF file (max 20 MB).

**Responses:**
- **200 OK:** Extracted text per page and combined full text.
    ```json
    {
      "pages": 2,
      "text": "This is page 1 content.\nThis is page 2 content.",
      "pages_detail": [
        {
          "page": 1,
          "text": "This is page 1 content."
        },
        {
          "page": 2,
          "text": "This is page 2 content."
        }
      ]
    }
    ```
- **413 Payload Too Large:** File exceeds 20 MB limit.
- **422 Unprocessable Entity:** Request validation failed.

**cURL Example:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquck-document/v1/pdf/text" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -F "file=@/path/to/your/document.pdf"
```

#### Extract tables from a PDF as arrays of row arrays

Extracts all tables from a PDF as structured arrays of rows and cells.

`POST /api/v1/quickpod/aiquck-document/v1/pdf/tables`

**Request Body (`multipart/form-data`):**
- `file` (binary, required): PDF file (max 20 MB).

**Responses:**
- **200 OK:** All tables found across all pages.
    ```json
    {
      "table_count": 1,
      "tables": [
        {
          "page": 1,
          "table_index": 0,
          "rows": [
            ["Header 1", "Header 2"],
            ["Data A", "Data B"]
          ]
        }
      ]
    }
    ```
- **413 Payload Too Large:** File exceeds 20 MB limit.
- **422 Unprocessable Entity:** Request validation failed.

**cURL Example:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquck-document/v1/pdf/tables" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -F "file=@/path/to/your/document.pdf"
```

#### Extract clean readable text from HTML, stripping navigation and boilerplate

Strips an HTML document to plain readable text, removing navigation and boilerplate.

`POST /api/v1/quickpod/aiquck-document/v1/html/text`

**Request Body (`application/json`):**
- `html` (string, required): Raw HTML string.
- `url` (string, optional): Optional canonical URL to improve extraction quality.

**Responses:**
- **200 OK:** Extracted plain text and character count.
    ```json
    {
      "text": "This is the clean readable text from the HTML page.",
      "length": 50
    }
    ```
- **422 Unprocessable Entity:** Request validation failed.

**cURL Example:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquck-document/v1/html/text" \
     -H "Content-Type: application/json" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -d '{
           "html": "<html><body><h1>Title</h1><nav>...</nav><p>This is the main content.</p></body></html>",
           "url": "http://example.com/article"
         }'
```

#### Extract main article content and title from HTML using readability algorithms

Extracts the main article content and title from an HTML page using readability algorithms.

`POST /api/v1/quickpod/aiquck-document/v1/html/readable`

**Request Body (`application/json`):**
- `html` (string, required): Raw HTML string.
- `url` (string, optional): Optional canonical URL.

**Responses:**
- **200 OK:** Article title, short title, and cleaned content.
    ```json
    {
      "title": "Article Title",
      "short_title": "Title",
      "content": "<p>This is the main article content after readability processing.</p>",
      "length": 75
    }
    ```
- **422 Unprocessable Entity:** Request validation failed.

**cURL Example:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquck-document/v1/html/readable" \
     -H "Content-Type: application/json" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -d '{
           "html": "<html><body><header>...</header><h1>My Article</h1><article><p>Content here.</p></article><footer>...</footer></body></html>",
           "url": "http://example.com/article"
         }'
```

#### Detect the true MIME type of a file by inspecting its magic bytes

Detects the true MIME type and description of any uploaded file by inspecting its bytes.

`POST /api/v1/quickpod/aiquck-document/v1/file/type`

**Request Body (`multipart/form-data`):**
- `file` (binary, required): The file to analyze.

**Responses:**
- **200 OK:** MIME type, description, and extension.
    ```json
    {
      "filename": "report.pdf",
      "mime_type": "application/pdf",
      "description": "PDF document, version 1.7",
      "extension": "pdf"
    }
    ```

**cURL Example:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquck-document/v1/file/type" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -F "file=@/path/to/your/file.jpg"
```

#### Convert a CSV string to a JSON array of objects keyed by the header row

Converts a CSV string to a JSON array of objects keyed by the header row.

`POST /api/v1/quickpod/aiquck-document/v1/csv/to-json`

**Request Body (`application/json`):**
- `csv` (string, required): The CSV string to convert. Example: `"name,age\nAlice,30\nBob,25"`
- `delimiter` (string, optional, default: `,`): The delimiter used in the CSV string.

**Responses:**
- **200 OK:** Parsed rows as JSON objects.
    ```json
    {
      "count": 2,
      "data": [
        {
          "name": "Alice",
          "age": "30"
        },
        {
          "name": "Bob",
          "age": "25"
        }
      ]
    }
    ```
- **422 Unprocessable Entity:** Request validation failed.

**cURL Example:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquck-document/v1/csv/to-json" \
     -H "Content-Type: application/json" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -d '{
           "csv": "name,age\nAlice,30\nBob,25",
           "delimiter": ","
         }'
```

#### Convert a JSON array of objects to a CSV string with auto-generated headers

Converts a JSON array of objects to a CSV string with an auto-generated header row.

`POST /api/v1/quickpod/aiquck-document/v1/json/to-csv`

**Request Body (`application/json`):**
- `data` (array of objects, required): The JSON array of objects to convert.
  Example: `[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]`
- `delimiter` (string, optional, default: `,`): The delimiter to use in the output CSV string.

**Responses:**
- **200 OK:** CSV text.
    ```csv
    name,age
    Alice,30
    Bob,25
    ```
- **422 Unprocessable Entity:** Request validation failed.

**cURL Example:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquck-document/v1/json/to-csv" \
     -H "Content-Type: application/json" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -d '{
           "data": [
             {"name": "Alice", "age": 30},
             {"name": "Bob", "age": 25}
           ],
           "delimiter": ","
         }'
```

#### Parse an XML document into a JSON object preserving attributes and text

Converts an XML document into a JSON object while preserving element attributes and text content.

`POST /api/v1/quickpod/aiquck-document/v1/xml/to-json`

**Request Body (`application/json`):**
- `xml` (string, required): The XML string to parse. Example: `"<root><item id=\"1\">hello</item></root>"`

**Responses:**
- **200 OK:** JSON representation of the XML tree.
    ```json
    {
      "root": "root",
      "data": {
        "item": {
          "@id": "1",
          "#text": "hello"
        }
      }
    }
    ```
- **422 Unprocessable Entity:** Request validation failed.

**cURL Example:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquck-document/v1/xml/to-json" \
     -H "Content-Type: application/json" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -d '{
           "xml": "<root><item id=\"1\">hello</item><item>world</item></root>"
         }'
```

#### Serialize a JSON object into a well-formed XML document

Serializes a JSON object into a well-formed XML document with a configurable root tag.

`POST /api/v1/quickpod/aiquck-document/v1/json/to-xml`

**Request Body (`application/json`):**
- `data` (object, required): The JSON object to convert to XML. Example: `{"name": "Alice", "age": 30}`
- `root` (string, optional, default: `"root"`): Root element tag name for the XML document.

**Responses:**
- **200 OK:** XML document string.
    ```xml
    <data>
      <name>Alice</name>
      <age>30</age>
    </data>
    ```
- **422 Unprocessable Entity:** Request validation failed.

**cURL Example:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquck-document/v1/json/to-xml" \
     -H "Content-Type: application/json" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -d '{
           "data": {
             "name": "Alice",
             "age": 30
           },
           "root": "data"
         }'
```

## Status Codes

- **200 OK:** Request successful. The API processed the request and returned the expected data.
- **201 Created:** Resource successfully created. (Not typically used by this API, but a standard code).
- **400 Bad Request:** Invalid input parameters or malformed request. Check your request body, headers, and parameters for correctness.
- **401 Unauthorized:** Missing or invalid API key. Ensure `x-api-market-key` header is present and contains a valid key.
- **403 Forbidden:** Valid API key but insufficient permissions. Your API key may not have the necessary access rights for the requested operation.
- **404 Not Found:** Resource not found. The requested endpoint path does not exist. Verify the URL.
- **422 Unprocessable Entity:** Request validation failed. The server understands the content type and the syntax of the request entity but was unable to process the contained instructions. Often indicates issues with the structure or values within the request body, such as missing required fields or incorrect data types.
- **429 Too Many Requests:** Rate limit exceeded. You have sent too many requests in a given amount of time. Implement exponential backoff for retries.
- **500 Internal Server Error:** Server-side error. An unexpected condition prevented the server from fulfilling the request. This typically indicates an issue on our end, but may be transient.
- **503 Service Unavailable:** Service temporarily unavailable. The server is currently unable to handle the request due to temporary overload or maintenance of the server. This is usually a temporary state.

## Rate Limits

Standard rate limits apply to prevent abuse and ensure fair usage for all customers. If you encounter a `429 Too Many Requests` error, you have exceeded your allocated rate limit. It is recommended to implement an exponential backoff strategy when retrying requests. Consult your API.market plan details for specific rate limit thresholds.

## Error Handling

Effective error handling is crucial for building robust applications. When an error occurs, the API will return an appropriate HTTP status code (e.g., 4xx for client errors, 5xx for server errors) and a JSON response body containing more details about the error.

**Interpreting Error Responses:**
Always check the HTTP status code of the response. For non-2xx status codes, parse the JSON response body. It typically includes an `error` object with:
- `code`: A machine-readable string identifying the error type.
- `message`: A human-readable description of the error.
- `status`: The HTTP status code.

**Common Errors & Resolution:**
- **400 Bad Request / 422 Unprocessable Entity:** These usually point to issues with your input. Carefully review the endpoint's request body schema and examples. Ensure all required fields are present, data types are correct, and values are within acceptable ranges.
- **401 Unauthorized:** Double-check that your `x-api-market-key` header is correctly set and that the API key is valid.
- **429 Too Many Requests:** Implement a retry mechanism with exponential backoff. Wait a short period before retrying, increasing the wait time with each subsequent failure.

**Example Error Response:**
```json
{
  "error": {
    "code": "validation_error",
    "message": "The 'xml' field is required in the request body.",
    "status": 422
  }
}
```

## FAQ

**What types of documents can this API process?**

This API is designed to process PDFs, HTML content, and structured data formats like XML, JSON, and CSV. It can detect the type of any uploaded file by inspecting its bytes.

**Is there a size limit for files uploaded to the API?**

Yes, for PDF files, there is a maximum size limit of 20 MB. Always refer to specific endpoint documentation for exact limits.

**How does the XML to JSON conversion handle attributes and text content?**

The XML to JSON converter is designed to preserve both element attributes and text content. Attributes are typically converted into keys prefixed with `@` (e.g., `@id`), while direct text content within an element is often mapped to a key like `#text`.

**Can I convert JSON with nested objects to CSV?**

The `json/to-csv` endpoint is optimized for JSON arrays of flat objects. Nested objects might be stringified or omitted depending on the complexity. For best results, flatten your JSON data before converting to CSV if complex nesting is present.

**What should I do if I get a `429 Too Many Requests` error?**

This error indicates you've hit your rate limit. Implement an exponential backoff strategy in your code to wait increasingly longer periods between retries. If the issue persists, consider upgrading your API.market plan.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Extract text and tables from PDFs, pull readable content from HTML, detect file types, and convert between CSV, JSON and XML data formats.

Document & Data API