Skip to main content
`Ctrl`+`K`

# pandas.Timestamp.ceil

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

  Return a new Timestamp ceiled to this resolution.

  This method rounds the Timestamp up to the nearest boundary of the given frequency. The result will never be earlier than the original Timestamp.

  Parameters:
    freq str or timedelta

      Frequency string or timedelta value indicating the ceiling resolution.

    ambiguous bool 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 a ValueError 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 a ValueError if there are nonexistent times.

  Raises:
    ValueError if the freq cannot be converted.

  See also

  `Timestamp.floor`

    Round down a Timestamp to the specified resolution.

  `Timestamp.round`

    Round a Timestamp to the specified resolution.

  `Series.dt.ceil`

    Ceil the datetime values in a Series.

  Notes

  If the Timestamp has a timezone, ceiling will take place relative to the local (“wall”) time and re-localized to the same timezone. When ceiling near daylight savings time, use `nonexistent` and `ambiguous` to control the re-localization behavior.

  Examples

  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='min')  # minute
      Timestamp('2020-03-14 15:33:00')

      >>> ts.ceil(freq='s')  # seconds
      Timestamp('2020-03-14 15:32:53')

      >>> ts.ceil(freq='us')  # microseconds
      Timestamp('2020-03-14 15:32:52.192549')

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

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

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

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

  `freq` can also be a timedelta value:

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

  Analogous for `pd.NaT`:

      >>> pd.NaT.ceil()
      NaT

  When rounding near a daylight savings time transition, use `ambiguous` or `nonexistent` to control how the timestamp should be re-localized.

      >>> ts_tz = pd.Timestamp("2021-10-31 01:30:00").tz_localize("Europe/Amsterdam")

      >>> ts_tz.ceil("h", ambiguous=False)
      Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')

      >>> ts_tz.ceil("h", ambiguous=True)
      Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')