Skip to content

month() - Pine Script Function

`month()`

Overview

month() extracts the calendar month (1 for January through 12 for December) from a UNIX timestamp. By default it evaluates the timestamp in the instrument’s exchange timezone, but you can convert to any IANA timezone or UTC offset when you need to align data from multiple markets.

Because the function uses the bar’s opening time, overnight sessions may report the previous calendar date. Adjust with a timezone override or the session input in time() if you need session-based months.

Syntax

month(time, timezone) → series int

Parameters

Name	Type	Description
`time`	`series int`	UNIX timestamp in milliseconds (e.g., `time` or a value from `request.security()`).
`timezone`	`series string` (optional)	Target timezone expressed as `"UTC±HH[:MM]"` or an IANA identifier such as `"Europe/London"`. Defaults to `syminfo.timezone`.

Returns

series int — Month number corresponding to the timestamp.

Remarks

Guard against na when accessing month(time[1]) on the first historical bar.
Use together with year() and dayofmonth() to build composite date keys for seasonality analysis.
Session-shifted symbols (e.g., FX pairs opening Sunday evening) may produce month values that differ from the trading calendar. Compare with time(timeframe.period, session) when you require session boundaries.

Example

//@version=5
indicator("Monthly boundaries", overlay=true, max_labels_count=500)

currMonth = month(time)
priorMonth = nz(month(time[1]), currMonth)
isNewMonth = currMonth != priorMonth

plotshape(isNewMonth, title="New month marker", style=shape.labeldown,
    text=str.tostring(currMonth),
    color=color.new(color.blue, 0),
    textcolor=color.white,
    location=location.abovebar,
    size=size.tiny)

bgcolor(isNewMonth ? color.new(color.blue, 92) : na,
    title="Highlight first session of the month")

See Also