htmldate: find the publication date of web pages
Code: | https://github.com/adbar/htmldate |
---|---|
Documentation: | https://htmldate.readthedocs.io |
Issue tracker: | https://github.com/adbar/htmldate/issues |
Find original and updated publication dates of any web page. All the steps needed from web page download to HTML parsing, scraping and text analysis are included.
In a nutshell, with Python:
>>> from htmldate import find_date
>>> find_date('http://blog.python.org/2016/12/python-360-is-now-available.html')
'2016-12-23'
>>> find_date('https://netzpolitik.org/2016/die-cider-connection-abmahnungen-gegen-nutzer-von-creative-commons-bildern/', original_date=True)
'2016-06-23'
On the command-line:
$ htmldate -u http://blog.python.org/2016/12/python-360-is-now-available.html
'2016-12-23'
Features
htmldate finds original and updated publication dates of web pages. URLs, HTML files or HTML trees are given as input, the library outputs a date string in the desired format. It provides following ways to date a HTML document:
- Markup in header: common patterns are used to identify relevant elements (e.g.
link
andmeta
elements) including Open Graph protocol attributes and a large number of CMS idiosyncracies - HTML code: The whole document is then searched for structural markers:
abbr
/time
elements and a series of attributes (e.g.postmetadata
) - Bare HTML content: A series of heuristics is run on text and markup:
- in
fast
mode the HTML page is cleaned and precise patterns are targeted- in
extensive
mode all potential dates are collected and disambiguation algorithm determines the best one
The module returns a date if a valid cue could be found in the document, corresponding to either the last update (default) or the original publishing statement. The output string defaults to ISO 8601 YMD format.
- Should be compatible with all common versions of Python 3
- Output thouroughly verified in terms of plausibility and adequateness
- Designed to be computationally efficient and used in production on millions of documents
- Batch processing of a list of URLs
- Switch between original and updated date
Performance
100 documents containing identifiable dates (2020-02-12) | |||
---|---|---|---|
Python Package | Precision | Accuracy | Time |
newspaper3k 0.2.8 | 0.97 | 0.31 | 49.51 |
goose3 3.1.6 | 0.94 | 0.32 | 7.10 |
date_guesser 2.1.4 | 0.80 | 0.40 | 18.26 |
news-please 1.4.25 | 0.80 | 0.46 | 40.85 |
articleDateExtractor 0.20 | 0.81 | 0.46 | 2.13 |
htmldate 0.6.1 (fast) | 0.93 | 0.79 | 1.40 |
htmldate[all] 0.6.1 (extensive) | 0.91 | 0.91 | 2.67 |
For complete results and explanations see the evaluation page.
Installation
This Python package is tested on Linux, macOS and Windows systems, it is compatible with Python 3.4 upwards. It is available on the package repository PyPI and can notably be installed with pip
or pipenv
:
$ pip install htmldate # pip3 install on systems where both Python 2 and 3 are installed
$ pip install --upgrade htmldate # to make sure you have the latest version
$ pip install git+https://github.com/adbar/htmldate.git # latest available code (see build status above)
A few additional libraries can be installed to enhance coverage and speed, most importantly ciso8601
and regex
(for speed) as well as dateparser
(to go beyond the current focus on English or German). They may not work on all platforms and have thus been singled out although installation is recommended:
$ pip install htmldate[all] # install with all additional functionality
You can also install or update the packages separately, htmldate will detect which ones are present on your system and opt for the best available combination.
For faster processing of downloads you may also consider installing the cchardet
package as well (currently not working on some macOS versions).
For infos on dependency management of Python packages see this discussion thread
With Python
>>> from htmldate import find_date
>>> find_date('http://blog.python.org/2016/12/python-360-is-now-available.html')
'2016-12-23'
Complete screening of the document with the extensive_search
parameter:
>>> find_date('https://creativecommons.org/about/')
'2017-08-11' # has been updated since
>>> find_date('https://creativecommons.org/about/', extensive_search=False)
>>>
Already parsed HTML (that is a LXML tree object):
# simple HTML document as string
>>> htmldoc = '<html><body><span class="entry-date">July 12th, 2016</span></body></html>'
>>> find_date(htmldoc)
'2016-07-12'
# parsed LXML tree
>>> from lxml import html
>>> mytree = html.fromstring('<html><body><span class="entry-date">July 12th, 2016</span></body></html>')
>>> find_date(mytree)
'2016-07-12'
Change the output to a format known to Python's datetime
module, the default being %Y-%m-%d
:
>>> find_date('https://www.gnu.org/licenses/gpl-3.0.en.html', outputformat='%d %B %Y')
'18 November 2016' # may have changed since
Although the time delta between original publication and "last modified" info is usually a matter of hours or days, it can be useful to prioritize the original publication date:
>>> find_date('https://netzpolitik.org/2016/die-cider-connection-abmahnungen-gegen-nutzer-von-creative-commons-bildern/') # default setting
'2019-06-24'
>>> find_date('https://netzpolitik.org/2016/die-cider-connection-abmahnungen-gegen-nutzer-von-creative-commons-bildern/', original_date=True) # modified behavior
'2016-06-23'
On the command-line
$ htmldate -u http://blog.python.org/2016/12/python-360-is-now-available.html
'2016-12-23'
$ htmldate --help
htmldate [-h] [-v] [-f] [--original] [-m MAXDATE] [-i INPUTFILE] [-u URL]
- optional arguments:
-h, --help show this help message and exit -v, --verbose increase output verbosity -f, --fast fast mode: disable extensive search --original original date prioritized -m MAXDATE, --maxdate MAXDATE latest acceptable date (YYYY-MM-DD) -i INPUTFILE, --inputfile INPUTFILE name of input file for batch processing (similar to wget -i) -u URL, --URL URL custom URL download
The batch mode -i
takes one URL per line as input and returns one result per line in tab-separated format:
$ htmldate --fast -i list-of-urls.txt
License
htmldate is distributed under the GNU General Public License v3.0
GPL and free software licensing: What's in it for business?
Going further
Online documentation: htmldate.readthedocs.io
If the date is nowhere to be found, it might be worth considering carbon dating the web page, however this is computationally expensive. In addition, datefinder features pattern-based date extraction for texts written in English.
Author
This effort is part of a methodological approach to derive information from web documents in order to build text databases for research (chiefly linguistics and natural language processing). There are web pages for which neither the URL nor the server response provide a reliable way to find out when a document was published or modified. For more information:
- Barbaresi, A. "Generic Web Content Extraction with Open-Source Software", Proceedings of KONVENS 2019, Kaleidoscope Abstracts, 2019.
- Barbaresi, A. "Efficient construction of metadata-enhanced web corpora", Proceedings of the 10th Web as Corpus Workshop (WAC-X), 2016.
You can contact me via my contact page or GitHub.
Contributing
Thanks to these contributors who submitted features and bugfixes:
Contributions are welcome!
Feel free to file bug reports on the issues page.
Kudos to the following software libraries:
- cchardet, ciso8601, lxml, dateparser
- A few patterns are derived from python-goose, metascraper, newspaper and articleDateExtractor. This module extends their coverage and robustness significantly.