pydoge-api 0.3.0

PyDOGE API is an advanced, Python wrapper for interacting with the public-facing API of the Department of Government Efficiency (DOGE)

A Python library to interact with the Department of Government Efficiency (DOGE) API.

📃 Documentation  ·  🔧 Report Bug

🧾 Table of Contents

1. About The Project
2. Highlights
3. Getting Started
   • Installation
4. Usage
   • Get Grants and sorted by savings
   • Get Contracts and sorted by savings
   • Get Leases
   • Get Payments and filter payments by agency
   • Without using Context Manager
5. Contributors
6. Acknowledgements

🐍 About The Project

PyDOGE API is an advanced, Python wrapper for interacting with the public-facing API of the Department of Government Efficiency (DOGE) — a federal initiative aimed at increasing transparency and fiscal accountability by sharing detailed datasets on:

• 💸 Cancelled grants
• 📑 Contract terminations
• 🏢 Lease reductions
• 🧾 Payment transactions

🚀 Features

• Auto-pagination (sync or async, fetch all pages if needed)
• .export() to CSV, Excel, or JSON with timestamped filenames
• .to_dataframe() for Pandas users
• .summary() with analytics (rows, nulls, dtypes, stats)
• summary(save_as="...") for file logging
• Returns Pydantic models & dict output
• Retry-safe client with 429 handling
• savings.all() — one tidy DataFrame across grants, contracts & leases
• 🖥️ Modern pydoge CLI (Typer + Rich) for fetch / export / summary
• 📈 Built-in charts (bar, time-series, distribution, US-state choropleth) via the [viz] extra
• 🔒 Secure logging powered by PyLogShield

This package enables data scientists and analysts to programmatically access and analyze the data with ease.

📌 Getting Started

Installation

Install:

pip install pydoge-api

Upgrade:

pip install --upgrade pydoge-api

Documentation

Full developer docs with API reference, usage, and model schema:

• 👉 Docs and Examples (PyDOGE)
• 👉 Official Swagger Page

📚 Usage

Get Grants and sorted by savings

from pydoge_api import DogeAPI

with DogeAPI(fetch_all=True, run_async=False) as api:
    grants = api.savings.get_grants(sort_by="savings")
    df = grants.to_dataframe()
    print(df.head())

    # Export to CSV
    grants.export("grants_q1", format="csv")
    
    # Show summary in terminal
    grants.summary(verbose=True)
    
    # Save the summary as markdown
    grants.summary(save_as="logs/grants_summary.md")

Get Contracts and sorted by savings

with DogeAPI(fetch_all=True, run_async=False) as api:
    contracts = api.savings.get_contracts(sort_by="savings")
    df = contracts.to_dataframe()
    print(df.head())

    # Export to CSV
    contracts.export("contracts_q1", format="csv")
    
    # Show summary in terminal
    contracts.summary(verbose=True)
    
    # Save the summary as markdown
    contracts.summary(save_as="logs/contracts_summary.md")

Get Leases

with DogeAPI(fetch_all=True, run_async=False) as api:
    leases = api.savings.get_leases()
    df = leases.to_dataframe()
    print(df.head())
    
    # Export to CSV
    leases.export("leases_q1", format="csv")
    
    # Show summary in terminal
    leases.summary(verbose=True)
    
    # Save the summary as markdown
    leases.summary(save_as="logs/leases_summary.md")

Get Payments and filter payments by agency

with DogeAPI(fetch_all=True, run_async=False) as api:
    payments = api.payments.get_payments(filter="agency_name", filter_value="NASA")
    df =payments.to_dataframe()
    print(df.head())
    
    # Export to CSV
    payments.export("payments_q1", format="csv")
    
    # Show summary in terminal
    payments.summary(verbose=True)
    
    # Save the summary as markdown
    payments.summary(save_as="logs/payments_summary.md")

Without using Context Manager

api = DogeAPI(
    fetch_all=True, # Get all records if True. Default False
    run_async=False # For Async set this to True
)

try:
    # Get Grants and sorted by savings
    grants = api.savings.get_grants(sort_by="savings")
    
    # Get Contracts and sorted by savings
    contracts = api.savings.get_contracts(sort_by="savings")
    
    # Get Leases
    leases = api.savings.get_leases()
    
    # Get Payments and filter payments by agency
    payments = api.payments.get_payments(filter="agency_name", filter_value="NASA")
    
    # Export to CSV
    grants.export("grants_q1", format="csv")
    
    # Show summary in terminal
    grants.summary(verbose=True)
    
    # Save the summary as markdown
    grants.summary(save_as="logs/grants_summary.md")
    
finally:
    api.close()
    

(back to top)

🔒 Secure Logging

PyDOGE API logs through PyLogShield instead of the bare standard library. Out of the box this scrubs cloud-credential prefixes (AWS_, AZURE_, GCP_, GOOGLE_, TOKEN) from every record, and you can opt into sensitive-value masking per call:

from pydoge_api._logging import get_logger

# Customize the SDK logger (e.g. JSON output, a custom log directory)
log = get_logger("pydoge_api", enable_json=True)
log.warning("token=abc123 leaked into a message", mask=True)  # -> token=***

The logger is created lazily on the first log call (so import pydoge_api has no side effects). On first use PyLogShield writes to ~/.logs/pydoge_api.log; pass add_console=False or a custom log_directory to get_logger(...) to change this.

(back to top)

👪 Contributors

All contributions are welcome. If you have a suggestion that would make this better, please fork the repo and create a merge request. You can also simply open an issue with the label 'enhancement'.

Don't forget to give the project a star! Thanks again!

👏 Acknowledgments

Inspiration, code snippets, etc.

(back to top)