fiscaldataapi 0.0.2
A Python wrapper to easily retrieve data from the Fiscal Data (US Treasury) official API in pandas format.
License: MIT License

# fiscaldataapi
This repository contains a Python wrapper to easily retrieve data from the Fiscal Data (US Treasury) official API in pandas format.

## Overview
The U.S. Department of the Treasury is building a suite of open-source tools to deliver standardized information about federal finances to the public. We are working to centralize publicly available financial data, and this website will include datasets from the Fiscal Service on topics including debt, revenue, spending, interest rates, and savings bonds.
## Requirements
- Python 3.9 or higher.
- Requests
- Pandas

## Installation
```terminal
pip install fiscaldataapi
```

## Get Fiscal Data
### get_fiscaldata
Get FiscalData table from Treasury series data.

```python
from fiscaldataapi import get_fiscaldata
df = get_fiscaldata(database, **kwargs)
```

#### Parameters
| Parameter  | Type  | Description                |
|------------|-------|----------------------------|
| `database` | `str` | Table name of the endpoint |

#### Keyword Arguments
| Parameter     | Type         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|---------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `fields`      | `str`        | The fields parameter allows you to select which field(s) should be included. If desired fields are not specified, all fields will be returned. When a file name passed to the fields parameter is not available for the endpoint accessed, an error will occur.                                                                                                                                                                                                                                                                                          |
| `filter`      | `str`        | Filters are used to view a subset of the data based on specific criteria. For example, you may want to find data that falls within a certain date range, or only show records which contain a value larger than a certain threshold.  Use a colon at the end of a filter parameter to pass a value or list of values. For lists passed as filter criteria, use a comma-separated list within parentheses. Filter for specific dates using the format YYYY-MM-DD. When no filters are provided, the default response will return all fields and all data. |
| `sort`        | `str`        | The sort parameter allows a user to sort a field in ascending (least to greatest) or descending (greatest to least) order. The sort parameter accepts a comma-separated list of field names. When no sort parameter is specified, the default is to sort by the first column listed.                                                                                                                                                                                                                                                                     |
| `page_size`   | `str or int` | The page size will set the number of rows that are returned on a request. When no page size parameter is specified, the default response is 100.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `page_number` | `str or int` | The page number will set the index for the pagination, starting at 1. When no page number is specified, the default response is 1.                                                                                                                                                                                                                                                                                                                                                                                                                       |

#### Returns
- pd.DataFrame: Dataframe containing the FiscalData endpoint table data.


### info_fiscaldata
Get information of a FiscalData table.

```python
from fiscaldataapi import info_fiscaldata
df = info_fiscaldata(database)
```

#### Parameters
| Parameter  | Type  | Description                |
|------------|-------|----------------------------|
| `database` | `str` | Table name of the endpoint |

#### Returns
- tuple(dict, int, int): Dictionary with the format of the table columns, the number of pages of table data (each page has up to 100 rows) and number of total rows of table data.



## Table of tables and endpoints
| Dataset                                                              | Table Name                                                                                           | Endpoint                                                                                     | Endpoint Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 120 Day Delinquent Debt Referral Compliance Report                   | 120 Day Delinquent Debt Referral Compliance Report                                                   | `/v2/debt/tror/data_act_compliance`                                                          | The 120 Day Delinquent Debt Referral Compliance Report provides access to tracking and benchmarking compliance with the requirements of a key provision of the Digital Accountability and Transparency Act of 2014 (the DATA Act). This table provides quick insights into federal agency compliance rates, as well as information on the number of eligible debts and debts referred or not referred each quarter, beginning in Fiscal Year 2016.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Accrual Savings Bonds Redemption Tables (Discontinued)               | Redemption Tables                                                                                    | `/v2/accounting/od/redemption_tables`                                                        | The Redemption Tables dataset contains monthly tables that list the redemption value, interest earned, and yield of accrual savings bonds purchased since 1941. Each monthly report lists the redemption value of all bonds at the time of publication. Investors and bond owners can use this dataset as an easy and understandable reference to know the redemption value of the bonds they hold.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Advances to State Unemployment Funds (Social Security Act Title XII) | Advances to State Unemployment Funds (Social Security Act Title XII)                                 | `/v2/accounting/od/title_xii`                                                                | Monthly balances for securities outstanding and principal outstanding for State and Local Government Series (SLGS) securities.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Average Interest Rates on U.S. Treasury Securities                   | Average Interest Rates on U.S. Treasury Securities                                                   | `/v2/accounting/od/avg_interest_rates`                                                       | Average interest rates for marketable and non-marketable securities.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Daily Treasury Statement (DTS)                                       | Operating Cash Balance                                                                               | `/v1/accounting/dts/operating_cash_balance`                                                  | This table represents the Treasury General Account balance. Additional detail on changes to the Treasury General Account can be found in the Deposits and Withdrawals of Operating Cash table. All figures are rounded to the nearest million.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Daily Treasury Statement (DTS)                                       | Deposits and Withdrawals of Operating Cash                                                           | `/v1/accounting/dts/deposits_withdrawals_operating_cash`                                     | This table represents deposits and withdrawals from the Treasury General Account. A summary of changes to the Treasury General Account can be found in the Operating Cash Balance table. All figures are rounded to the nearest million.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Daily Treasury Statement (DTS)                                       | Public Debt Transactions                                                                             | `/v1/accounting/dts/public_debt_transactions`                                                | This table represents the issues and redemption of marketable and nonmarketable securities. All figures are rounded to the nearest million.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Daily Treasury Statement (DTS)                                       | Adjustment of Public Debt Transactions to Cash Basis                                                 | `/v1/accounting/dts/adjustment_public_debt_transactions_cash_basis`                          | This table represents cash basis adjustments to the issues and redemptions of Treasury securities in the Public Debt Transactions table. All figures are rounded to the nearest million.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Daily Treasury Statement (DTS)                                       | Debt Subject to Limit                                                                                | `/v1/accounting/dts/debt_subject_to_limit`                                                   | This table represents the breakdown of total public debt outstanding as it relates to the statutory debt limit. All figures are rounded to the nearest million.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Daily Treasury Statement (DTS)                                       | Inter-Agency Tax Transfers                                                                           | `/v1/accounting/dts/inter_agency_tax_transfers`                                              | This table represents the breakdown of inter-agency tax transfers within the federal government. All figures are rounded to the nearest million.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Daily Treasury Statement (DTS)                                       | Income Tax Refunds Issued                                                                            | `/v1/accounting/dts/income_tax_refunds_issued`                                               | This table represents the breakdown of tax refunds by recipient (individual vs business) and type (check vs electronic funds transfer). Tax refunds are also represented as withdrawals in the Deposits and Withdrawals of Operating Cash table. All figures are rounded to the nearest million. As of February 14, 2023, Table VI Income Tax Refunds Issued was renamed to Table V Income Tax Refunds Issued within the published report.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Daily Treasury Statement (DTS)                                       | Federal Tax Deposits                                                                                 | `/v1/accounting/dts/federal_tax_deposits`                                                    | This table represents the breakdown of taxes that are received by the federal government. Federal taxes received are represented as deposits in the Deposits and Withdrawals of Operating Cash table. All figures are rounded to the nearest million.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Daily Treasury Statement (DTS)                                       | Short-Term Cash Investments                                                                          | `/v1/accounting/dts/short_term_cash_investments`                                             | This table represents the amount Treasury has in short-term cash investments. Deposits and withdrawals of short-term cash investments are also represented in the Deposits and Withdrawals of Operating Cash table. This program was suspended indefinitely in 2008. All figures are rounded to the nearest million. As of February 14, 2023, Table V Short Term Cash Investments will no longer be updated and removed from the published report. The historical data will remain available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Debt to the Penny                                                    | Debt to the Penny                                                                                    | `/v2/accounting/od/debt_to_penny`                                                            | Outstanding U.S. debt on a daily basis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Electronic Securities Transactions                                   | Sales                                                                                                | `/v1/accounting/od/securities_sales`                                                         | Securities Issued in TreasuryDirect: Sales provides gross sales, returns, net sales, and count of securities for marketable securities and savings bonds issued in TreasuryDirect. Securities are available by security class: bills, notes, bonds, and TIPS for marketable securities and Series E, EE, and I for savings bonds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Electronic Securities Transactions                                   | Sales by Term                                                                                        | `/v1/accounting/od/securities_sales_term`                                                    | Securities Issued in TreasuryDirect: Sales by Term provides the count and dollar value of marketable securities and savings bonds issued in TreasuryDirect by term. Securities are available by security class: bills, notes, bonds, and Treasury Inflation-Protected Securities (TIPS) for marketable securities and Series EE and I for savings bonds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Electronic Securities Transactions                                   | Transfers of Marketable Securities                                                                   | `/v1/accounting/od/securities_transfers`                                                     | Securities Issued In TreasuryDirect: Transfers of Marketable Securities provides the count and dollar value for marketable securities transferred to TreasuryDirect from legacy Treasury Direct, legacy holding system, and commercial book entry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Electronic Securities Transactions                                   | Conversions of Paper Savings Bonds                                                                   | `/v1/accounting/od/securities_conversions`                                                   | Securities Issued in TreasuryDirect: Conversions of Paper Savings Bonds provides the count and dollar value of paper savings bonds converted to electronic savings bonds in TreasuryDirect.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Electronic Securities Transactions                                   | Redemptions                                                                                          | `/v1/accounting/od/securities_redemptions`                                                   | Securities Issued in TreasuryDirect: Redemptions provides the count and dollar value for marketable securities and savings bonds redeemed in TreasuryDirect. Securities are available by security class: bills, notes, bonds, and Treasury Inflation-Protected Securities (TIPS) for marketable securities and Series E, EE, and I for savings bonds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Electronic Securities Transactions                                   | Outstanding                                                                                          | `/v1/accounting/od/securities_outstanding`                                                   | Securities Issued in TreasuryDirect: Outstanding provides the dollar value for marketable securities and savings bonds outstanding in TreasuryDirect. Securities are available by security class: bills, notes, bonds, and TIPS for marketable securities and Series E, EE, and I for savings bonds. Does not include outstanding dollar value of certificates of indebtedness. That data can be retrieved from the Securities Issued in TreasuryDirect: Certificates of Indebtedness table.