Skip to content

SavingsAPI

SavingsAPI(client: DogeAPIClient, api: DogeAPI)

Access all endpoints under /savings including grants, contracts, and leases.

This class handles paginated retrieval of financial savings data via a shared DogeAPIClient. Supports both Pydantic model and dict export modes.

client : DogeAPIClient Shared HTTP client instance for making API calls. api : DogeAPI Reference to parent DogeAPI instance for runtime config flags.

METHOD DESCRIPTION
get_grants

Retrieve cancelled or reduced government grants.
get_contracts

Retrieve cancelled or optimized government contracts.
get_leases

Retrieve terminated or downsized government leases.
Source code in src/pydoge_api/endpoints/savings.py
Python
23
24
25
26
27
28
29
30
31
32
33
def __init__(self, client: DogeAPIClient, api: "DogeAPI"):
    """
    Parameters
    ----------
    client : DogeAPIClient
        Shared HTTP client instance for making API calls.
    api : DogeAPI
        Reference to parent DogeAPI instance for runtime config flags.
    """
    self.client = client
    self.api = api

get_grants(*, sort_by: Optional[str] = None, sort_order: Optional[str] = None, page: int = 1, per_page: int = 100) -> Union[GrantResponse, dict, httpx.Response]

Retrieve cancelled or reduced government grants.

PARAMETER DESCRIPTION

sort_by

Field to sort by. Options include 'savings', 'value', or 'date'.

TYPE: str DEFAULT: None

sort_order

Sort direction. One of 'asc' or 'desc'.

TYPE: str DEFAULT: None

page

Starting page number for paginated results.

TYPE: int DEFAULT: 1

per_page

Number of records to retrieve per page.

TYPE: int DEFAULT: 100

RETURNS DESCRIPTION
GrantResponse or dict or Response

Pydantic model if output_pydantic=True, exportable dict if output_pydantic=False, or raw response if handle_response=False.
Source code in src/pydoge_api/endpoints/savings.py
Python
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def get_grants(
    self, *, sort_by: Optional[str] = None, sort_order: Optional[str] = None, page: int = 1, per_page: int = 100
) -> Union[GrantResponse, dict, httpx.Response]:
    """
    Retrieve cancelled or reduced government grants.

    Parameters
    ----------
    sort_by : str, optional
        Field to sort by. Options include 'savings', 'value', or 'date'.
    sort_order : str, optional
        Sort direction. One of 'asc' or 'desc'.
    page : int, default=1
        Starting page number for paginated results.
    per_page : int, default=100
        Number of records to retrieve per page.

    Returns
    -------
    GrantResponse or dict or httpx.Response
        Pydantic model if `output_pydantic=True`,
        exportable dict if `output_pydantic=False`,
        or raw response if `handle_response=False`.
    """
    params = GrantParams(sort_by=sort_by, sort_order=sort_order, page=page, per_page=per_page)
    query = params.model_dump(exclude_none=True)

    logger.info(f"💸 Fetching grants (sort_by={sort_by!r}, per_page={per_page}, fetch_all={self.api.fetch_all})")
    result = self.client.get("/savings/grants", params=query, decode=self.api.handle_response)
    if not self.api.handle_response:
        return result

    model = GrantResponse(**cast(dict, result))

    return _fetch_paginated(
        api=self.api,
        client=self.client,
        endpoint="/savings/grants",
        params=params,
        initial_response=model,
        key="grants",
        model_cls=GrantResponse,
    )

get_contracts(*, sort_by: Optional[str] = None, sort_order: Optional[str] = None, page: int = 1, per_page: int = 100) -> Union[ContractResponse, dict, httpx.Response]

Retrieve cancelled or optimized government contracts.

PARAMETER DESCRIPTION

sort_by

Field to sort by. Options include 'savings', 'value', or 'date'.

TYPE: str DEFAULT: None

sort_order

Sort direction. One of 'asc' or 'desc'.

TYPE: str DEFAULT: None

page

Starting page number for paginated results.

TYPE: int DEFAULT: 1

per_page

Number of records to retrieve per page.

TYPE: int DEFAULT: 100

RETURNS DESCRIPTION
ContractResponse or dict or Response

Pydantic model if output_pydantic=True, exportable dict if output_pydantic=False, or raw response if handle_response=False.
Source code in src/pydoge_api/endpoints/savings.py
Python
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def get_contracts(
    self, *, sort_by: Optional[str] = None, sort_order: Optional[str] = None, page: int = 1, per_page: int = 100
) -> Union[ContractResponse, dict, httpx.Response]:
    """
    Retrieve cancelled or optimized government contracts.

    Parameters
    ----------
    sort_by : str, optional
        Field to sort by. Options include 'savings', 'value', or 'date'.
    sort_order : str, optional
        Sort direction. One of 'asc' or 'desc'.
    page : int, default=1
        Starting page number for paginated results.
    per_page : int, default=100
        Number of records to retrieve per page.

    Returns
    -------
    ContractResponse or dict or httpx.Response
        Pydantic model if `output_pydantic=True`,
        exportable dict if `output_pydantic=False`,
        or raw response if `handle_response=False`.
    """
    params = ContractParams(sort_by=sort_by, sort_order=sort_order, page=page, per_page=per_page)
    query = params.model_dump(exclude_none=True)

    logger.info(f"📑 Fetching contracts (sort_by={sort_by!r}, per_page={per_page}, fetch_all={self.api.fetch_all})")
    result = self.client.get("/savings/contracts", params=query, decode=self.api.handle_response)
    if not self.api.handle_response:
        return result

    model = ContractResponse(**cast(dict, result))

    return _fetch_paginated(
        api=self.api,
        client=self.client,
        endpoint="/savings/contracts",
        params=params,
        initial_response=model,
        key="contracts",
        model_cls=ContractResponse,
    )

get_leases(*, sort_by: Optional[str] = None, sort_order: Optional[str] = None, page: int = 1, per_page: int = 100) -> Union[LeaseResponse, dict, httpx.Response]

Retrieve terminated or downsized government leases.

PARAMETER DESCRIPTION

sort_by

Field to sort by. Options include 'savings', 'value', or 'date'.

TYPE: str DEFAULT: None

sort_order

Sort direction. One of 'asc' or 'desc'.

TYPE: str DEFAULT: None

page

Starting page number for paginated results.

TYPE: int DEFAULT: 1

per_page

Number of records to retrieve per page.

TYPE: int DEFAULT: 100

RETURNS DESCRIPTION
LeaseResponse or dict or Response

Pydantic model if output_pydantic=True, exportable dict if output_pydantic=False, or raw response if handle_response=False.
Source code in src/pydoge_api/endpoints/savings.py
Python
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def get_leases(
    self, *, sort_by: Optional[str] = None, sort_order: Optional[str] = None, page: int = 1, per_page: int = 100
) -> Union[LeaseResponse, dict, httpx.Response]:
    """
    Retrieve terminated or downsized government leases.

    Parameters
    ----------
    sort_by : str, optional
        Field to sort by. Options include 'savings', 'value', or 'date'.
    sort_order : str, optional
        Sort direction. One of 'asc' or 'desc'.
    page : int, default=1
        Starting page number for paginated results.
    per_page : int, default=100
        Number of records to retrieve per page.

    Returns
    -------
    LeaseResponse or dict or httpx.Response
        Pydantic model if `output_pydantic=True`,
        exportable dict if `output_pydantic=False`,
        or raw response if `handle_response=False`.
    """
    params = LeaseParams(sort_by=sort_by, sort_order=sort_order, page=page, per_page=per_page)
    query = params.model_dump(exclude_none=True)

    logger.info(f"🏢 Fetching leases (sort_by={sort_by!r}, per_page={per_page}, fetch_all={self.api.fetch_all})")
    result = self.client.get("/savings/leases", params=query, decode=self.api.handle_response)
    if not self.api.handle_response:
        return result

    model = LeaseResponse(**cast(dict, result))

    return _fetch_paginated(
        api=self.api,
        client=self.client,
        endpoint="/savings/leases",
        params=params,
        initial_response=model,
        key="leases",
        model_cls=LeaseResponse,
    )