tabletojson
Advanced tools
Convert local or remote HTML embedded tables into JSON objects.
Tabletojson attempts to convert local or remote HTML tables into JSON with a very low footprint. Can be passed the markup for a single table as a string, a fragment of HTML or an entire page or just a URL (with an optional callback function; promises also supported).
The response is always an array. Every array entry in the response represents a table found on the page (in same the order they were found in HTML).
As of version 2.0 tabletojson is completely written in typescript.
const tabletojson = require('../lib/tabletojson'); to either
const tabletojson = require('../lib/tabletojson').Tabletojson; or
const {Tabletojson: tabletojson} = require('../lib/tabletojson');import {Tabletojson as tabletojson} from 'tabletojson'; or import {tabletojson} from 'tabletojson';import {tabletojson} from 'tabletojson';npm run build:examples
cd dist/examples
node --experimental-vm-modules --experimental-specifier-resolution=node example-1.js --prefix=dist/examples
npm install tabletojson
import {tabletojson} from 'tabletojson';
tabletojson.convertUrl('https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes', function (tablesAsJson) {
console.log(tablesAsJson[1]);
});
const {tabletojson} = require('tabletojson');
tabletojson.convertUrl('https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes', function (tablesAsJson) {
console.log(tablesAsJson[1]);
});
convertUrl)// example-1.ts
import {tabletojson} from 'tabletojson';
tabletojson.convertUrl('https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes', function (tablesAsJson) {
console.log(tablesAsJson[1]);
});
convert)More examples can be found in examples folder.
// example-6.ts
import {tabletojson} from 'tabletojson';
import * as fs from 'fs';
import * as path from 'path';
const html = fs.readFileSync(path.resolve(process.cwd(), '../../test/tables.html'), {
encoding: 'utf-8',
});
const converted = tabletojson.convert(html);
console.log(converted);
Tables with duplicate column headings, subsequent headings are suffixed with a count:
|| PLACE || VALUE || PLACE || VALUE ||
|--------|--------|--------|---------|
| abc | 1 | def | 2 |
[
{
"PLACE": "abc",
"VALUE": "1",
"PLACE_2": "def",
"VALUE_2": "2"
}
]
In tables with rowspan, the content of the spawned cell must be available in the respective object.
| Parent | Child | Age |
|---|---|---|
| Marry | Sue | 15 |
| Steve | 12 | |
| Tom | 3 |
[
{"Parent": "Marry", "Child": "Tom", "Age": "3"},
{"Parent": "Marry", "Child": "Steve", "Age": "12"},
{"Parent": "Marry", "Child": "Sue", "Age": "15"}
]
In tables with complex rowspans, the content of the spawned cell must be available in the respective object.
| Parent | Child | Age |
|---|---|---|
| Marry | Sue | 15 |
| Steve | 12 | |
| Tom | 3 | |
| Taylor | ||
| Peter | 17 |
[
{"Parent": "Marry", "Child": "Sue", "Age": "15"},
{"Parent": "Marry", "Child": "Steve", "Age": "12"},
{"Parent": "Marry", "Child": "Tom", "Age": "3"},
{"Parent": "Taylor", "Child": "Tom", "Age": "3"},
{"Parent": "Taylor", "Child": "Peter", "Age": "17"}
]
In tables with even more complex rowspans, the content of the spawned cell must be available in the respective object.
| Department | Major | Class | Instructor | Credit |
|---|---|---|---|---|
| Engineering | Computer Science | CS101 | Kim | 3 |
| CS201 | Garcia | |||
| CS303 | 2 | |||
| Electrical Engineering | EE101 | Müller | 3 | |
| Social Science | Economics | EC101 | Nguyen | 3 |
| EC401 | Smith |
[
{
"Department": "Engineering",
"Major": "Computer Science",
"Class": "CS101",
"Instructor": "Kim",
"Credit": "3"
},
{
"Department": "Engineering",
"Major": "Computer Science",
"Credit": "3",
"Class": "CS201",
"Instructor": "Garcia"
},
{
"Department": "Engineering",
"Major": "Computer Science",
"Instructor": "Garcia",
"Class": "CS303",
"Credit": "2"
},
{
"Department": "Engineering",
"Major": "Electrical Engineering",
"Class": "EE101",
"Instructor": "Müller",
"Credit": "3"
},
{
"Department": "Social Science",
"Major": "Economics",
"Class": "EC101",
"Instructor": "Nguyen",
"Credit": "3"
},
{
"Department": "Social Science",
"Major": "Economics",
"Credit": "3",
"Class": "EC401",
"Instructor": "Smith"
}
]
If a table contains headings in the first column you might get an unexpected
result, but you can pass a second argument with options with
{ useFirstRowForHeadings: true } to have it treat the first column as it would
any other cell.
tabletojson.convertUrl(
'https://www.timeanddate.com/holidays/ireland/2017',
{ useFirstRowForHeadings: true },
function(tablesAsJson) {
console.log(tablesAsJson);
}
);
The following options are true by default, which converts all values to plain text to give you an easier more readable object to work with:
If your table contains HTML you want to parse (for example for links) you can
set stripHtmlFromCells to false to treat it as raw text.
tabletojson.convertUrl(
'https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes',
{ stripHtmlFromCells: false },
function(tablesAsJson) {
//Print out the 1st row from the 2nd table on the above webpage as JSON
console.log(tablesAsJson[1][0]);
}
);
Note: This doesn't work with nested tables, which it will still try to parse.
You probably don't need to set stripHtmlFromHeadings to false (and setting
it to false can make the results hard to parse), but if you do you can also set
both at the same time by setting stripHtml to false.
Use the following rows as keys in the output json object. The values are flattened and concatenated the values with 'concatWith' [default=undefined]
Input:
| Industry | Operating income | Operating costs | Total profit | ||||||
| amount (billion) | Year-over-year growth (%) | amount (billion) | Year-over-year growth (%) | amount (billion) | Year-over-year growth (%) | ||||
| $ | €* | $ | €* | $ | €* | ||||
| total | 843280,70 | 758952,63 | -0,30 | 718255,00 | 646429,50 | 0,20 | 46558,20 | 41902,38 | -11,70 |
| Coal mining and washing industry | 22937,30 | 20643,57 | -13,90 | 14653,70 | 13188,33 | -7,50 | 5236,90 | 4713,21 | -26,30 |
| Oil and gas extraction | 7605,10 | 6844,59 | -9,60 | 3863,60 | 3477,24 | 0,10 | 2592,70 | 2333,43 | -10,80 |
| Ferrous metal mining and dressing industry | 3010,70 | 2709,63 | -4,40 | 2369,10 | 2132,19 | -4,10 | 326,60 | 293,94 | -23,80 |
| Non-ferrous metal mining and dressing industry | 2180,90 | 1962,81 | -0,30 | 1394,30 | 1254,87 | -2,50 | 512,10 | 460,89 | 4,00 |
| Non-metallic ore mining and dressing industry | 2244,70 | 2020,23 | -5,70 | 1612,00 | 1450,80 | -5,70 | 236,10 | 212,49 | -7,00 |
| Mining professional and ancillary activities | 1537,30 | 1383,57 | 12,70 | 1453,70 | 1308,33 | 11,80 | 2,60 | 2,34 | -77,00 |
|
Note: Some indicators in this table have a situation where the total is not equal to the sum of the sub-items, which is due to rounding of the data and has not been mechanically adjusted. * Conversion rate: 1$=0,9€ |
Output:
[
{
"Industry": "total",
"Operating income amount (billion) $": "843280,70",
"Operating income amount (billion) €*": "758952,63",
"Operating income Year-over-year growth (%)": "-0,30",
"Operating costs amount (billion) $": "718255,00",
"Operating costs amount (billion) €*": "646429,50",
"Operating costs Year-over-year growth (%)": "0,20",
"Total profit amount (billion) $": "46558,20",
"Total profit amount (billion) €*": "41902,38",
"Total profit Year-over-year growth (%)": "-11,70"
},
{
"Industry": "Coal mining and washing industry",
"Operating income amount (billion) $": "22937,30",
"Operating income amount (billion) €*": "20643,57",
"Operating income Year-over-year growth (%)": "-13,90",
"Operating costs amount (billion) $": "14653,70",
"Operating costs amount (billion) €*": "13188,33",
"Operating costs Year-over-year growth (%)": "-7,50",
"Total profit amount (billion) $": "5236,90",
"Total profit amount (billion) €*": "4713,21",
"Total profit Year-over-year growth (%)": "-26,30"
},
{
"Industry": "Oil and gas extraction",
"Operating income amount (billion) $": "7605,10",
"Operating income amount (billion) €*": "6844,59",
"Operating income Year-over-year growth (%)": "-9,60",
"Operating costs amount (billion) $": "3863,60",
"Operating costs amount (billion) €*": "3477,24",
"Operating costs Year-over-year growth (%)": "0,10",
"Total profit amount (billion) $": "2592,70",
"Total profit amount (billion) €*": "2333,43",
"Total profit Year-over-year growth (%)": "-10,80"
},
{
"Industry": "Ferrous metal mining and dressing industry",
"Operating income amount (billion) $": "3010,70",
"Operating income amount (billion) €*": "2709,63",
"Operating income Year-over-year growth (%)": "-4,40",
"Operating costs amount (billion) $": "2369,10",
"Operating costs amount (billion) €*": "2132,19",
"Operating costs Year-over-year growth (%)": "-4,10",
"Total profit amount (billion) $": "326,60",
"Total profit amount (billion) €*": "293,94",
"Total profit Year-over-year growth (%)": "-23,80"
},
{
"Industry": "Non-ferrous metal mining and dressing industry",
"Operating income amount (billion) $": "2180,90",
"Operating income amount (billion) €*": "1962,81",
"Operating income Year-over-year growth (%)": "-0,30",
"Operating costs amount (billion) $": "1394,30",
"Operating costs amount (billion) €*": "1254,87",
"Operating costs Year-over-year growth (%)": "-2,50",
"Total profit amount (billion) $": "512,10",
"Total profit amount (billion) €*": "460,89",
"Total profit Year-over-year growth (%)": "4,00"
},
{
"Industry": "Non-metallic ore mining and dressing industry",
"Operating income amount (billion) $": "2244,70",
"Operating income amount (billion) €*": "2020,23",
"Operating income Year-over-year growth (%)": "-5,70",
"Operating costs amount (billion) $": "1612,00",
"Operating costs amount (billion) €*": "1450,80",
"Operating costs Year-over-year growth (%)": "-5,70",
"Total profit amount (billion) $": "236,10",
"Total profit amount (billion) €*": "212,49",
"Total profit Year-over-year growth (%)": "-7,00"
},
{
"Industry": "Mining professional and ancillary activities",
"Operating income amount (billion) $": "1537,30",
"Operating income amount (billion) €*": "1383,57",
"Operating income Year-over-year growth (%)": "12,70",
"Operating costs amount (billion) $": "1453,70",
"Operating costs amount (billion) €*": "1308,33",
"Operating costs Year-over-year growth (%)": "11,80",
"Total profit amount (billion) $": "2,60",
"Total profit amount (billion) €*": "2,34",
"Total profit Year-over-year growth (%)": "-77,00"
},
{
"Industry": "Note: Some indicators in this table have a situation where the total is not equal to the sum of the sub-items, which is due to rounding of the data and has not been mechanically adjusted.\n * Conversion rate: 1$=0,9€"
}
]
convertUrl)Tabletojson is using fetch api which is available in node from version 17.5.0 onwards to fetch remote HTML pages. See
mdn web docs on fetch for more information. The usage of
Tabletojson should now be the same in node as in browsers.
So if you need to get data from a remote server you can call tabletojson.convertUrl and pass any
fetch-options (proxy, headers,...) by adding a RequestInit object to the options
passed to convertUrl. For more information on how to configure request please
have a look at Browser Syntax or Node fetch
tabletojson.convertUrl('https://www.timeanddate.com/holidays/ireland/2017', {
useFirstRowForHeadings: true,
fetchOptions: {
...
}
});
Define the rows to be used as keys in the output json object. The values will be concatenated with the given concatWith value. [default=undefined]
const html = fs.readFileSync(path.resolve(process.cwd(), '../test/tables.html'), {
encoding: 'utf-8',
});
const converted = tabletojson.convert(html, {
id: ['table15'],
// from (Optional) Start row [default=0]
// to End row
// concatWith Concatenate the values with this string
headers: {
to: 2,
concatWith: ' ',
},
});
console.log(JSON.stringify(converted, null, 2));
Strip any HTML from heading cells. Default is true.
||KEY || <b>VALUE</b><||
|-----|----------------|
| abc | 1 |
| dev | 2 |
Example output with stripHtmlFromHeadings:true
[
{
"KEY": "abc", "VALUE": "1"
},
{
"KEY": "dev", "VALUE": "2"
}
]
Example output with stripHtmlFromHeadings:false
[
{
"KEY": "abc", "<b>VALUE</b>": "1"
},
{
"KEY": "dev", "<b>VALUE</b>": "2"
}
]
Strip any HTML from tableBody cells. Default is true.
||KEY || VALUE||
|-----|-----------|
|abc | <i>1</i>|
|dev | <i>2</i>|
Example output with stripHtmlFromHeadings:true
[
{
"KEY": "abc", "VALUE": "1"
},
{
"KEY": "dev", "VALUE": "2"
}
]
Example output with stripHtmlFromHeadings:false
[
{
"KEY": "abc", "VALUE": "<i>1</i>"
},
{
"KEY": "dev", "VALUE": "<i>2</i>"
}
]
Instead of using column text (that sometime re-order the data), force an index as a number (string number).
{
"0": "",
"1": "Ａ会",
"2": "Ｂ会",
"3": "Ｃ会",
"4": "Something",
"5": "Else",
"6": ""
}
Default is true. If set to false, duplicate headings will not get a trailing
number. The value of the field will be the last value found in the table row:
||PLACE || VALUE || PLACE || VALUE||
|-------|--------|--------|--------|
| abc | 1 | def | 2 |
| ghi | 3 | jkl | 4 |
Example output with countDuplicateHeadings:false
[
{
"PLACE": "def", "VALUE": "2"
},
{
"PLACE": "jkl", "VALUE": "4"
}
]
Array of indexes to be ignored, starting with 0. Default is 'null/undefined'.
|| NAME || PLACE || WEIGHT || SEX || AGE ||
|-------|--------|---------|------|-------|
| Mel | 1 | 58 | W | 23 |
| Bill | 3 | 92 | M | 31 |
| Tom | 2 | 78 | M | 54 |
Example output with ignoreColumns: [2, 3]
[
{
"NAME": "Mel", "PLACE": "1", "AGE": "23"
},
{
"NAME": "Tom", "PLACE": "2", "AGE": "54"
},
{
"NAME": "Bill", "PLACE": "3", "AGE": "31"
}
]
Array of indexes that are taken, starting with 0. Default is 'null/undefined'. If given, this option overrides ignoreColumns.
|| NAME || PLACE || WEIGHT || SEX || AGE ||
|-------|--------|---------|------|-------|
| Mel | 1 | 58 | W | 23|
| Tom | 2 | 78 | M | 54|
| Bill | 3 | 92 | M | 31|
Example output with onlyColumns: [0, 4]
[
{
"NAME": "Mel", "AGE": "23"
},
{
"NAME": "Tom", "AGE": "54"
},
{
"NAME": "Bill", "AGE": "31"
}
]
Indicates if hidden rows (display:none) are ignored. Default is true:
|| NAME || PLACE || WEIGHT || SEX || AGE ||
|-------|--------|---------|------|-------|
| Mel | 1 | 58 | W | 23|
| Tom | 2 | 78 | M | 54|
| Bill | 3 | 92 | M | 31|
|* Cat | 4 | 4 | W | 2*|
Example output with ignoreHiddenRows:true
[
{
"NAME":"Mel",
"PLACE":"1",
"WEIGHT":"58",
"SEX":"W",
"AGE":"23"
},
{
"NAME":"Tom",
"PLACE":"2",
"WEIGHT":"78",
"SEX":"M",
"AGE":"54"
},
{
"NAME":"Bill",
"PLACE":"3",
"WEIGHT":"92",
"SEX":"M",
"AGE":"31"
}
]
Example output with ignoreHiddenRows:false
[
{
"NAME":"Mel",
"PLACE":"1",
"WEIGHT":"58",
"SEX":"W",
"AGE":"23"
},
{
"NAME":"Tom",
"PLACE":"2",
"WEIGHT":"78",
"SEX":"M",
"AGE":"54"
},
{
"NAME":"Bill",
"PLACE":"3",
"WEIGHT":"92",
"SEX":"M",
"AGE":"31"
},
{
"NAME":"Cat",
"PLACE":"4",
"WEIGHT":"4",
"SEX":"W",
"AGE":"2"
}
]
Array of Strings to be used as headings. Default is null/undefined.
If more headings are given than columns exist the overcounting ones will be ignored. If less headings are given than existing values the overcounting values are ignored.
|| NAME || PLACE || WEIGHT || SEX || AGE ||
|-------|--------|---------|------|-------|
| Mel | 1 | 58 | W | 23|
| Tom | 2 | 78 | M | 54|
| Bill | 3 | 92 | M | 31|
|* Cat | 4 | 4 | W | 2*|
Example output with headings: ['A','B','C','D','E']
[
{
"A":"Mel",
"B":"1",
"C":"58",
"D":"W",
"E":"23"
},
{
"A":"Tom",
"B":"2",
"C":"78",
"D":"M",
"E":"54"
},
{
"A":"Bill",
"B":"3",
"C":"92",
"D":"M",
"E":"31"
}
]
Example output with headings: ['A','B','C']
[
{
"A":"Mel",
"B":"1",
"C":"58"
},
{
"A":"Tom",
"B":"2",
"C":"78"
},
{
"A":"Bill",
"B":"3",
"C":"92"
}
]
Example output with headings: ['A','B','C','D','E','F','G','H']
[
{
"A":"Mel",
"B":"1",
"C":"58",
"D":"W",
"E":"23"
},
{
"A":"Tom",
"B":"2",
"C":"78",
"D":"M",
"E":"54"
},
{
"A":"Bill",
"B":"3",
"C":"92",
"D":"M",
"E":"31"
}
]
Example output with headings: ['A','B','C'] && ignoreColumns: [2, 3]
[
{
"A":"Mel",
"B":"W",
"C":"23"
},
{
"A":"Tom",
"B":"M",
"C":"54"
},
{
"A":"Bill",
"B":"M",
"C":"31"
}
]
Number of rows to which the resulting object should be limited to. Default is
null/undefined.
|| Roleplayer Number || Name || Text to say||
|--------------------|------------------|--------------|
| 0 | Raife Parkinson | re dolor in hendrerit in vulputate ve|
| 1 | Hazel Schultz | usto duo dolores et ea rebum. Ste|
| 2 | Montana Delgado | psum dolor sit amet. Lorem ipsum dolor|
| 3 | Dianne Mcbride | sit ame olor sit amet. Lorem ipsum|
| 4 | Xena Lynch | us est Lorem ipsum dol|
| 5 | Najma Holding | akimata sanctus est Lorem ipsum dolor sit|
| 6 | Kiki House | ame nvidunt ut|
|...|
|197 | Montana Delgado | lores et ea rebum. Stet clita kasd gu a|
|198 | Myrtle Conley | rebum. Stet clita kasd gubergren, no sea|
|199 | Hanna Ellis | kimata sanctus est Lorem ipsum dolor si|
[
{
"Roleplayer Number":"0",
"Name":"Raife Parkinson",
"Text to say":"re dolor in hendrerit in vulputate ve"
},
{
"Roleplayer Number":"1",
"Name":"Hazel Schultz",
"Text to say":"usto duo dolores et ea rebum. Ste"
},
{
"Roleplayer Number":"2",
"Name":"Montana Delgado",
"Text to say":"psum dolor sit amet. Lorem ipsum dolor sit ame"
},
{
"Roleplayer Number":"3",
"Name":"Dianne Mcbride",
"Text to say":"olor sit amet. Lorem ipsum"
},
{
"Roleplayer Number":"4",
"Name":"Xena Lynch",
"Text to say":"us est Lorem ipsum dol"
}
]
Array of classes to find a specific table using this class. Default is null/
undefined.
<th></th> headings and corresponding <td></td> cells, but also
taking care of rowspan and colspan. It can give useless or weird results
on tables that have complex structures
(such as nested tables) or multiple headers (such as on both X and Y axis).Find here a list of examples on how to use the library. More examples can be found in the examples folder or in the test folder
import {tabletojson} from 'tabletojson';
const tablesAsJson = tabletojson.convert(html);
const firstTableAsJson = tablesAsJson[0];
const secondTableAsJson = tablesAsJson[1];
import {tabletojson} from 'tabletojson';
tabletojson.convertUrl('https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes', function (tablesAsJson) {
console.log(tablesAsJson[1]);
});
import {tabletojson} from 'tabletojson';
const url = 'http://en.wikipedia.org/wiki/List_of_countries_by_credit_rating';
tabletojson.convertUrl(url)
.then(function(tablesAsJson) {
const standardAndPoorRatings = tablesAsJson[1];
const fitchRatings = tablesAsJson[2];
});
import {tabletojson} from 'tabletojson';
import {Parser} from 'json2csv';
const url = 'http://en.wikipedia.org/wiki/List_of_countries_by_credit_rating';
tabletojson.convertUrl(url).then(function (tablesAsJson) {
const fitchRatings = tablesAsJson[2];
const json2csvParser = new Parser({
fields: ['Country/Region', 'Outlook'],
});
const csv = json2csvParser.parse(fitchRatings);
console.log(csv);
/* Example output
"Country/Region","Outlook"
"Abu Dhabi, UAE","Stable"
"Albania","Stable"
"Andorra","Negative"
"Angola","Stable"
"Argentina","Negative"
"Aruba","Stable"
"Australia","Stable"
"Austria","Negative"
"Azerbaijan","Positive"
...
*/
});
Improvements, fixes and suggestions are welcome.
You can find basic tests in the test folder. The library has been implemented to be used straight forward way. Nonetheless there are some edge cases that need to be tested and I would like to ask for support here. Feel free to fork and create PRs here. Every bit of help is appreciated.
For more usage examples have a look in the examples folder that shows usage and would be a good start.
If you submit a pull request, please add an example for your use case, so I can understand what you want it to do (as I want to get around to writing tests for this and want to understand the sort of use cases people have).
FAQs
Convert HTML tables to JSON objects
The npm package tabletojson receives a total of 9,764 weekly downloads. As such, tabletojson popularity was classified as popular.
We found that tabletojson demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."