Skip to content

Extracting a Table's Content in NodeJS

HTML tables are one of the most common ways structured data appears on the web, and they are also one of the easiest to turn into usable records when the extraction service does the parsing for you.

OUTPUT FORMATSHTMLJSONMarkdown

Instead of downloading the full HTML response and writing your own row and cell parser, you point the request at the table with a CSS selector and let the extraction layer return the rows in a shape your code can consume.

How table extraction works in a request

The workflow has three moving parts. First, you identify the table on the target page with a CSS selector. Second, you declare that selector inside an extract_rules object. Third, you pick an output mode so the service knows whether to return labeled objects or positional arrays.

For the demo page used in this guide, the prose describes the table's class as .BasicTable-table, while the captured request code targets .table for both rules. Treat the selector as the value you must confirm against the actual page markup before sending the request; the two values above are captured evidence, not a verified working pair.

The example pulls the top 100 NASDAQ stock prices from a demo page. Each rule names a key (for example table_json or table_array), and the rule body carries a selector and an output. The response then contains one entry per rule key.

Choosing between table_json and table_array

Both output modes return the same underlying rows; they differ in how each row is shaped.

  • table_json returns each row as an object whose keys come from the table's column headers. In the captured example the keys include SYMBOL , NAME , PRICE , CHANGE and %CHANGE , with values such as AMD, Advanced Micro Devices Inc, 94.82, -3.98 and -4.03.
  • table_array returns each row as a plain array of cell values in column order, for example ["AMD", "Advanced Micro Devices Inc", "94.82", "-3.98", "-4.03"].

Use the JSON form when downstream code refers to columns by name and you want the mapping to stay readable. Use the array form when you are streaming rows into a spreadsheet, a CSV writer, or a database loader that expects positional columns. The captured request code declares two rules with the same selector and different keys, one per output mode, so both shapes can be requested together.

The two representations are documented separately in the data extraction reference; see the JSON Representation and Array Representation sections there for the full field behavior.

Request field map

The request is assembled from a small set of inputs. The table below shows where each one belongs so you can wire it into your NodeJS client without guessing.

InputWhere it goesWhat it controls
Target URLrequest urlThe page that contains the table
API keyclient constructorAuthenticates the request
Rule keykey inside extract_rulesName of the result entry in the response
selectorinside each ruleCSS selector that locates the table
outputinside each ruletable_json or table_array

The exact request and response shapes are preserved in the accompanying deterministic code modules, so treat those as the source of truth for field names and casing.

Worked example: NASDAQ top 100 table

The demo page contains a table of the top 100 NASDAQ stocks. The captured request code targets .table for both rules, while the surrounding prose names the table's class as .BasicTable-table; confirm the selector against the live markup before relying on either value.

A single row in the JSON output looks like this: SYMBOL is AMD, NAME is Advanced Micro Devices Inc, PRICE is 94.82, CHANGE is -3.98, and %CHANGE is -4.03. The same row in the array output is ["AMD", "Advanced Micro Devices Inc", "94.82", "-3.98", "-4.03"]. Notice that the JSON keys carry a trailing space in the captured output; if you consume those keys programmatically, trim them before using them as identifiers.

Because the response contains one entry per rule key, you can read parsed.table_json and parsed.table_array from the same decoded body without making a second request.

Checklist before you debug

When a table extraction returns nothing useful, work through these checks in order. Each one isolates a different layer of the request.

  1. Selector matches the table. Confirm the CSS selector targets the table element itself, not a wrapper or a row. The captured prose and captured code disagree on the class value (.BasicTable-table vs .table), so verify against the page markup rather than trusting either alone.
  2. Rule key is unique. Each rule key names a distinct result entry in the response, so give each rule its own name to keep results addressable.
  3. Output mode is one of the documented values. Use table_json or table_array; these are the two output values shown in the captured example.
  4. Response is decoded before parsing. The captured client code decodes response.data with a TextDecoder and logs the resulting text; the exact client return shape is preserved in the accompanying deterministic code module.
  5. Transport and auth errors are separate. The captured client code attaches a .catch handler that logs the error payload, so inspect that payload rather than assuming the selector is wrong.

Distinguishing these cases early avoids the common trap of rewriting a selector that was already correct.

Frequently asked questions

Can I extract more than one table in a single request?

Yes. Each entry in extract_rules is an independent rule with its own key, selector and output. Declare a separate rule for each table you want, and read each result by its rule key.

What is the practical difference between table_json and table_array?

table_json returns rows as objects keyed by the table's column headers, which is convenient when code refers to columns by name. table_array returns rows as ordered arrays of cell values, which suits positional consumers such as CSV writers or loaders. Both return the same rows.

Do I still need to parse the HTML myself?

No. The extraction layer returns the table rows in the chosen representation, so you do not need to download the HTML and write a row and cell parser. You still decode the response bytes to text before reading the JSON.

Why do the JSON keys have a trailing space?

In the captured example the column headers include a trailing space, so the object keys do too. If you use those keys as identifiers, trim them first.