> For the complete documentation index, see [llms.txt](https://docs.metarank.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.metarank.ai/reference/overview/feature-extractors/datetime.md).

# Date and Time

## local\_time extractor

This extractor is useful when you need to parse a local date-time and get a time-of-day (or something similar) from there to catch a seasonality: maybe visitor behavior is different on morning and in evening? Given the event:

```json
{
  "event": "ranking",
  "id": "81f46c34-a4bb-469c-8708-f8127cd67d27",
  "timestamp": "1599391467000",
  "user": "user1",
  "session": "session1",
  "fields": [
      {"name": "localts", "value": "2021-12-03T10:15:30+01:00"}
  ],
  "items": [
    {"id": "item3"},
    {"id": "item1"},
    {"id": "item2"} 
  ]
}
```

and the following feature config:

```yaml
- name: time
  type: local_time
  parse: time_of_day // can be day_of_week/time_of_day/day_of_month/month_of_year/year/second
  source: ranking.localts // can only work with ranking event types, the field must be string with ISO-formatted zoned datetime
```

This extractor will pull the `10:15:30+01:00`, and map it into a `0..23.99` range, so one second before midnight will be 0.99, and midday will be 0.5.

This extractor can use both a separate field or an event-level `ranking.timestamp` one.

Supported `parse` field values:

* `day_of_week`: day number in 1..7 range, where Monday is 1
* `time_of_day`: local time in 0.0..23.99 range
* `day_of_month`: day of current month in 1..31 range
* `month_of_year`: current month in 1..12 range
* `year`: absolute current year value
* `second`: current local timestamp in seconds from epoch start

## item\_age

Sometimes it can be useful to know how fresh is the item in the ranking? Consider the following item metadata event:

```json
{
  "event": "item",
  "id": "81f46c34-a4bb-469c-8708-f8127cd67d27",
  "item": "product1", 
  "timestamp": "1599391467000",
  "fields": [
    {"name": "created_at", "value": "2021-12-03T10:15:30+01:00"}
  ]
}
```

It's possible to compute how much time has passed from the `created_at` field value till now, with the following config snippet:

```yaml
- name: freshness
  type: item_age
  source: item.created_at // can only work with item metadata event types
  refresh: 0s // optional, how frequently we should update the value, 0s by default
  ttl: 90d // optional, how long should we store this field
```

The `source` field should have any of the following types:

* `string`, ISO8601 date+time+timezone, example: "2021-12-03T10:15:30+01:00"
* `number`, unixtime (number of seconds from epoch start), example `1648483661`
* `string`, unixtime as a string (so there will be no json number rounding), example: `"1648483661"`
* you can reference the event timestamp (not the free-form field, but the native top-level event timestamp) with a `item.timestamp`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.metarank.ai/reference/overview/feature-extractors/datetime.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.