Timestamp.ceil(freq, ambiguous='raise', nonexistent='raise')

Return a new Timestamp ceiled to this resolution.


Frequency string indicating the ceiling resolution.

ambiguousbool or {‘raise’, ‘NaT’}, default ‘raise’

The behavior is as follows:

  • bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates).

  • ‘NaT’ will return NaT for an ambiguous time.

  • ‘raise’ will raise an AmbiguousTimeError for an ambiguous time.

nonexistent{‘raise’, ‘shift_forward’, ‘shift_backward, ‘NaT’, timedelta}, default ‘raise’

A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST.

  • ‘shift_forward’ will shift the nonexistent time forward to the closest existing time.

  • ‘shift_backward’ will shift the nonexistent time backward to the closest existing time.

  • ‘NaT’ will return NaT where there are nonexistent times.

  • timedelta objects will shift nonexistent times by the timedelta.

  • ‘raise’ will raise an NonExistentTimeError if there are nonexistent times.

ValueError if the freq cannot be converted.


Create a timestamp object:

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651')

A timestamp can be ceiled using multiple frequency units:

>>> ts.ceil(freq='H') # hour
Timestamp('2020-03-14 16:00:00')
>>> ts.ceil(freq='T') # minute
Timestamp('2020-03-14 15:33:00')
>>> ts.ceil(freq='S') # seconds
Timestamp('2020-03-14 15:32:53')
>>> ts.ceil(freq='U') # microseconds
Timestamp('2020-03-14 15:32:52.192549')

freq can also be a multiple of a single unit, like ‘5T’ (i.e. 5 minutes):

>>> ts.ceil(freq='5T')
Timestamp('2020-03-14 15:35:00')

or a combination of multiple units, like ‘1H30T’ (i.e. 1 hour and 30 minutes):

>>> ts.ceil(freq='1H30T')
Timestamp('2020-03-14 16:30:00')

Analogous for pd.NaT:

>>> pd.NaT.ceil()