# Date\_Filtering\_Guide

## Purpose

Use this guide to set date filters correctly in GovTribe `Search_*` tools using plain dates or Elasticsearch date math. Use it when:

* users ask for time-bounded results such as last 30 days or due next week.
* setting any `*_date_range` field in a request payload.
* building broad award/IDV horizon scans that should be aggregation-first.

## Construction Rules

### Range Object Shape

* Date range objects should include both keys:
  * `from`
  * `to`
* If one side is open-ended, keep the key and set it to `null`.

### Supported Date Values

* Use one of these value styles:
  * plain date values (example `2026-03-02`)
  * Elasticsearch date math (example `now-90d/d`, `2026-01-01||+1M/d`)
* Use fixed dates when reproducibility matters.

### Field Selection Guide

* Use the date field that matches user intent:
  * `award_date_range`: award issue date.
  * `posted_date`: posting date.
  * `due_date_range`: response deadline.
  * `ultimate_completion_date_range`: completion horizon.
  * `last_date_to_order_range`: IDV ordering deadline.
  * `estimated_solicitation_release_date_range`: forecasted release timing.
  * `anticipated_award_start_date_range`: forecasted start timing.
* For broad award/IDV horizon scans, pair date windows with `aggregations` first.

## Examples

Rolling 90-day federal award scan (agg-first): Tool: `Search_Federal_Contract_Awards`

```json
{
  "query": "",
  "award_date_range": {
    "from": "now-90d/d",
    "to": "now/d"
  },
  "aggregations": ["top_awardees_by_dollars_obligated"]
}
```

Open-ended posted-date filter: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "query": "",
  "posted_date": {
    "from": "2026-01-01",
    "to": null
  }
}
```

Future due-date window: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "query": "",
  "due_date_range": {
    "from": "now/d",
    "to": "now+30d/d"
  }
}
```