Skip to main content
`Ctrl`+`K`

# pandas.Timestamp.ceil

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

  Return a new Timestamp ceiled to this resolution.

  Parameters:
    freq str

      Frequency string 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')

  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')