.. Note that we use raw HTML in the header section because centering images and paragraphs is not supported in Github (https://github.com/github/markup/issues/163)

.. raw:: html

<div align="center">

.. image:: artwork/dateparser-logo.png :alt: Dateparser :width: 500 :target: https://github.com/scrapinghub/dateparser

Python parser for human readable dates

.. raw:: html

</div>

.. docs-include-marker

.. raw:: html

<p align="center">
    <a href="https://pypi.python.org/pypi/dateparser">
        <img src="https://img.shields.io/pypi/dm/dateparser.svg" alt="PyPI - Downloads">
    </a>
    <a href="https://pypi.python.org/pypi/dateparser">
        <img src="https://img.shields.io/pypi/v/dateparser.svg" alt="PypI - Version">
    </a>
    <a href="https://codecov.io/gh/scrapinghub/dateparser">
        <img src="https://codecov.io/gh/scrapinghub/dateparser/branch/master/graph/badge.svg" alt="Code Coverage">
    </a>
    <a href="https://github.com/scrapinghub/dateparser/actions">
        <img src="https://github.com/scrapinghub/dateparser/workflows/Build/badge.svg" alt="Github - Build">
    </a>
    <a href="https://dateparser.readthedocs.org/en/latest/?badge=latest">
        <img src="https://readthedocs.org/projects/dateparser/badge/?version=latest" alt="Readthedocs - Docs">
    </a>
</p>

<p align="center">
    <a href="#key-features">Key Features</a> •
    <a href="#how-to-use">How To Use</a> •
    <a href="#installation">Installation</a> •
    <a href="#common-use-cases">Common use cases</a> •
    <a href="#you-may-also-like">You may also like...</a> •
    <a href="#license">License</a>
</p>

Key Features

• Support for almost every existing date format: absolute dates, relative dates ("two weeks ago" or "tomorrow"), timestamps, etc.
• Support for more than 200 language locales <https://dateparser.readthedocs.io/en/latest/supported_locales.html>__.
• Language autodetection
• Customizable behavior through settings <https://dateparser.readthedocs.io/en/latest/settings.html>__.
• Support for non-Gregorian calendar systems <#supported-calendars>__.
• Support for dates with timezones abbreviations or UTC offsets ("August 14, 2015 EST", "21 July 2013 10:15 pm +0500"...)
• Search dates <#search-for-dates-in-longer-chunks-of-text>__ in longer texts.
• Time span detection for expressions like "past month", "last week".

Online demo

Do you want to try it out without installing any dependency? Now you can test it quickly by visiting this online demo <https://gnyman.github.io/dateparser-demo-app/>__!

How To Use

The most straightforward way to parse dates with dateparser is to use the dateparser.parse() function, that wraps around most of the functionality of the module.

.. code:: python

>>> import dateparser

>>> dateparser.parse('Fri, 12 Dec 2014 10:55:50')
datetime.datetime(2014, 12, 12, 10, 55, 50)

>>> dateparser.parse('1991-05-17')
datetime.datetime(1991, 5, 17, 0, 0)

>>> dateparser.parse('In two months')  # today is 1st Aug 2020
datetime.datetime(2020, 10, 1, 11, 12, 27, 764201)

>>> dateparser.parse('1484823450')  # timestamp
datetime.datetime(2017, 1, 19, 10, 57, 30)

>>> dateparser.parse('January 12, 2012 10:00 PM EST')
datetime.datetime(2012, 1, 12, 22, 0, tzinfo=<StaticTzInfo 'EST'>)

dateparser also works with strings in different languages:

.. code:: python

>>> dateparser.parse('Martes 21 de Octubre de 2014')  # Spanish (Tuesday 21 October 2014)
datetime.datetime(2014, 10, 21, 0, 0)

>>> dateparser.parse('Le 11 Décembre 2014 à 09:00')  # French (11 December 2014 at 09:00)
datetime.datetime(2014, 12, 11, 9, 0)

>>> dateparser.parse('13 января 2015 г. в 13:34')  # Russian (13 January 2015 at 13:34)
datetime.datetime(2015, 1, 13, 13, 34)

>>> dateparser.parse('1 เดือนตุลาคม 2005, 1:00 AM')  # Thai (1 October 2005, 1:00 AM)
datetime.datetime(2005, 10, 1, 1, 0)

>>> dateparser.parse('yaklaşık 23 saat önce')  # Turkish (23 hours ago), current time: 12:46
datetime.datetime(2019, 9, 7, 13, 46)

>>> dateparser.parse('2小时前')  # Chinese (2 hours ago), current time: 22:30
datetime.datetime(2018, 5, 31, 20, 30)

You can specify the language(s), if known, using the languages argument. In this case, given languages are used and language detection is skipped:

.. code:: python

>>> dateparser.parse('2015, Ago 15, 1:08 pm', languages=['pt', 'es'])
datetime.datetime(2015, 8, 15, 13, 8)

If you know the possible formats of the dates, you can use the date_formats argument:

.. code:: python

>>> dateparser.parse('22 Décembre 2010', date_formats=['%d %B %Y'])
datetime.datetime(2010, 12, 22, 0, 0)

The formats are tried first. A date string that none of them parses is then parsed as if no formats were given, so a number that is out of range for a format can be read as another part of the date (32 is not a day, but it is a valid two-digit year). To accept only the given formats, set PARSERS to ['custom-formats'], which also turns off timestamps, relative dates and free-form dates:

.. code:: python

>>> dateparser.parse('32 DEC 10', date_formats=['%d %b %y'])
datetime.datetime(2032, 12, 10, 0, 0)

>>> dateparser.parse('32 DEC 10', date_formats=['%d %b %y'], settings={'PARSERS': ['custom-formats']})
None

Relative Dates

.. code:: python

>>> from dateparser import parse
>>> parse('1 hour ago')
datetime.datetime(2015, 5, 31, 23, 0)
>>> parse('Il ya 2 heures')  # French (2 hours ago)
datetime.datetime(2015, 5, 31, 22, 0)
>>> parse('1 anno 2 mesi')  # Italian (1 year 2 months)
datetime.datetime(2014, 4, 1, 0, 0)
>>> parse('yaklaşık 23 saat önce')  # Turkish (23 hours ago)
datetime.datetime(2015, 5, 31, 1, 0)
>>> parse('Hace una semana')  # Spanish (a week ago)
datetime.datetime(2015, 5, 25, 0, 0)
>>> parse('2小时前')  # Chinese (2 hours ago)
datetime.datetime(2015, 5, 31, 22, 0)
>>> parse('next Wednesday')
datetime.datetime(2015, 6, 3, 0, 0)

In English, last, this and next before a weekday mean its closest occurrence before, on or after, and after the current date, respectively, regardless of the PREFER_DATES_FROM setting. So this Wednesday and next Wednesday are the same date except on a Wednesday. They do not apply to wed, sat and sun, which are also common English words.

.. note:: Testing above code might return different values depending on your environment's current date and time.

.. note:: For the Finnish language, please specify settings={'SKIP_TOKENS': []} to correctly parse relative dates.

Date Order

.. code:: python

>>> # parsing ambiguous date
>>> parse('02-03-2016')  # assumes english language, uses MDY date order
datetime.datetime(2016, 2, 3, 0, 0)
>>> parse('le 02-03-2016')  # detects french, uses DMY date order
datetime.datetime(2016, 3, 2, 0, 0)

.. note:: Ordering is not locale-based — do not expect DMY order for UK/Australia English. You can specify date order explicitly:

.. code:: python

   >>> parse('18-12-15 06:00', settings={'DATE_ORDER': 'DMY'})
   datetime.datetime(2015, 12, 18, 6, 0)

This is the beginning of the README. Read the rest at the original. Read the full README ↗