Struct Amber

Source

pub struct Amber { /* private fields */ }

Expand description

Main client for the Amber Electric API

This client provides a high-level interface to all Amber Electric API endpoints.

Implementations§

Source §

impl Amber

Source

pub fn builder() -> AmberBuilder

Create an instance of Amber using the builder syntax

Source §

impl Amber

Source

pub fn sites(&self) -> Result<Vec<Site>>

Return all sites linked to your account.

This method returns information about all electricity sites associated with your Amber account. Each site represents a location where you have electricity service.

§Authentication

This method requires authentication via API key. The API key can be provided either through the AMBER_API_KEY environment variable (when using Amber::default()) or by explicitly setting it when building the client.

§Returns

Returns a Result containing a Vec of Site objects on success.

§Errors

This method will return an error if:

The API key is missing or invalid (HTTP 401)
There’s a network error communicating with the API
The API returns an internal server error (HTTP 500)

§Example

use amber_api::Amber;

let client = Amber::default();
let sites = client.sites()?;

for site in sites {
    println!("Site {}: {} ({})", site.id, site.network, site.status);
}

Source

pub fn current_renewables<'f1>(&'f1 self) -> AmberCurrentRenewablesBuilder<'f1>

Returns the current percentage of renewables in the grid for a specific state.

This method retrieves renewable energy data for the specified Australian state. The data shows the current percentage of renewable energy in the grid and can optionally include historical and forecast data.

§Parameters

state: The Australian state (NSW, VIC, QLD, SA)
next: Optional number of forecast intervals to return
previous: Optional number of historical intervals to return
resolution: Optional interval duration (5 or 30 minutes, default 30)

§Authentication

This endpoint does not require authentication and can be called without an API key.

§Returns

Returns a Result containing a Vec of Renewable objects on success.

§Errors

This method will return an error if:

There’s a network error communicating with the API
The API returns an internal server error (HTTP 500)

§Example

use amber_api::Amber;
use amber_api::models::{State, Resolution};

let client = Amber::default();

// Get current renewables data for Victoria
let renewables = client.current_renewables()
    .state(State::Vic)
    .call()?;

for renewable in renewables {
    println!("{}", renewable);
}

// Get current data with 8 forecast intervals
let renewables_with_forecast = client.current_renewables()
    .state(State::Nsw)
    .next(8)
    .resolution(Resolution::FiveMinute)
    .call()?;

Source

pub fn prices<'f1, 'f2>(&'f1 self) -> AmberPricesBuilder<'f1, 'f2>

Returns all the prices between the start and end dates for a specific site.

This method retrieves historical pricing data for the specified site between the given date range. The date range cannot exceed 7 days.

§Parameters

site_id: ID of the site you are fetching prices for (obtained from sites())
start_date: Optional start date for the price range (defaults to today)
end_date: Optional end date for the price range (defaults to today)
resolution: Optional interval duration (5 or 30 minutes, defaults to your billing interval)

§Authentication

This method requires authentication via API key. The API key can be provided either through the AMBER_API_KEY environment variable (when using Amber::default()) or by explicitly setting it when building the client.

§Returns

Returns a Result containing a Vec of Interval objects on success. Intervals are returned in order: General > Controlled Load > Feed In.

§Errors

This method will return an error if:

The API key is missing or invalid (HTTP 401)
The site ID is invalid (HTTP 400)
The site is not found (HTTP 404)
The date range exceeds 7 days (HTTP 422)
There’s a network error communicating with the API
The API returns an internal server error (HTTP 500)

§Example

use std::str::FromStr;

use amber_api::Amber;
use amber_api::models::Resolution;
use jiff::civil::Date;

let client = Amber::default();
let sites = client.sites()?;
let site_id = &sites[0].id;

// Get prices for today
let prices = client.prices()
    .site_id(site_id)
    .call()?;

// Get prices for a specific date range
let start_date = Date::from_str("2021-05-01").expect("Invalid start date");
let end_date = Date::from_str("2021-05-03").expect("Invalid end date");
let prices = client.prices()
    .site_id(site_id)
    .start_date(start_date)
    .end_date(end_date)
    .resolution(Resolution::FiveMinute)
    .call()?;

for interval in prices {
    match interval {
        amber_api::models::Interval::ActualInterval(actual) => {
            println!("Actual price: {:.2}c/kWh", actual.base.per_kwh);
        }
        _ => {} // Handle other interval types as needed
    }
}

Source

pub fn current_prices<'f1, 'f2>( &'f1 self, ) -> AmberCurrentPricesBuilder<'f1, 'f2>

Returns the current price for a specific site.

This method retrieves the current pricing data for the specified site, optionally including historical and forecast data.

§Parameters

site_id: ID of the site you are fetching prices for (obtained from sites())
next: Optional number of forecast intervals to return (max 2048 total)
previous: Optional number of historical intervals to return (max 2048 total)
resolution: Optional interval duration (5 or 30 minutes, defaults to your billing interval)

§Authentication

This method requires authentication via API key. The API key can be provided either through the AMBER_API_KEY environment variable (when using Amber::default()) or by explicitly setting it when building the client.

§Returns

Returns a Result containing a Vec of Interval objects on success. Intervals are returned in order: General > Controlled Load > Feed In.

§Errors

This method will return an error if:

The API key is missing or invalid (HTTP 401)
The site ID is invalid (HTTP 400)
The site is not found (HTTP 404)
The total number of intervals exceeds 2048 (HTTP 422)
There’s a network error communicating with the API
The API returns an internal server error (HTTP 500)

§Example

use amber_api::Amber;
use amber_api::models::Resolution;

let client = Amber::default();
let sites = client.sites()?;
let site_id = &sites[0].id;

// Get current prices only
let current_prices = client.current_prices()
    .site_id(site_id)
    .call()?;

// Get current prices with forecast
let prices_with_forecast = client.current_prices()
    .site_id(site_id)
    .next(8)
    .resolution(Resolution::ThirtyMinute)
    .call()?;

// Get current prices with history and forecast
let full_prices = client.current_prices()
    .site_id(site_id)
    .previous(8)
    .next(8)
    .call()?;

for interval in current_prices {
    match interval {
        amber_api::models::Interval::CurrentInterval(current) => {
            println!("Current price: {:.2}c/kWh (estimate: {})",
                     current.base.per_kwh, current.estimate);
        }
        _ => {} // Handle other interval types as needed
    }
}

Source

pub fn usage<'f1, 'f2>(&'f1 self) -> AmberUsageBuilder<'f1, 'f2>

Returns all usage data between the start and end dates for a specific site.

This method retrieves historical usage data for the specified site between the given date range. The date range cannot exceed 7 days, and the API can only return 90 days worth of data.

§Parameters

site_id: ID of the site you are fetching usage for (obtained from sites())
start_date: Start date for the usage data (required)
end_date: End date for the usage data (required)
resolution: Optional interval duration (deprecated, will be ignored)

§Authentication

This method requires authentication via API key. The API key can be provided either through the AMBER_API_KEY environment variable (when using Amber::default()) or by explicitly setting it when building the client.

§Returns

Returns a Result containing a Vec of Usage objects on success. Usage data is returned in order: General > Controlled Load > Feed In.

§Errors

This method will return an error if:

The API key is missing or invalid (HTTP 401)
The site ID is invalid (HTTP 400)
The site is not found (HTTP 404)
The date range exceeds 7 days (HTTP 422)
There’s a network error communicating with the API
The API returns an internal server error (HTTP 500)

§Example

use std::str::FromStr;

use amber_api::Amber;
use jiff::civil::Date;

let client = Amber::default();
let sites = client.sites()?;
let site_id = &sites[0].id;

// Get usage data for a specific date range
let start_date = Date::from_str("2021-05-01").expect("Invalid start date");
let end_date = Date::from_str("2021-05-03").expect("Invalid end date");
let usage_data = client.usage()
    .site_id(site_id)
    .start_date(start_date)
    .end_date(end_date)
    .call()?;

for usage in usage_data {
    println!("Channel {}: {:.2} kWh, Cost: ${:.2}",
             usage.channel_identifier, usage.kwh, usage.cost);
}