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.
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_jsonreturns each row as an object whose keys come from the table's column headers. In the captured example the keys includeSYMBOL,NAME,PRICE,CHANGEand%CHANGE, with values such asAMD,Advanced Micro Devices Inc,94.82,-3.98and-4.03.table_arrayreturns 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.
| Input | Where it goes | What it controls |
|---|---|---|
| Target URL | request url | The page that contains the table |
| API key | client constructor | Authenticates the request |
| Rule key | key inside extract_rules | Name of the result entry in the response |
selector | inside each rule | CSS selector that locates the table |
output | inside each rule | table_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.
- 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-tablevs.table), so verify against the page markup rather than trusting either alone. - 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.
- Output mode is one of the documented values. Use
table_jsonortable_array; these are the two output values shown in the captured example. - Response is decoded before parsing. The captured client code decodes
response.datawith aTextDecoderand logs the resulting text; the exact client return shape is preserved in the accompanying deterministic code module. - Transport and auth errors are separate. The captured client code attaches a
.catchhandler 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.