---
title: "Parse an html table and generate a json definition"
method: POST
path: "/parse/html"
---

# Parse an html table and generate a json definition

`POST /parse/html`

## Request

- The document declares no server URL.
- Auth: none declared

A request to convert an html table (plus supporting data) into the correct RenderRequest format

## Request body

- ParseRequest: Properties that are present in both the RenderRequest and ParseRequest
  - `filename` string, required: A unique id for the table
  - `title` string: The main title of the table
  - `subtitle` string: An additional title or short description of the table
  - `source` string: Where the data in the table came from
  - `units` string: Name/decription of the units used in the table, if appropriate
  - `keep_headers_together` boolean: If true, the html output includes a css class designed to prevent content of heading cells being wrapped over 2 lines. Deliberate line breaks will be honoured.
  - `footnotes` string[]: Notes associated with (and potentially referenced from) the table. The order of footnotes is important, e.g. [1] will be converted into a link to the first footnote.
  - `table_html` string, required: An html snippet containing the <table>...</table> that should be parsed
  - `ignore_first_row` boolean: If true, the first row in the source table is ignored. Can be useful with some js spreadsheet components that insert row and column headers.
  - `ignore_first_column` boolean: If true, the first cell of each row in the source table is ignored. Can be useful with some js spreadsheet components that insert row and column headers.
  - `header_rows` integer: The number of rows that should be rendered as headings, after ignoring the first row (if applicable).
  - `header_cols` integer: The number of column that should be rendered as headings, after ignoring the first row (if applicable).
  - `cell_size_units` '%' | 'em' | 'auto': The desired unit for cell widths/heights. Pixel widths will be converted to this unit, provided the required information is provided - see current_table_width and single_em_height. The default is 'auto', in which case no table cell widths/heights will be specified.
  - `current_table_width` integer: The width of the table, used to convert pixel widths to %.
  - `current_table_height` integer: The height of the table, used to convert pixel heights to %.
  - `single_em_height` number: Used to convert height/width from pixels to em. The height of the following: <div style="display: none; font-size: 1em; margin: 0; padding:0; height: auto; line-height: 1; border:0;">m</div>.
  - `column_width_to_ignore` string: If the source html applies a default column width that shouldn't be included in the output, specify it here. e.g. '50px'
  - `alignment_classes` AlignmentClasses: defines the css classes that should be interpreted as defining the alignment of cells in a table
    - `top` string: The css class indicating vertical alignment at the top
    - `middle` string: The css class indicating vertical alignment in the middle
    - `bottom` string: The css class indicating vertical alignment at the bottom
    - `left` string: The css class indicating alignment on the left
    - `center` string: The css class indicating alignment in the centre
    - `right` string: The css class indicating alignment on the right

## Response `200`

A json representation of the table is returned in the body

- ParseResponse: The response to a parse requests - contains an html representation of the table, and the json that defines it
  - `render_json` RenderRequest: Properties that are present in both the RenderRequest and ParseRequest
    - `filename` string, required: A unique id for the table
    - `title` string: The main title of the table
    - `subtitle` string: An additional title or short description of the table
    - `source` string: Where the data in the table came from
    - `units` string: Name/decription of the units used in the table, if appropriate
    - `keep_headers_together` boolean: If true, the html output includes a css class designed to prevent content of heading cells being wrapped over 2 lines. Deliberate line breaks will be honoured.
    - `footnotes` string[]: Notes associated with (and potentially referenced from) the table. The order of footnotes is important, e.g. [1] will be converted into a link to the first footnote.
    - `row_formats` RowFormat[]: A list of format definitions for rows of the table
      - `row` integer: The index of the row this format applies to. Zero indexed.
      - `heading` boolean: Whether this row should be formatted as a heading
      - `height` string: The desired height of this row, as a valid css width property. E.g. '5em'
      - `vertical_align` 'Top' | 'Middle' | 'Bottom': The vertical alignment of the row. For html output this will be rendered as the name of a css class that is assumed to be defined in the containing page.
    - `column_formats` ColumnFormat[]: A list of format definitions for columns of the table
      - `col` integer: The index of the column this format applies to. Zero indexed.
      - `heading` boolean: Whether this column should be formatted as a heading
      - `width` string: The desired width of this column, as a valid css width property. E.g. '5em'
      - `align` 'Left' | 'Center' | 'Right' | 'Justify': The alignment of the column. For html output this will be rendered as the name of a css class that is assumed to be defined in the containing page.
    - `cell_formats` CellFormat[]: A list of format definitions for individual cells in the table
      - `row` integer: The row index of the cell this format applies to. Zero indexed.
      - `col` integer: The column index of the cell this format applies to. Zero indexed.
      - `align` 'Left' | 'Center' | 'Right' | 'Justify': The alignment of the column. For html output this will be rendered as the name of a css class that is assumed to be defined in the containing page.
      - `vertical_align` 'Top' | 'Middle' | 'Bottom': The vertical alignment of the cell. For html output this will be rendered as the name of a css class that is assumed to be defined in the containing page.
    - `data` array[]: The content of the cells in the table (a two-dimensional array of strings). Should contain values for each possible cell in the table, even if that cell will be hidden because another cell has a colspan or rowspan that covers it.
      - string[]
  - `preview_html` string: The html of the table as it would be generated from json

## Other responses

- `400`: Invalid request body
- `500`: Failed to process the request due to an internal error

---

[API](https://skmtc.dev/office-of-national-statistics/apis/table-renderer.md) - [All operations](https://skmtc.dev/office-of-national-statistics/apis/table-renderer/llms.txt) - [OpenAPI document](https://skmtc.dev/office-of-national-statistics/apis/table-renderer/revisions/6adcb13d0bcb?raw)