> ## Documentation Index
> Fetch the complete documentation index at: https://docs.northaxiumdata.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Contract Stats

> Aggregated contract statistics grouped by department, vendor, or year.

## Overview

Returns grouped aggregate statistics across all federal contract records. Useful for spending breakdowns by department, vendor rankings by total value, or year-over-year procurement trends.

## Query Parameters

<ParamField query="group_by" type="string">
  Grouping dimension. Options: `department`, `vendor`, `year`. Default: `department`. Example: `vendor`.
</ParamField>

<ParamField query="sum_field" type="string">
  Only `value`. Default: `value`. Example: `amount`.
</ParamField>

<ParamField query="vendor" type="string">
  Partial match on vendor name. Example: `Palantir`.
</ParamField>

<ParamField query="department" type="string">
  Partial match on department name. Example: `National Defence`.
</ParamField>

<ParamField query="method" type="string">
  Exact match on `procurement_method`. Example: `Non-competitive`.
</ParamField>

<ParamField query="source" type="string">
  Exact match on `source_dataset`. Example: `open.canada`.
</ParamField>

<ParamField query="min_value" type="number">
  Minimum contract value. Example: `100000`.
</ParamField>

<ParamField query="max_value" type="number">
  Maximum contract value. Example: `5000000`.
</ParamField>

<ParamField query="date_from" type="string">
  ISO 8601 start date. Example: `2023-01-01`.
</ParamField>

<ParamField query="date_to" type="string">
  ISO 8601 end date. Example: `2023-12-31`.
</ParamField>

<ParamField query="limit" type="integer">
  Max groups to return. Default: `100`. Max: `200`. Example: `25`.
</ParamField>

<ParamField query="offset" type="integer">
  Result offset. Default: `0`. Example: `50`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -H "X-API-Key: your_api_key_here" \
    "https://api.northaxiumdata.ca/api/v1/contracts/stats?group_by=department&department=National%20Defence&limit=10"
  ```

  ```python Python theme={null}
  import requests

  headers = {"X-API-Key": "your_api_key_here"}
  params = {
      "group_by": "department",
      "department": "National Defence",
      "limit": 10
  }

  response = requests.get(
      "https://api.northaxiumdata.ca/api/v1/contracts/stats",
      headers=headers,
      params=params
  )
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "group_by": "department",
        "group_value": "National Defence | Défense nationale",
        "record_count": 18432,
        "sum_field": "value",
        "sum_value": 4821034521.00
      },
      {
        "group_by": "department",
        "group_value": "Public Services and Procurement Canada | Services publics et Approvisionnement Canada",
        "record_count": 12891,
        "sum_field": "value",
        "sum_value": 3109823400.00
      }
    ],
    "meta": {
      "total": 482,
      "limit": 10,
      "offset": 0
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "BAD_REQUEST",
      "message": "group_by must be one of: department, vendor, year."
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Missing API key. Pass your key in the X-API-Key header."
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Monthly request limit exceeded. Upgrade your plan for higher limits."
    }
  }
  ```
</ResponseExample>