{"id":38598914,"url":"https://github.com/grahamlea/amberelectic-api-tools","last_synced_at":"2026-01-18T09:30:18.662Z","repository":{"id":41361330,"uuid":"405394616","full_name":"GrahamLea/amberelectic-api-tools","owner":"GrahamLea","description":"A collection of command-line tools (and Python functions) that can be used to work with data from the Amber Electric API.","archived":false,"fork":false,"pushed_at":"2022-11-06T05:02:41.000Z","size":90,"stargazers_count":23,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-01-17T17:59:31.551Z","etag":null,"topics":["amber","api","cli","electric","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GrahamLea.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-09-11T14:03:56.000Z","updated_at":"2025-11-05T23:24:17.000Z","dependencies_parsed_at":"2023-01-21T23:03:27.754Z","dependency_job_id":null,"html_url":"https://github.com/GrahamLea/amberelectic-api-tools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GrahamLea/amberelectic-api-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrahamLea%2Famberelectic-api-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrahamLea%2Famberelectic-api-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrahamLea%2Famberelectic-api-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrahamLea%2Famberelectic-api-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GrahamLea","download_url":"https://codeload.github.com/GrahamLea/amberelectic-api-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrahamLea%2Famberelectic-api-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amber","api","cli","electric","python"],"created_at":"2026-01-17T08:31:44.685Z","updated_at":"2026-01-18T09:30:18.640Z","avatar_url":"https://github.com/GrahamLea.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Amber Electric API Tools\n\nA collection of command-line tools (and Python functions) that can be used to\nwork with data from the Amber Electric API.\n\n\n## About Amber Electric\n\n[Amber Electric](https://amber.com.au/) is an innovative energy retailer in\nAustralia which gives customers access to the wholesale energy price as\ndetermined by the National Energy Market.\nThis gives customers the opportunity to reduce their bills and their reliance\non fossil fuels by shifting their biggest energy usage to times of the day when\nenergy is cheaper and greener.\n\n\n### Amber's API\n\nAmber gives customers access to a LOT of their own data through their public\nApplication Programming Interface or API.\n\nThis tool relies on you having access to Amber's API, which means you need\nto be an Amber customer, and you need to get an API token.\nBut that's pretty easy.\n[Start here](https://help.amber.com.au/hc/en-us/articles/360038985552-Do-you-have-an-API-).\n\n\n## How To Get The Tools\n\nIf you're a programmer comfortable with Git, I'm sure you already know how to\nget this code onto your machine from GitHub.\n\nIf you're not familiar with Git, you can download this code as a Zip file\nby clicking on [this link](https://github.com/GrahamLea/amber-usage-summary/archive/refs/heads/main.zip).\nOnce it's downloaded, unzip the file, which will create a directory containing\nall the files of this project.\n\n\n## Pre-Requisites For These Tools\n\n1. You'll need to know how to use a command-line interface / terminal / PowerShell.\n\n2. You'll need an Amber API token. (See above)\n\n3. You'll need [Python 3.9](https://www.python.org/downloads/) (or higher) installed.\n\nIf you think you already have Python 3.9+ installed, you can check the version \nof Python in your path by running:\n```commandline\npython3 -V\n```\n\nIf that doesn't work, try:\n```commandline\npython -V\n```\n\nIf neither of those works, or neither is Python 3.9 or higher, you'll need to\n[download and install Python](https://www.python.org/downloads/).\n\n\n## Setup\n\nUsing a terminal, in the directory of this project:\n\n1. Create a Python virtual environment with this command. (Note: if 'python3' \ndidn't work above but 'python' did and is v3.9 or higher, just use 'python'):\n```\npython3  -m  venv  venv\n```\n\n2. Install the required dependencies with this command on MacOS or Linux:\n```\nvenv/bin/pip  install  -r  requirements.txt\n```\nor this command on Windows:\n```\nvenv\\Scripts\\pip  install  -r  requirements.txt\n```\n\n\n## Common Options\n\nThe following options are common among all the tools.\n\n\n### Help\n\nRun the script with the `-h` option to see its help page.\n\nOn MacOS / Linux:\n```\nvenv/bin/python  SCRIPT_NAME  -h\n```\nOn Windows:\n```\nvenv\\Scripts\\python  SCRIPT_NAME  -h\n```\n\n\n### API Tokens\n\nAll scripts require an Amber API token to be provided.\nThere is an `--apitoken`/`-t` option available in each script. \n\nIf you'd prefer _not_ to paste your API token into a terminal command, you can\nsave it in a file called `apitoken` (with no extension) in the project's \ndirectory.\nAll scripts will look for this file and read the API token from it if it exists,\nremoving the need for the `--apitoken` option.\n\n\n### Site Selection\n\nIf you have multiple sites in your Amber Electric account, you'll need to select\none using the `--site-id` option:\n```\nvenv/bin/python  SCRIPT_NAME  --site-id  SITE_ID_YOU_WANT_DATA_FOR\n```\n\n\n## Amber Electric Usage Summary\n\nThis is a command line tool that produces a summary CSV report of an Amber \nElectric customer's energy consumption and cost data.\n\nYou simply need to provide your Amber API token, and the tool will output a CSV\nlike this for the last 12 months:\n\n```\nCHANNEL                         , 2020-09-01, 2020-09-02, 2020-09-03, ...\nB4 (FEED_IN) Usage (kWh)        ,      1.351,      0.463,      0.447, ...\nE3 (CONTROLLED_LOAD) Usage (kWh),      2.009,      2.669,      2.757, ...\nE4 (GENERAL) Usage (kWh)        ,     20.400,     20.965,     16.011, ...\n```\n\n\n### How To Use It\n\nUsing a terminal, in the directory of this project:\n\nRun the tool with this command, replacing `YOUR_API_TOKEN` with your own API\ntoken.\n\nMacOS / Linux:\n```\nvenv/bin/python  amber_usage_summary.py  --api-token  YOUR_API_TOKEN  \u003e  my_amber_usage_data.csv\n```\n\nWindows:\n```\nvenv\\Scripts\\python  amber_usage_summary.py  --api-token  YOUR_API_TOKEN  \u003e  my_amber_usage_data.csv\n```\n\nUsing the above, your summary consumption data for the last year will be saved \nto the file called `my_amber_usage_data.csv` in the same directory.\n\n\n#### Options\n\n\n##### Costs Summary\n\nBy default, the tool just outputs energy consumption data.\nIf you also want a summary of your cost data, add the `--include-cost` option:\n```\nvenv/bin/python  amber_usage_summary.py  --include-cost\n```\n\n\n##### Date Range\n\nBy default, the report includes the last 12 full calendar months of data, plus\nall of the current month's data up until yesterday.\nYou can select what date range to include in the output by adding and start date\nand, optionally, an end date to the command.\n```\nvenv/bin/python  amber_usage_summary.py  2020-07-01  2021-06-30\n```\n\n\n## Amber Electric Spot Price History\n\nThis is a command line tool that produces a detailed CSV report of an Amber \nElectric customer's historical spot prices.\n\nYou simply need to provide your Amber API token, and the tool will output a CSV\nlike this for the last month:\n\n```\nDATE +10:00, CHANNEL                , 00:00:00, 00:30:00, 01:00:00, ...\n2022-01-21 , GENERAL (c/kWh)        ,   17.456,   17.743,   17.736, ...\n2022-01-21 , CONTROLLED_LOAD (c/kWh),   14.366,   14.653,   14.646, ...\n2022-01-21 , FEED_IN (c/kWh)        ,   -5.913,   -6.174,   -6.168, ...\n2022-01-22 , GENERAL (c/kWh)        ,  118.627,   17.623,   18.280, ...\n...\n```\n\n\n### How To Use It\n\nUsing a terminal, in the directory of this project:\n\nRun the tool with this command, replacing `YOUR_API_TOKEN` with your own API\ntoken.\n\nOn MacOS / Linux:\n```\nvenv/bin/python  amber_spot_price_export.py  --api-token  YOUR_API_TOKEN  \u003e  my_amber_spot_price_data.csv\n```\nOn Windows:\n```\nvenv\\Scripts\\python  amber_spot_price_export.py  --api-token  YOUR_API_TOKEN  \u003e  my_amber_spot_price_data.csv\n```\n\nUsing the above, your spot price data for the last month will be saved \nto the file called `my_amber_spot_price_data.csv` in the same directory.\n\n\n#### Options\n\n\n##### Date Range\n\nBy default, the report includes the last month of data.\nYou can select what date range to include in the output by adding a start date\nand, optionally, an end date to the command.\n```\nvenv/bin/python  amber_spot_price_export.py  2020-07-01  2021-06-30\n```\n\n\n## Amber Electric Solar Export Summary\n\nThis is a command line tool that produces a CSV summary of an Amber Electric \ncustomer's historical solar exports, including total exports, earnings, and\naverage and peak outputs by month.\n\nYou simply need to provide your Amber API token, and the tool will output a CSV\nlike this for the last year:\n\n```\n                 , 2022-05, 2022-06, 2022-07, ...\nTotal kWh        ,   0.137,   6.171,  16.988, ...\nTotal Income $   ,   0.000,   0.230,   0.840, ...\nAverage Daily kWh,   0.034,   0.213,   0.566, ...\nPeak Daily kWh   ,   0.074,   0.738,   2.161, ...\nPeak Period kW   ,   0.116,   0.438,   0.656, ...\n```\n\n\n### How To Use It\n\nUsing a terminal, in the directory of this project:\n\nRun the tool with this command, replacing `YOUR_API_TOKEN` with your own API\ntoken.\n\nOn MacOS / Linux:\n```\nvenv/bin/python  amber_solar_export_summary.py  --api-token  YOUR_API_TOKEN  \u003e  my_amber_solar_export_data.csv\n```\nOn Windows:\n```\nvenv\\Scripts\\python  amber_solar_export_summary.py  --api-token  YOUR_API_TOKEN  \u003e  my_amber_solar_export_data.csv\n```\n\nUsing the above, your solar export summary data for the last year will be saved \nto the file called `my_amber_solar_export_data.csv` in the same directory.\n\n\n#### Options\n\n\n##### Date Range\n\nBy default, the report includes the last 12 full months of data.\nYou can select what date range to include in the output by adding a start month\nand, optionally, an end month to the command.\n```\nvenv/bin/python  amber_solar_export_summary.py  2020-07  2021-06\n```\n\n\n## Amber Electric Invoice Estimate / Tariff Comparison\n\nThis is a command line tool that produces a text-based estimate of an Amber \nElectric customer's invoice for a particular month or months in the past, using\nusage and pricing data from Amber's API.\n\n*Once configured*, the tool can output an invoice breakdown like this one for \nany past whole month during which you were an Amber customer:\n\n```\nMonth: 2022-01\n\n   Usage Fees:\n      General Usage Wholesale                319.9     8.10   $  25.91\n      Controlled Load Wholesale               39.9     8.07   $   3.22\n      Network - Peak Energy                   35.2    25.37   $   8.93\n...\n```\n\nThe output has been designed to closely match the format of Amber's most recent \ninvoice format.\n\nBy running the tool multiple times for the same time period but using different\ntariffs, it's possible to compare the *estimates* for what you would have paid \nunder different tariffs for previous months.\n\n\n### ⚠️ Important Note: This Ain't Official\n\nI'm in no way attached to Amber Electric (except for being a customer).\nThis tool has been developed as an amateur, non-vocational exercise effort.\nAmber doesn't endorse this tool, nor support it. \n\n\n### ⚠️ Important Note About Accuracy\n\nThe tool deliberately has \"Estimate\" in the name because it is NOT, and cannot\nbe, a 100% accurate re-creation of Amber's billing engine that creates your\nactual invoices.\n\nThe purpose for creating this tool was to enable a rough comparison of \ndifferent DNSP tariffs against historical usage data, and in my own use it \nappears to be accurate *enough* to serve this purpose.\n\nWhile no warranty is given about any aspect of the tools in this repository, \nI want to specifically call out that I'm offering ZERO guarantees that the \noutput of this tool is accurate.\nAmber themselves have \n[published information about some of the reasons that make reproducing bills from API data problematic](https://github.com/amberelectric/public-api/discussions/50). \nAnd in relation to this tool they've told me:\n\n\u003e Billing is complicated, and there are a bunch of business rules that you \n\u003e probably haven’t modelled, so the output may not match a bill exactly.\n\nIf you find inaccuracies in the output, and know why they are happening, I'd be\nhappy to hear from you in order to improve the tool (and even happier to have \nyou develop and submit a patch (after chatting with me about it)).\nSee 'Contributions' below.\n\n\n### ⚠️ Important Note About Limitations\n\nThe following limitations are _known_ to exist with the tool:\n* There is no handling for block tariffs.\n* There is no handling for capacity pricing.\n* The outputs of demand pricing have not been tested against real bills.\n* There is no provision for mid-month changes, e.g. if a tariff changes or\n  GreenPower is switched on or off in the middle of a month.\n* There is no special handling for doing part of the current month (per-day \n  charges will be calculated for the full month).\n* Only Ausgrid residential tariffs have been encoded (and only non-closed ones).\n* Only NSW charges have been encoded.\n* Only public holidays in NSW from 2021-2023 have been comprehensively encoded.\n\nThere are likely _other_ limitations that are unknown.\n\nRe-producing a bill requires a lot more data than what is available from the API.\nAt a high level, the tariffs you want to use for each channel, the prices that\nmake up those tariffs, and other charges specific to your state, your network,\nand even your site's location, all need to be available and relatively accurate \nto make a good estimate.\n\nSo far, I've only entered this data for scenarios that I've wanted to test.\nThis means if you are in NSW, on the Ausgrid network, have an IntelliHub smart\nmeter, and are connected to the Sydney South TNI, the tool *might* produce good\nestimates for you!\nIf you're not part of that small niche, you will probably need to do some data\nacquisition and entry in order to get the tool estimating your own bills.\n\nIf you add new data for your own purposes, and you'd like to contribute it\nfor others to use, I'd be happy to hear from you.\nSee 'Contributions' below.\n\n\n### How To Use It\n\n\n### Configuration\n\nBefore using this tool, you'll need to configure it to have the correct tariffs \nand other data for the location and scenario you want to test.\n\nAt the very least, you'll need to either edit or create your own copy\n(recommended) of ``data/accountConfigs/my_account_config_example.json5``, and \nreview/update all the values in the file to ensure they're accurate for your \nsite.\n\nIf you're using tariffs that aren't already encoded in a tariff file, you'll\nneed to create a new tariff file.\nThe document `data/tariffs/TariffsReadme.md` explains the format for creating\na tariff file.\nIt will probably be easiest to copy an existing one for a similar type of \ntariff (e.g. time of use, demand, controlled load) and modify it rather than \nstart from scratch. But it shouldn't be too hard.\nSee below for how to find the data to go in these files.\n\nLastly, if there isn't an \"Other Charges\" file for your location under \n`data/otherCharges`, or it's out of date, you'll need to create one of those.\nThis file has a similar format to tariff files with a few small differences as\nexplained at the top of the NSW file.\nThere are links in the NSW file that should help in finding the right values.\n\nNote that, except for the Amber monthly fee, all other tariffs and charges \nshould be entered as *exclusive* of GST.\n\n\n#### Finding Out Your DNSP\n\nThe first thing you'll need to do is figure out who your Distributed Network\nService Provider (DNSP) is.\nThis is sometimes just called your \"network\" as is the company  who controls\nthe poles and wires in your ares.\nIt is not the same as your retailer (that would be Amber!).\n\nIf you're planning to use these tools, then the easiest way to find out who \nruns your network will be to \n[perform a `/sites` query using the Amber API docs](https://app.amber.com.au/developers/#operations-default-get_sites).\nThe name of your DNSP appears in the response as the property `network`.\n\n\n#### Finding Out Your Tariffs and Rates\n\nGood news: The `/sites` query response (see above) also contains the codes of \nyour current tariffs!\n\nBad news: Tariffs are usually made up of a number of different rates/prices that\napply to different metrics (e.g. energy used, or days in a month) and at \ndifferent times (e.g. peak vs shoulder vs off-peak, or different months of the \nyear).\n\nGood news: Tariffs are often available online.\nIf you google for your DNSP's name, \"tariffs\", and the current year, you should \nusually come up with a document that describes your tariffs.\n\nHere's an incomplete list of known tariff documents.\nIf you find another one, or one that points to an old link, it'd be great if you \ncould add it and submit a pull request to this README!\n* [Ausgrid: 'Network Price List 2021-2022'](https://www.ausgrid.com.au/-/media/Documents/Regulation/Pricing/PList/AUSGRID-NETWORK-PRICE-LIST-FY2021-22.pdf)\n\n\n#### Finding Out Other Data\n\nAmber have kindly said they'll probably be happy to supply people with extra \ndata they may need to run this tool if they contact their support team at \n[info@amber.com.au](mailto:info@amber.com.au).\n\nThey've also said that they often have busy periods and that in those times \nrequests like this might take a long time for a response, or could even be \nrefused.\n\nI would expect the only data your might need to get from Amber would be:\n* `marginalLossFactor` and `smartMeterAccessChargeCentsPerDay` for your Account \n  Config file\n* the six `centsPerKwh` items for your state's Other Charges file\n\nI believe most other rates should be able to be easily found on the internet.\nLet's try not to bother Amber with requests for data that we can easily google.\nTaking the time to submit a pull request to this project with any data you get \nfrom Amber or from tariff documents that could be useful to other people should \nhelp greatly in reducing that load.\n\n\n### Running the Tool\n\n⚠️ IMPORTANT: If you skipped \"Configuration\" above, go back and read it, and\ndo it!\nIf you don't, your results will be meaningless unless you just happen to live \nin the same part of Sydney as me and are on the same tariff.\n\nUsing a terminal, in the directory of this project:\n\nRun the tool with this command, replacing `YOUR_API_TOKEN` with your own API\ntoken, and the account config filename with the path of your own account config.\n\nOn MacOS / Linux:\n```\nvenv/bin/python  amber_invoice_estimate.py  --api-token  YOUR_API_TOKEN  data/accountConfigs/my_account_config_example.json5\n```\nOn Windows:\n```\nvenv\\Scripts\\python  amber_invoice_estimate.py  --api-token  YOUR_API_TOKEN  data\\accountConfigs\\my_account_config_example.json5\n```\n\n\n#### Options\n\n\n##### Months\n\nBy default, the report generates an estimate of your bill for the last complete\nmonth.\nYou can select what months to include in the output by listing one or more \nmonths as arguments to the script in `yyyy-MM` format: \n```\nvenv/bin/python  amber_invoice_estimate.py  ACCOUNT_CONFIG_FILE  2021-10  2021-11  2021-12\n```\n\n\n## Contributions\n\nI'm open to accepting contributions that improve the tool.\n\nIf you're planning on altering the code with the intention of contributing the\nchanges back, it'd be great to have a chat about it first to check we're on\nthe same page about how the improvement might be added.\nIt's probably easiest to create an issue describing your planned improvement (and\nbeing clear that you plan to implement it yourself).\n\n\n## License\n\nAll files in this project are licensed under the \n[3-clause BSD License](https://opensource.org/licenses/BSD-3-Clause).\nSee [LICENSE.md](LICENSE.md) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrahamlea%2Famberelectic-api-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrahamlea%2Famberelectic-api-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrahamlea%2Famberelectic-api-tools/lists"}