Skip to content

📊 DogeAnalytics

DogeAnalytics is a high-level reporting layer built on top of SavingsAPI. It helps you quickly rank and summarize grants, leases, and contracts using the DOGE API, returning ready-to-use pandas.DataFrame results.

🚀 Instantiating DogeAnalytics

Python
from pydoge_api import DogeAnalytics

with DogeAnalytics(fetch_all=True) as da:
    top = da.top_agencies_by_savings(top_n=10)
    print(top)

❗ Without context manager

Python
da = DogeAnalytics(fetch_all=True)
top = da.top_agencies_by_savings(top_n=10)
da.close()  # Don't forget to close manually

♻️ Reusing an existing client

Python
from pydoge_api import DogeAPI, DogeAnalytics

with DogeAPI(fetch_all=True) as api:
    da = DogeAnalytics(client=api.client, fetch_all=True)
    print(da.lease_area_summary())

⚙️ Constructor Parameters

Param Description Default
client Reuse an existing DogeAPIClient. If omitted, a new DogeAPI is created internally None
fetch_all Fetch all pages for paginated responses False
output_pydantic Return full Pydantic model vs plain dict True
handle_response Whether to parse and return the response body True
run_async Enable async pagination where supported False
**api_kwargs Additional kwargs forwarded to DogeAPI / DogeAPIClient (e.g. headers, timeout)

Tip

For meaningful rankings you almost always want fetch_all=True — otherwise only the first page (default 100 records) is aggregated.

🏆 Available analytics methods

Method Returns (DataFrame columns)
top_agencies_by_savings(top_n=10) Agency, Total Savings
top_contracts_by_value(top_n=10) all contract columns, sorted by value
lease_area_summary() Agency, Total Square Feet
top_agencies_by_leases(top_n=10) agency, savings
top_agencies_by_contracts(top_n=10) agency, savings
Python
with DogeAnalytics(fetch_all=True) as da:
    da.top_agencies_by_savings(top_n=10)
    da.top_contracts_by_value(top_n=10)
    da.lease_area_summary()
    da.top_agencies_by_leases(top_n=5)
    da.top_agencies_by_contracts(top_n=3)

📑 Need the raw data instead?

DogeAnalytics exposes the underlying SavingsAPI as .savings, so you can pull a full DataFrame and run your own analysis:

Python
with DogeAnalytics(fetch_all=True) as da:
    grants_df = da.savings.get_grants().to_dataframe()
    contracts_df = da.savings.get_contracts().to_dataframe()
    leases_df = da.savings.get_leases().to_dataframe()

💾 Exporting Results

Use .export_dataset() to save any DataFrame with a timestamped filename. It returns the written Path.

Python
with DogeAnalytics(fetch_all=True) as da:
    df = da.top_agencies_by_savings()
    path = da.export_dataset(df, "top_savers", format="xlsx")
    print(f"Saved to: {path}")

Supported Formats

  • csv → comma-separated
  • xlsx → Excel spreadsheet
  • json → pretty-printed array

📦 Class Reference

DogeAnalytics(client: Optional[DogeAPIClient] = None, **api_kwargs)

High-level analytics engine for grants, contracts, and leases using SavingsAPI.

Every method returns a ranked/aggregated pandas.DataFrame. Requires parsed responses (handle_response=True, the default); pass fetch_all=True for meaningful rankings over the full dataset.

client : DogeAPIClient, optional If provided, reuses the existing client (its lifecycle stays with the caller). Otherwise a new client is created internally. **api_kwargs : dict Passed to DogeAPI (e.g. fetch_all=True, run_async=True).

METHOD DESCRIPTION
close

Close the internal session (no-op when reusing an injected client).
Source code in src/pydoge_api/analytic.py
Python
19
20
21
22
23
24
25
26
27
28
29
30
31
32
def __init__(self, client: Optional[DogeAPIClient] = None, **api_kwargs):
    """
    Parameters
    ----------
    client : DogeAPIClient, optional
        If provided, reuses the existing client (its lifecycle stays with the
        caller). Otherwise a new client is created internally.
    **api_kwargs : dict
        Passed to DogeAPI (e.g. fetch_all=True, run_async=True).
    """
    if api_kwargs.get("handle_response") is False:
        raise ValueError("DogeAnalytics needs parsed data; handle_response must be True.")
    self._api = DogeAPI(client=client, **api_kwargs)
    self.savings = self._api.savings

close()

Close the internal session (no-op when reusing an injected client).

Source code in src/pydoge_api/analytic.py
Python
81
82
83
def close(self):
    """Close the internal session (no-op when reusing an injected client)."""
    self._api.close()