PHP SDK

<div class="admonition admonition-warning"><span class="admonition-icon">⚠️</span><div class="admonition-content"><p>Closed Beta The PHP SDK is under development. In the meantime, you can call the API directly using Guzzle or Laravel's HTTP client — see the <a href="/docs/api">API Reference</a> for endpoints and parameters.</p> </div></div>

Official PHP client for the emissions.dev API.

Installation

composer require emissions-dev/sdk

Requirements: PHP 8.1+

Quick Start

use EmissionsDev\Client;

$client = new Client('em_live_xxxx');

$result = $client->freight()->calculate([
    'origin_country' => 'GB',
    'destination_country' => 'FR',
    'weight' => 1000,
]);

echo $result->data->attributes->emissions->co2e . " kg CO2e";

Configuration

$client = new Client(
    apiKey: 'em_live_xxxx',
    baseUrl: 'https://api.emissions.dev/v1',
    timeout: 30,
    retries: 3
);

Freight API

$result = $client->freight()->calculate([
    'origin_country' => 'GB',
    'destination_country' => 'DE',
    'origin_location' => 'London',
    'destination_location' => 'Berlin',
    'weight' => 5000,
    'transport_mode' => 'road',
    'equivalents' => true,
]);

$co2e = $result->data->attributes->emissions->co2e;
$distance = $result->data->attributes->route->total_distance_km;

Travel API

$result = $client->travel()->calculate([
    'origin_country' => 'GB',
    'destination_country' => 'FR',
    'origin_location' => 'London',
    'destination_location' => 'Paris',
    'transport_mode' => 'flight',
    'cabin_class' => 'business',
    'passengers' => 2,
    'return_trip' => true,
]);

echo "Total: {$result->data->attributes->emissions->co2e} kg\n";
echo "Per passenger: {$result->data->attributes->emissions->per_passenger_kg} kg\n";

Hotel API

// Calculate emissions
$result = $client->hotel()->calculate([
    'country' => 'GB',
    'nights' => 3,
    'rooms' => 1,
]);

// Get all factors
$factors = $client->hotel()->factors();

// Compare countries
$comparison = $client->hotel()->compare([
    'countries' => 'GB,FR,DE,ES',
    'nights' => 5,
]);

Error Handling

use EmissionsDev\Client;
use EmissionsDev\Exceptions\UnauthorizedException;
use EmissionsDev\Exceptions\ValidationException;
use EmissionsDev\Exceptions\RateLimitException;

try {
    $result = $client->freight()->calculate([
        'origin_country' => 'GB',
        'destination_country' => 'XX',
        'weight' => 1000,
    ]);
} catch (UnauthorizedException $e) {
    echo "Invalid API key";
} catch (ValidationException $e) {
    echo "Validation error: {$e->getField()} - {$e->getMessage()}";
} catch (RateLimitException $e) {
    echo "Rate limited. Retry after {$e->getRetryAfter()} seconds";
}

Laravel Integration

Config

// config/services.php
return [
    'emissions' => [
        'api_key' => env('EMISSIONS_API_KEY'),
    ],
];

Service Provider

// AppServiceProvider.php
use EmissionsDev\Client;

public function register(): void
{
    $this->app->singleton(Client::class, function ($app) {
        return new Client(config('services.emissions.api_key'));
    });
}

Controller

use EmissionsDev\Client;

class ShippingController extends Controller
{
    public function __construct(private Client $emissions) {}

    public function calculate(Request $request)
    {
        $result = $this->emissions->freight()->calculate([
            'origin_country' => $request->from_country,
            'destination_country' => $request->to_country,
            'weight' => $request->weight_kg,
        ]);

        return response()->json([
            'co2e_kg' => $result->data->attributes->emissions->co2e,
        ]);
    }
}