Energy labels endpoint

README.md

@@ -12,6 +12,7 @@ Register for free to obtain a **test API key** at [nederlandpostcode.nl](https:/
   - [Address Endpoint](#address-endpoint)
     - [Single Address](#single-address)
     - [Multiple Addresses](#multiple-addresses)
+  - [Energy Label Endpoint](#energy-label-endpoint)
   - [Quota Endpoint](#quota-endpoint)
 - [Error Handling](#error-handling)
 
@@ -42,7 +43,7 @@ try {
     $address = $client->find(
         postcode: '1118BN',
         number: 800,
-        addition: ['coordinates'],
+        attributes: ['coordinates'],
     );
 } catch (NederlandPostcodeException $exception) {
     // handle exception
@@ -79,7 +80,7 @@ $address = $client->find(
     postcode: '1118BN',
     number: 800,
     addition: null,
-    attributes: ['coordinates']
+    attributes: ['coordinates'],
 );
 ```
 
@@ -116,71 +117,79 @@ $client = new NederlandPostcodeClient(
     key: 'npa_live_XXX'
 );
 
-$address = $client->list(
+$addresses = $client->list(
     postcode: '1015CN',
     number: 10,
     addition: null,
-    attributes: ['coordinates']
+    attributes: ['coordinates'],
 );
 ```
 
-This will return an `AddressCollection` object like this:
+This will return an `AddressCollection` like this:
 
 ```php
 AddressCollection {
     items: [
         Address {
             postcode: "1015CN",
             number: 10,
-            addition: 'A',
+            addition: "A",
             street: "Keizersgracht",
             city: "Amsterdam",
             municipality: "Amsterdam",
             province: "Noord-Holland",
-            coordinates: Coordinates {
-                latitude: 52.379401496779124,
-                longitude: 4.889216673725493
-            }
+            country: "Nederland",
+            coordinates: Coordinates { ... }
         },
         Address {
             postcode: "1015CN",
             number: 10,
-            addition: 'B',
+            addition: "B",
             street: "Keizersgracht",
-            city: "Amsterdam",
-            municipality: "Amsterdam",
-            province: "Noord-Holland",
-            coordinates: Coordinates {
-                latitude: 52.379401496779124,
-                longitude: 4.889216673725493
-            }
-        },
-        Address {
-            postcode: "1015CN",
-            number: 10,
-            addition: 'C',
-            street: "Keizersgracht",
-            city: "Amsterdam",
-            municipality: "Amsterdam",
-            province: "Noord-Holland",
-            coordinates: Coordinates {
-                latitude: 52.379401496779124,
-                longitude: 4.889216673725493
-            }
-        },
-        Address {
-            postcode: "1015CN",
-            number: 10,
-            addition: 'D',
-            street: "Keizersgracht",
-            city: "Amsterdam",
-            municipality: "Amsterdam",
-            province: "Noord-Holland",
-            coordinates: Coordinates {
-                latitude: 52.379401496779124,
-                longitude: 4.889216673725493
-            }
-        },
+            ...
+        }
+    ]
+}
+```
+
+### Energy Label Endpoint
+
+The energy label endpoint allows you to fetch energy label information for a given postcode and house number (with optional addition).
+
+```php
+use Label84\NederlandPostcode\NederlandPostcodeClient;
+
+$client = new NederlandPostcodeClient(
+    key: 'npa_live_XXX'
+);
+
+$energyLabels = $client->energyLabels()->get(
+    postcode: '1118BN',
+    number: 800,
+    addition: null,
+);
+```
+
+This will return an `EnergyLabelCollection` like this:
+
+```php
+EnergyLabelCollection {
+    items: [
+        EnergyLabel {
+            postcode: "1118BN",
+            number: 800,
+            addition: null,
+            street: "Schiphol Boulevard",
+            city: "Schiphol",
+            inspectionDate: DateTime("2022-08-02"),
+            validUntilDate: DateTime("2032-08-02"),
+            constructionType: "utiliteitsbouw",
+            buildingType: null,
+            energyLabel: "A+++",
+            maxEnergyDemand: 98.4,
+            maxFossilEnergyDemand: 55.48,
+            minRenewableShare: 55.3
+        }
     ]
 }
 ```

src/DTO/EnergyLabel.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Label84\NederlandPostcode\DTO;
+
+use DateTime;
+
+class EnergyLabel
+{
+    public function __construct(
+        public readonly string $postcode,
+        public readonly int $number,
+        public readonly ?string $addition,
+        public readonly string $street,
+        public readonly string $city,
+        public readonly DateTime $inspectionDate,
+        public readonly DateTime $validUntilDate,
+        public readonly string $constructionType,
+        public readonly ?string $buildingType,
+        public readonly string $energyLabel,
+        public readonly ?float $maxEnergyDemand,
+        public readonly ?float $maxFossilEnergyDemand,
+        public readonly ?float $minRenewableShare,
+    ) {}
+}

src/DTO/EnergyLabelCollection.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Label84\NederlandPostcode\DTO;
+
+use ArrayIterator;
+use Countable;
+use IteratorAggregate;
+
+/** @implements IteratorAggregate<EnergyLabel> */
+class EnergyLabelCollection implements IteratorAggregate, Countable
+{
+    /** @var EnergyLabel[] */
+    protected array $items = [];
+
+    /** @param EnergyLabel[] $items */
+    public function __construct(array $items = [])
+    {
+        $this->items = $items;
+    }
+
+    /** @return EnergyLabel[] */
+    public function all(): array
+    {
+        return $this->items;
+    }
+
+    public function count(): int
+    {
+        return count($this->items);
+    }
+
+    /** @return ArrayIterator<int, EnergyLabel> */
+    public function getIterator(): ArrayIterator
+    {
+        return new ArrayIterator($this->items);
+    }
+
+    public function isEmpty(): bool
+    {
+        return empty($this->items);
+    }
+}

src/Factories/EnergyLabelCollectionFactory.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace Label84\NederlandPostcode\Factories;
+
+use DateTime;
+use Label84\NederlandPostcode\DTO\EnergyLabel;
+use Label84\NederlandPostcode\DTO\EnergyLabelCollection;
+
+class EnergyLabelCollectionFactory
+{
+    /**
+     * @param array{data: array{
+     *      postcode: string,
+     *      number: int,
+     *      addition?: string|null,
+     *      street: string,
+     *      city: string,
+     *      energy_labels: array<array{
+     *          inspection_date: string,
+     *          valid_until_date: string,
+     *          construction_type: string,
+     *          building_type: string|null,
+     *          energy_label: string,
+     *          max_energy_demand: float,
+     *          max_fossil_energy_demand: float,
+     *          min_renewable_share: float,
+     *      }>,
+     * }} $response
+     */
+    public static function make(array $response): EnergyLabelCollection
+    {
+        $postcode = $response['data']['postcode'];
+        $number = $response['data']['number'];
+        $addition = $response['data']['addition'] ?? null;
+        $street = $response['data']['street'];
+        $city = $response['data']['city'];
+
+        $energyLabels = array_map(function (array $attributes) use ($postcode, $number, $addition, $street, $city) {
+            return new EnergyLabel(
+                postcode: $postcode,
+                number: $number,
+                addition: $addition,
+                street: $street,
+                city: $city,
+                inspectionDate: new DateTime($attributes['inspection_date']),
+                validUntilDate: new DateTime($attributes['valid_until_date']),
+                constructionType: $attributes['construction_type'],
+                buildingType: $attributes['building_type'],
+                energyLabel: $attributes['energy_label'],
+                maxEnergyDemand: $attributes['max_energy_demand'],
+                maxFossilEnergyDemand: $attributes['max_fossil_energy_demand'],
+                minRenewableShare: $attributes['min_renewable_share'],
+            );
+        }, $response['data']['energy_labels']);
+
+        $energyLabels = array_values($energyLabels);
+
+        return new EnergyLabelCollection($energyLabels);
+    }
+}

src/NederlandPostcodeClient.php

@@ -9,12 +9,15 @@
 use Label84\NederlandPostcode\Enums\AddressAttributesEnum;
 use Label84\NederlandPostcode\Exceptions\AddressNotFoundException;
 use Label84\NederlandPostcode\Exceptions\MultipleAddressesFoundException;
+use Label84\NederlandPostcode\Exceptions\NederlandPostcodeException;
 use Label84\NederlandPostcode\Resources\AddressesResource;
+use Label84\NederlandPostcode\Resources\EnergyLabelResource;
 use Label84\NederlandPostcode\Resources\QuotaResource;
 
 /**
  * @method AddressesResource addresses()
  * @method QuotaResource quota()
+ * @method EnergyLabelResource energyLabels()
  * @method AddressCollection<Address> list(string $postcode, int $number, ?string $addition = null, array<int|string, string|AddressAttributesEnum> $attributes = [])
  * @method Address find(string $postcode, int $number, ?string $addition = null, array<int|string, string|AddressAttributesEnum> $attributes = [])
  * @method Quota usage()
@@ -46,22 +49,32 @@ public function __construct(
 
     /**
      * @param  array<string, mixed>  $options
-     * @return array<string, mixed>
+     * @return array<mixed, mixed>
      */
     public function request(string $method, string $uri, array $options = []): array
     {
         $response = $this->client->request($method, $uri, $options);
 
         $body = $response->getBody()->getContents();
 
-        return json_decode($body, true); // @phpstan-ignore return.type
+        $decoded = json_decode($body, true);
+
+        if (! is_array($decoded)) {
+            throw new NederlandPostcodeException('Invalid JSON response from API');
+        }
+        return $decoded;
     }
 
     public function addresses(): AddressesResource
     {
         return new AddressesResource($this);
     }
 
+    public function energyLabels(): EnergyLabelResource
+    {
+        return new EnergyLabelResource($this);
+    }
+
     public function quota(): QuotaResource
     {
         return new QuotaResource($this);

src/Resources/EnergyLabelResource.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Label84\NederlandPostcode\Resources;
+
+use Label84\NederlandPostcode\DTO\EnergyLabelCollection;
+use Label84\NederlandPostcode\Factories\EnergyLabelCollectionFactory;
+
+class EnergyLabelResource extends BaseResource
+{
+    public function get(
+        string $postcode,
+        int $number,
+        ?string $addition,
+    ): EnergyLabelCollection {
+        // @phpstan-ignore-next-line
+        return EnergyLabelCollectionFactory::make($this->request(
+            method: 'GET',
+            path: 'v1/energy-label',
+            query: [
+                'postcode' => $postcode,
+                'number' => $number,
+                'addition' => $addition,
+            ],
+        ));
+    }
+}

tests/Resources/EnergyLabelResourceTest.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Label84\NederlandPostcode\Tests\Resources;
+
+use Label84\NederlandPostcode\DTO\EnergyLabelCollection;
+use Label84\NederlandPostcode\Tests\TestCase;
+
+class EnergyLabelResourceTest extends TestCase
+{
+    public function test_get_single_result(): void
+    {
+        $result = $this->client
+            ->energyLabels()
+            ->get(
+                postcode: '1118BN',
+                number: 800,
+                addition: null,
+            );
+
+        $this->assertInstanceOf(EnergyLabelCollection::class, $result);
+        $this->assertCount(1, $result);
+    }
+
+    public function test_get_multiple_results(): void
+    {
+        $result = $this->client
+            ->energyLabels()
+            ->get(
+                postcode: '1015CN',
+                number: 10,
+                addition: 'A',
+            );
+
+        $this->assertInstanceOf(EnergyLabelCollection::class, $result);
+        $this->assertCount(2, $result);
+    }
+}