README

This PHP package provides a client for fetching dynamic energy prices from the EnergyZero API. It allows you to retrieve energy prices for a specified date range with customizable intervals and VAT options.

Building your own client? See API.md for detailed API documentation with examples in multiple languages.

Price Availability

Installation

You can install the package via composer:

composer require baspa/energyzero-php-api

Usage

You can fetch the energy prices for a specific date range with a specific interval and VAT option. When the VAT option is not provided, it will default to true. Make sure you provide a date in the format Y-m-d.

use Baspa\EnergyZero\EnergyZero;
use Baspa\EnergyZero\Enums\Interval;

$prices = (new EnergyZero())->energyPrices(
    startDate: '2024-01-01',
    endDate: '2024-01-02',
    interval: Interval::HOUR,
    vat: true
);

The response will be an array of prices for the specified date range and also include the average price for the period.

Interval options

The following interval options are available:

You can also use integer values directly for backward compatibility:

$prices = (new EnergyZero())->energyPrices('2024-01-01', '2024-01-02', 4);

Set default interval

You can set a default interval that will be used for all requests:

use Baspa\EnergyZero\EnergyZero;
use Baspa\EnergyZero\Enums\Interval;

$energyZero = (new EnergyZero())->setDefaultInterval(Interval::QUARTER);

// All subsequent calls will use 15-minute intervals by default
$prices = $energyZero->energyPrices('2024-01-01', '2024-01-02');

Get quarter-hour prices

Fetch prices in 15-minute intervals for more granular data:

use Baspa\EnergyZero\EnergyZero;
use Baspa\EnergyZero\Enums\Interval;

$prices = (new EnergyZero())->energyPrices(
    startDate: '2024-01-01',
    endDate: '2024-01-01',
    interval: Interval::QUARTER
);

Get gas prices

Fetch gas prices instead of electricity prices:

use Baspa\EnergyZero\EnergyZero;

$gasPrices = (new EnergyZero())->gasPrices(
    startDate: '2024-01-01',
    endDate: '2024-01-02',
    vat: true
);

Or set the default energy type:

use Baspa\EnergyZero\EnergyZero;
use Baspa\EnergyZero\Enums\EnergyType;

$energyZero = (new EnergyZero())->setDefaultEnergyType(EnergyType::GAS);

$prices = $energyZero->energyPrices('2024-01-01', '2024-01-02');

Get the current price

Get the current electricity price for the current hour:

$currentPrice = (new EnergyZero())->getCurrentPrice();
// Returns: ['price' => 0.25, 'datetime' => '2024-01-01T14:00:00']

Get prices for specific hours

Get prices for specific hours of a day:

$prices = (new EnergyZero())->getPricesForHours(
    date: '2024-01-01',
    hours: [8, 12, 18, 22]
);

Get the average price for a period

$averagePrice = (new EnergyZero())->getAveragePriceForPeriod(
    startDate: '2024-01-01',
    endDate: '2024-01-02',
    interval: Interval::HOUR,
    vat: true
);

Get the lowest price for a period

$lowestPrice = (new EnergyZero())->getLowestPriceForPeriod(
    startDate: '2024-01-01',
    endDate: '2024-01-02',
    interval: Interval::HOUR,
    vat: true
);

Get the highest price for a period

$highestPrice = (new EnergyZero())->getHighestPriceForPeriod(
    startDate: '2024-01-01',
    endDate: '2024-01-02',
    interval: Interval::HOUR,
    vat: true
);

Get the prices above a threshold

$prices = (new EnergyZero())->getPricesAboveThreshold(
    startDate: '2024-01-01',
    endDate: '2024-01-02',
    threshold: 0.05,
    interval: Interval::HOUR,
    vat: true
);

Get the prices below a threshold

$prices = (new EnergyZero())->getPricesBelowThreshold(
    startDate: '2024-01-01',
    endDate: '2024-01-02',
    threshold: 0.05,
    interval: Interval::HOUR,
    vat: true
);

Get the peak hours

Get the top N peak hours for a period.

$peakHours = (new EnergyZero())->getPeakHours(
    startDate: '2024-01-01',
    endDate: '2024-01-02',
    topN: 5,
    interval: Interval::HOUR,
    vat: true
);

Get the valley hours

Get the top N valley hours for a period.

$valleyHours = (new EnergyZero())->getValleyHours(
    startDate: '2024-01-01',
    endDate: '2024-01-02',
    topN: 5,
    interval: Interval::HOUR,
    vat: true
);

Testing

composer test

API Documentation

For developers who want to build their own client in another programming language, see API.md for:

• Complete API endpoint documentation
• Query parameters and response format
• Code examples in Python, JavaScript, and cURL
• Information about price availability times

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Baspa
• All Contributors

License

The MIT License (MIT). Please see License File for more information.