aioynab¶
YNAB API client implemented using python 3 asyncio.
Quick Start¶
First create a personal access token in your YNAB account. Create a client with that value like the example below.
import asyncio
from aioynab.client import Client
loop = asyncio.get_event_loop()
client = Client('ynab-personal-access-token')
budgets = loop.run_until_complete(client.budgets()))
budget_id = budgets['budgets'][0]['budget_id']
accounts = loop.run_until_complete(client.accounts(budget_id))
account_id = accounts['accounts'][0]['account_id']
transactions = loop.run_until_complete(client.account_transactions(budget_id, account_id))
Return Values¶
The return values from all client functions return the value of the data key of the YNAB response. For example, the following YNAB response from the /user endpoint:
{
"data": {
"user": {
"id": "1a2f3f4e-5c01-4678-8134-c11e278fa111"
}
}
}
Would result in the following return value when calling the user method:
>>> client = Client('access-token')
>>> client.user()
{'user': {'id': '1a2f3f4e-5c01-4678-8134-c11e278fa111'}}
Consult the YNAB API endpoint documentation for the schema of the response for each endpoint that the client interacts with.
Module Documentation¶
-
aioynab.client.
BASE_URL
= 'https://api.youneedabudget.com/v1'¶ The base API URL for YNAB.
-
class
aioynab.client.
Client
(personal_access_token, loop=None, session=None)[source]¶ Bases:
object
A client for the YNAB API.
Parameters: - personal_access_token (
str
) – The YNAB personal access token. Create one at https://app.youneedabudget.com/settings/developer. - loop (
Optional
[AbstractEventLoop
]) – Optional event loop, one will be created if not passed. - session (
Optional
[ClientSession
]) – Optional aiohttp client session, one will be created if not passed.
-
_request
(endpoint, method='GET', params=None, body=None)[source]¶ Performs a http request and returns the json response.
Parameters: - endpoint (
str
) – The API endpoint. - method (
str
) – The HTTP method to use (GET, POST, PUT). - params (
Optional
[dict
]) – Any parameters to send with the request. - body (
Optional
[dict
]) – A json body to send with the request.
Return type: dict
Returns: The json data as a dict.
Raises: YNABAPIError – If there is an api error.
- endpoint (
-
account
(budget_id, account_id)[source]¶ Returns a single account associated with a budget.
Corresponds to the /budget/{budget_id}/accounts/{account_id} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget to look up. - account_id (
str
) – The ID of the account.
Return type: dict
Returns: A dict of the account.
- budget_id (
-
account_transactions
(budget_id, account_id, since_date=None, type=None, last_knowledge_of_server=None)[source]¶ Returns all transactions for a specified account.
Corresponds to the /budgets/{budget_id}/accounts/{account_id}/transactions endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - account_id (
str
) – The ID of the account. - since_date (
Optional
[str
]) – If specified, only transactions on or after this date will be included. The date should be ISO formatted (e.g. 2016-12-30). - type (
Optional
[str
]) – If specified, only transactions of the specified type will be included. ‘uncategorized’and ‘unapproved’ are currently supported. - last_knowledge_of_server (
Optional
[int
]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type: dict
Returns: A dict of all transactions for the requested account.
- budget_id (
-
accounts
(budget_id, last_knowledge_of_server=None)[source]¶ Returns all accounts associated with the budget.
Corresponds to the /budget/{budget_id}/accounts endpoint.
Parameters: - budget_id (
str
) – The ID of the budget to look up. - last_knowledge_of_server (
Optional
[int
]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type: dict
Returns: A dict containing all accounts.
- budget_id (
-
budget
(budget_id, last_knowledge_of_server=None)[source]¶ Returns a single budget with all related entities.
This resource is effectively a full budget export. Corresponds to the /budget/{budget_id} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget to look up. - last_knowledge_of_server (
Optional
[int
]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type: dict
Returns: A dict containing the requested budget.
- budget_id (
-
budget_month
(budget_id, month)[source]¶ Returns a single budget month.
Corresponds to the /budgets/{budget_id}/months/{month} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - month (
str
) – The budget month in ISO format (e.g. 2016-12-01) (‘current’ can also be used to specify the current calendar month (UTC)).
Return type: dict
Returns: A dict for the requested budget month.
- budget_id (
-
budget_months
(budget_id, last_knowledge_of_server=None)[source]¶ Returns all budget months.
Corresponds to the /budgets/{budget_id}/months endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - last_knowledge_of_server (
Optional
[int
]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type: dict
Returns: A dict of all budget months.
- budget_id (
-
budget_settings
(budget_id)[source]¶ Returns settings for a budget.
Corresponds to the /budget/{budget_id/settings endpont.
Parameters: budget_id ( str
) – The ID of the budget.Return type: dict
Returns: The budget settings data as a dict.
-
budgets
()[source]¶ Returns budgets list with summary information.
Corresponds to the /budgets endpoint.
Reutrns: A dict containing all budgets. Return type: dict
-
categories
(budget_id, last_knowledge_of_server=None)[source]¶ Returns all categories grouped by category group.
Corresponds to the /budgets/{budget_id}/categories endpoint.
Parameters: - budget_id (
str
) – The ID of the budget to look up. - last_knowledge_of_server (
Optional
[int
]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type: dict
Returns: A dict of all categories.
- budget_id (
-
category
(budget_id, category_id)[source]¶ Returns a single category.
Amounts (budgeted, activity, balance, etc.) are specific to the current budget month (UTC). Corresponds to the /budgets/{budget_id}/categories/{category_id} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - category_id (
str
) – The ID of the category.
Return type: dict
Returns: A dict of the requested category.
- budget_id (
-
category_month
(budget_id, category_id, month)[source]¶ Returns a single category for a specific budget month.
Amounts (budgeted, activity, balance, etc.) are specific to the current budget month (UTC). Corresponds to the /budgets/{budget_id}/months/{month}/categories/{category_id} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - category_id (
str
) – The ID of the category. - month (
str
) – The budget month in ISO format (e.g. 2016-12-01) (‘current’ can also be used to specify the current calendar month (UTC)).
Return type: dict
Returns: A dict for the specified category and month.
- budget_id (
-
category_transactions
(budget_id, category_id, since_date=None, type=None, last_knowledge_of_server=None)[source]¶ Returns all transactions for a specified category.
Corresponds to the /budgets/{budget_id}/categories/{category_id}/transactions endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - category_id (
str
) – The ID of the category. - since_date (
Optional
[str
]) – If specified, only transactions on or after this date will be included. The date should be ISO formatted (e.g. 2016-12-30). - type (
Optional
[str
]) – If specified, only transactions of the specified type will be included. ‘uncategorized’and ‘unapproved’ are currently supported. - last_knowledge_of_server (
Optional
[int
]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type: dict
Returns: A dict of all transactions for the requested category.
- budget_id (
-
create_transactions
(budget_id, transaction=None, transactions=None)[source]¶ Creates a single transaction or multiple transactions.
One of transaction or transactions must be specified, but not both. Corresponds to the /budgets/{budget_id}/transactions endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - transaction (
Optional
[dict
]) – The transaction to create. - transactions (
Optional
[List
[dict
]]) – The list of transactions to create.
Return type: dict
Returns: A dict of the created transaction(s).
Raises: ValueError – If both transaction and transactions are provided or neither are provided.
- budget_id (
-
locations_payee
(budget_id, payee_id)[source]¶ Returns all payee locations for the specified payee.
Corresponds to the /budgets/{budget_id}/payees/{payee_id}/payee_locations endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - payee_id (
str
) – The ID of the payee.
Return type: dict
Returns: A dict of locations for the requested payee.
- budget_id (
-
payee
(budget_id, payee_id)[source]¶ Returns single payee.
Corresponds to the /budgets/{budget_id}/payees/{payee_id} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - payee_id (
str
) – The ID of the payee.
Return type: dict
Returns: A dict of the requested payee.
- budget_id (
-
payee_location
(budget_id, payee_location_id)[source]¶ Returns all payee locations.
Corresponds to the /budgets/{budget_id}/payee_locations/{payee_location_id} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - payee_location_id (
str
) – The ID of the payee location.
Return type: dict
Returns: A dict of the requested payee location.
- budget_id (
-
payee_locations
(budget_id)[source]¶ Returns all payee locations.
Corresponds to the /budgets/{budget_id}/payee_locations endpoint.
Parameters: budget_id ( str
) – The ID of the budget.Return type: dict
Returns: A dict of all payee locations.
-
payee_transactions
(budget_id, payee_id, since_date=None, type=None, last_knowledge_of_server=None)[source]¶ Returns all transactions for a specified payee.
Corresponds to the /budgets/{budget_id}/payees/{payee_id}/transactions endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - payee_id (
str
) – The ID of the payee. - since_date (
Optional
[str
]) – If specified, only transactions on or after this date will be included. The date should be ISO formatted (e.g. 2016-12-30). - type (
Optional
[str
]) – If specified, only transactions of the specified type will be included. ‘uncategorized’and ‘unapproved’ are currently supported. - last_knowledge_of_server (
Optional
[int
]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type: dict
Returns: A dict of all transactions for the requested payee.
- budget_id (
-
payees
(budget_id, last_knowledge_of_server=None)[source]¶ Returns all payees.
Corresponds to the /budgets/{budget_id}/payees endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - last_knowledge_of_server (
Optional
[int
]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type: dict
Returns: A dict of all payees.
- budget_id (
-
scheduled_transaction
(budget_id, scheduled_transaction_id)[source]¶ Returns all scheduled transactions.
Corresponds to the /budgets/{budget_id}/scheduled_transactions/{scheduled_transaction_id} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - scheduled_transaction_id (
str
) – The ID of the scheduled transaction.
Return type: dict
Returns: A dict of all scheduled transactions.
- budget_id (
-
scheduled_transactions
(budget_id)[source]¶ Returns all scheduled transactions.
Corresponds to the /budgets/{budget_id}/scheduled_transactions endpoint.
Parameters: budget_id ( str
) – The ID of the budget.Return type: dict
Returns: A dict of all scheduled transactions.
-
transaction
(budget_id, transaction_id)[source]¶ Returns a single transaction.
Corresponds to the /budgets/{budget_id}/transactions/{transaction_id} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - transaction_id (
str
) – The ID of the transaction.
Return type: dict
Returns: A dict of the requested transaction.
- budget_id (
-
transactions
(budget_id, since_date=None, type=None, last_knowledge_of_server=None)[source]¶ Returns budget transactions.
Corresponds to the /budgets/{budget_id}/transactions endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - since_date (
Optional
[str
]) – If specified, only transactions on or after this date will be included. The date should be ISO formatted (e.g. 2016-12-30). - type (
Optional
[str
]) – If specified, only transactions of the specified type will be included. ‘uncategorized’and ‘unapproved’ are currently supported. - last_knowledge_of_server (
Optional
[int
]) – The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
Return type: dict
Returns: A dict of all transactions for the budget.
- budget_id (
-
update_category_month
(budget_id, category_id, month, data)[source]¶ Updates a category for a specific month.
Corresponds to the /budgets/{budget_id}/months/{month}/categories/{category_id} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - category_id (
str
) – The ID of the category. - month (
str
) – The budget month in ISO format (e.g. 2016-12-01) (‘current’ can also be used to specify the current calendar month (UTC)). - data (
dict
) – A dict containing the fields/values to update.
Return type: dict
Returns: A dict of the category for the month.
- budget_id (
-
update_transaction
(budget_id, transaction_id, data)[source]¶ Updates a single transaction.
Corresponds to the /budgets/{budget_id}/transactions/{transaction_id} endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - transaction_id (
str
) – The ID of the transaction. - data (
dict
) – A dict containing the fields/values to update.
Return type: dict
Returns: A dict of the updated transaction.
- budget_id (
-
update_transactions
(budget_id, transaction=None, transactions=None)[source]¶ Updates multiple transactions, by ‘id’ or ‘import_id’.
One of transaction or transactions must be specified, but not both. Corresponds to the /budgets/{budget_id}/transactions endpoint.
Parameters: - budget_id (
str
) – The ID of the budget. - transaction (
Optional
[dict
]) – The transaction to update. - transactions (
Optional
[List
[dict
]]) – The list of transactions to updates.
Return type: dict
Returns: A dict of the updated transaction(s).
Raises: ValueError – If both transaction and transactions are provided or neither are provided.
- budget_id (
- personal_access_token (