Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dogmatic69/nordigen-homeassistant
Home assistant integration for the Nordigen open banking API
https://github.com/dogmatic69/nordigen-homeassistant
banking hacs hacs-integration home-assistant homeassistant integration nordigen open-banking openbanking python
Last synced: 2 months ago
JSON representation
Home assistant integration for the Nordigen open banking API
- Host: GitHub
- URL: https://github.com/dogmatic69/nordigen-homeassistant
- Owner: dogmatic69
- Created: 2021-07-02T14:33:27.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2023-09-04T17:41:32.000Z (over 1 year ago)
- Last Synced: 2024-10-11T07:45:51.665Z (3 months ago)
- Topics: banking, hacs, hacs-integration, home-assistant, homeassistant, integration, nordigen, open-banking, openbanking, python
- Language: Python
- Homepage:
- Size: 192 KB
- Stars: 22
- Watchers: 7
- Forks: 0
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Nordigen Home Assistant integration
[](LICENSE)
[](https://www.codefactor.io/repository/github/dogmatic69/nordigen-homeassistant)
[](https://sonarcloud.io/dashboard?id=dogmatic69_nordigen-homeassistant)
[](https://github.com/dogmatic69/nordigen-homeassistant/actions/workflows/pr.yaml)
This integration will allow you to have access to banking data for most banks
in the EU.
## Installation
HACS coming soon!
You will need to register on Nordigen and get an API key before you can run this
integration. At this time there is only support for one API key per HA instance.
### Installation
1. Copy / clone this integration into `./config/custom_components/nordigen`
1. Restart Home Assistant to get the integration loaded
### Configuraiton
1. Add your config to `./config/configuration.yaml` or similar
1. Validate the config using UI or CLI.
1. Restart Home Assistant
### Authentication
1. Check the developer section for sensors, there should be a sensor with the account number / reference containing a link to authenticate your account.
1. Click the link and follow the instructions
1. Restart Home Assistant one last time
In the future I hope to be able to make the system a bit more dynamic and user
friendly for account onboarding :)
## Configuration
| Name | Type | Requirement | Description |
| ----------------- | ------- | ------------ | ------------------------------------------- |
| token | string | **Required** | Your secret API token from Nordigen (use `!secret`!) |
| requisitions | array | **Required** | List of banking institutions that will be connected |
| debug | boolean | **Optional** | Still connects to the bank for account name, but balance is randomly generated witout connecting to the bank. (default `False`) |
This integration pairs a "user id" with a banking institution. Each banking
institution will return one or more accounts, each of which can have multiple
types of balances.
Each requisition can contain the following options:
| Name | Type | Requirement | Description |
| ------------------- | ------- | ------------ | ------------------------------------------- |
| enduser_id | string | **Required** | A unique (to your HA install) identifier for the user these accounts will belong to. Generally a UUID |
| aspsp_id | string | **Required** | The bank code for the institution being connected. This can be found either in the API examples on Nordigen or using the Client Libs (there are hundreds) |
| refresh_rate | integer | **Optional** | Time in minutes between refresh (default is `240` min / 4 hours). Some banks are limited to 4 requests / day |
| ignore_accounts | array | **Optional** | List of account numbers to ignore. For example might add accounts for 2 partners including a joint account (which would show up twice, once for each user). |
| available_balance | boolean | **Optional** | Create a sensor based on the available balance (default `True`) |
| booked_balance | boolean | **Optional** | Create a sensor based on the booked balance (pending transactions) (default `True`) |
| max_historical_days | integer | **Optional** | Maximum days of history to collect (default `30`) |
| icon | string | **Optional** | Icon to use for the sensor, defaults to the currency symbol or USD when not available as an icon (default `mdi:currency-usd-circle`) |
### Example Config
Assuming you bank with a single institution, your config may look like this.
```yaml
nordigen:
token: !secret nordigen
requisitions:
- enduser_id: user-id-1
aspsp_id: BANK_A
```
Should you have more than one institution you use (credit cards are often apart from current acounts)
```yaml
nordigen:
token: !secret nordigen
requisitions:
- enduser_id: user-id-1
aspsp_id: BANK_A
- enduser_id: user-id-1
aspsp_id: BANK_B
```
Multiple users with the same institution, but ignoring an account
```yaml
nordigen:
token: !secret nordigen
requisitions:
- enduser_id: user-id-1
aspsp_id: BANK_A
- enduser_id: user-id-2
aspsp_id: BANK_A
ignore_accounts:
- ACCOUNT_ID_1234
```
### Derivative Sensors
You can build derivative sensors to view your total wealth for example
```yaml
sensor:
- platform: template
sensors:
my_wealth:
unit_of_measurement: SEK
value_template: |
{{
(
(states('sensor.account_123_available') | float) +
(states('sensor.account_456_available') | float) +
(states('sensor.account_789_available') | float) +
) | round(2)
}}
```
### Automations
Turn off your outside lights when your account balance is getting low.
```yaml
automation:
- alias: "broke"
trigger:
- platform: numeric_state
entity_id: sensor.account_123_available
below: 2500
action:
- service: light.turn_off
target:
entity_id: light.exterior_lighting
```
## Technical details
I wanted to have good test coverage and could not find a good way to do it within
this integration so I've abstracted out all the code into a [standalone python lib].
That in turn uses a generic API [clinet lib] for Nordigen
## About Nordigen
[Nordigen] is an all-in-one banking data API for building powerful banking, lending
and finance apps. They offer a free API for fetching account info, balances and
transactions. They also handle all the authentication between the banks and do
a little bit of data nomilisation.
Check out the [Nordigen API] for full details.
[standalone python lib]: https://pypi.org/project/nordigen-ha-lib/
[client lib]: https://pypi.org/project/nordigen-python/
[Nordigen]: https://nordigen.com/
[Nordigen API]: https://nordigen.com/en/account_information_documenation/api-documention/overview/