Core Document ProcessingParsing

Response Format

The Parse API returns document content in a structured format that provides both high-level formatted content and detailed block-level information. Start with the response structure, then decide whether you need formatted content or block-level detail.

Response structure

Each chunk contains two key properties:

  1. content: A fully formatted representation of the entire chunk in the target format (e.g., markdown). This is ready to use as-is if you need the complete formatted content of a page.

  2. blocks: An array of individual content blocks that make up the chunk, each with its own formatting, position information, and metadata.

Choose content vs. blocks

  • Use chunk.content when:

    • You need the complete, properly formatted content of a page, already doing the logical placement of blocks (e.g. grouping markdown sections and placing spatially, etc)
    • You want to display or process the document content as a whole (and can just combine all chunk.content values)
    • You’re integrating with systems that expect formatted text (e.g., markdown processors)

  • Use chunk.blocks when:

    • You need to work with specific elements of the document (e.g., only tables or figures)
    • You need spatial information about where content appears on the page, perhaps to build citation systems
    • You’re building a UI that shows or highlights specific document elements

Examples

Extract specific content types

1// Extract all tables from a document
2function extractTables(parseResult) {
3  const tables = [];
4  
5  parseResult.chunks.forEach(chunk => {
6    chunk.blocks.forEach(block => {
7      if (block.type === 'table') {
8        tables.push({
9          content: block.content,
10          pageNumber: block.metadata.page.number,
11          position: block.boundingBox
12        });
13      }
14    });
15  });
16  
17  return tables;
18}
19
20// Extract all figures with their images
21function extractFigures(parseResult) {
22  const figures = [];
23  
24  parseResult.chunks.forEach(chunk => {
25    chunk.blocks.forEach(block => {
26      if (block.type === 'figure' && block.details.imageUrl) {
27        figures.push({
28          caption: block.content,
29          imageUrl: block.details.imageUrl,
30          figureType: block.details.figureType,
31          pageNumber: block.metadata.page.number
32        });
33      }
34    });
35  });
36  
37  return figures;
38}

Reconstruct content with custom formatting

1// Extract headings and their content to create a table of contents
2function createTableOfContents(parseResult) {
3  const toc = [];
4  
5  parseResult.chunks.forEach(chunk => {
6    chunk.blocks.forEach(block => {
7      if (block.type === 'heading' || block.type === 'section_heading') {
8        toc.push({
9          title: block.content,
10          pageNumber: block.metadata.page.number
11        });
12      }
13    });
14  });
15  
16  return toc;
17}

Excel cell metadata and formatting

For advanced Excel parsing, advancedOptions.excelIncludeCellMetadata adds spreadsheet provenance to block details. Table cell blocks receive details.cellReference in A1 notation (for example, "B2", or "A1:C1" for a merged cell), and formula cells receive details.formula with a leading =. Text or heading blocks that come from spreadsheet cells can receive a source range in details.cellReference.

If blockOptions.tables.targetFormat is "html", the same metadata is also emitted as data-cell and data-formula attributes. Markdown output omits those attributes, but the structured block details still carry the metadata.

advancedOptions.excelIncludeCellFormatting adds details.formatting to table cell blocks when formatting is present. The formatting object can include bold, italic, fontColor, and backgroundColor; colors are hex strings such as "#ff0000". For HTML table output, inline cell styles are also preserved.

1{
2  "type": "table_cell",
3  "content": "40",
4  "details": {
5    "type": "table_cell_details",
6    "rowIndex": 1,
7    "columnIndex": 1,
8    "cellReference": "B2",
9    "formula": "=A2*10",
10    "formatting": {
11      "bold": true,
12      "fontColor": "#ff0000",
13      "backgroundColor": "#ffff00"
14    }
15  }
16}

Spatial information

Each block contains spatial information in the form of a polygon (precise outline) and a simplified boundingBox. Use this when you need position-aware output:

  • Highlight specific content in a document viewer
  • Create visual overlays on top of the original document
  • Understand the reading order and layout of the document
1// Create highlight coordinates for a document viewer
2function createHighlights(parseResult, searchTerm) {
3  const highlights = [];
4  
5  parseResult.chunks.forEach(chunk => {
6    chunk.blocks.forEach(block => {
7      if (block.type === 'text' && block.content.includes(searchTerm)) {
8        highlights.push({
9          pageNumber: block.metadata.page.number,
10          boundingBox: block.boundingBox
11        });
12      }
13    });
14  });
15  
16  return highlights;
17}

By leveraging both the formatted content and the structured block information, you can build powerful document processing workflows that combine the convenience of formatted text with the precision of block-level access.