Energielabels in de buurt opvragen: Energielabel Radius API

Wil je weten welke energielabels de woningen en gebouwen in de buurt van een locatie hebben, bijvoorbeeld om ze op een kaart te tonen of een woning met de omgeving te vergelijken? Met het nieuwe /energy-label-radius endpoint van de Nederland Postcode API vraag je in één verzoek de energielabels van alle adressen binnen een straal van maximaal 1000 meter op, gesorteerd op afstand.

Daarmee bestaat de Energielabel API nu uit drie endpoints: voor één adres, voor een hele straat en voor alle adressen rond een locatie.

Hoe werkt het?

Je geeft een coördinaat (latitude en longitude) en een straal in meters op. De API zoekt alle adressen binnen die straal waarvoor een energielabel is geregistreerd en retourneert ze gesorteerd op afstand, het dichtstbijzijnde adres eerst.

Per adres krijg je de adresgegevens, de coördinaten, de afstand in meters tot het opgegeven punt en de labelklasse van het meest recente energielabel. Adressen zonder energielabel worden overgeslagen.

Voorbeeld API-verzoek

Onderstaand verzoek haalt de energielabels op van alle adressen binnen 150 meter van Schiphol Boulevard 800:

GET https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150

Het resultaat is een gepagineerde lijst met adressen, gesorteerd op afstand:

{
    "data": [
        {
            "postcode": "1118BN",
            "number": 800,
            "addition": null,
            "street": "Schiphol Boulevard",
            "city": "Schiphol",
            "coordinates": {
                "latitude": 52.30528553688755,
                "longitude": 4.750645160863609
            },
            "distance": 0,
            "energy_label": "A+++"
        },
        {
            "postcode": "1118CX",
            "number": 308,
            "addition": null,
            "street": "Evert van de Beekstraat",
            "city": "Schiphol",
            "coordinates": {
                "latitude": 52.30482565215747,
                "longitude": 4.749222421097077
            },
            "distance": 110,
            "energy_label": "A+"
        },
        {
            "postcode": "1118CL",
            "number": 1,
            "addition": null,
            "street": "Evert van de Beekstraat",
            "city": "Schiphol",
            "coordinates": {
                "latitude": 52.30549394509628,
                "longitude": 4.752529225036044
            },
            "distance": 130,
            "energy_label": "A+"
        }
    ],
    "links": {
        "first": "https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150&page=1",
        "last": "https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.305285&longitude=4.750645&radius=150&page=1"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://api.nederlandpostcode.nl/v1/energy-label-radius",
        "per_page": 10,
        "to": 3,
        "total": 3
    }
}

Wat zit er in de response?

• distance - de afstand in hele meters tussen het opgegeven punt en het adres
• energy_label - de labelklasse van het meest recente energielabel, van A+++++ tot en met G. In zeldzame gevallen is er geen labelklasse bekend en is de waarde null.
• coordinates - de latitude en longitude van het adres, zodat je het direct op een kaart kunt plaatsen

Adressen op dezelfde afstand, zoals appartementen in hetzelfde gebouw, worden gesorteerd op postcode, huisnummer en toevoeging. Zo blijft de volgorde van de resultaten over alle pagina's hetzelfde.

Van adres naar energielabels in de buurt

Vaak begin je niet met een coördinaat, maar met een adres. Vraag dan eerst de coördinaten van het adres op via het /address endpoint met attributes[]=coordinates:

GET https://api.nederlandpostcode.nl/v1/address?postcode=1118BN&number=800&attributes[]=coordinates

Gebruik de latitude en longitude uit de response vervolgens als middelpunt voor het radius-verzoek:

GET https://api.nederlandpostcode.nl/v1/energy-label-radius?latitude=52.30528553688755&longitude=4.750645160863609&radius=500

Heeft het adres zelf een energielabel, dan staat het vooraan in het resultaat met een afstand van 0 meter. Andere adressen in hetzelfde gebouw delen dezelfde locatie en staan daar dan ook met 0 meter bij.

Alleen de labelklasse, of alle gegevens?

Het radius-endpoint geeft per adres alleen de labelklasse terug, zoals "A+" of "C". Dat houdt de response compact, ook als je honderden adressen opvraagt.

Heb je voor een specifiek adres meer nodig, zoals de registratiedatum, geldigheidsdatum, energiebehoefte of de labelhistorie? Vraag die dan op via het /v2/energy-label endpoint. Het overzicht van alle drie de endpoints en hun verschillen vind je op de pagina Energielabel API.

Paginering en verbruik

In een dichtbevolkte stad kunnen binnen een straal van 1000 meter duizenden adressen met een energielabel liggen. De resultaten worden daarom gepagineerd: standaard 10 per pagina, met per_page maximaal 25. In meta.total zie je hoeveel adressen er in totaal binnen de straal liggen en in meta.last_page hoeveel pagina's dat zijn.

Ieder verzoek telt als 1 verzoek voor je maandelijkse quota, ongeacht het aantal adressen in de response. Iedere opgevraagde pagina is een apart verzoek. Heb je maar een paar adressen nodig, begin dan met een kleine straal.

Waarvoor kun je dit gebruiken?

• Vastgoedplatforms en makelaars - laat bij een woning zien welke energielabels de woningen in de buurt hebben
• Kaartapplicaties - toon de energielabels van alle adressen rond een locatie direct op een kaart
• Taxateurs - vind vergelijkbare woningen in de omgeving en neem hun energielabel mee in je analyse
• Verduurzamings- en installatiebedrijven - vind woningen met een laag energielabel rond een locatie voor een gerichte buurtcampagne
• Gemeenten, woningcorporaties en onderzoekers - breng de energieprestaties van een buurt of wijk snel in kaart

Veelgestelde vragen

Wat is de Energielabel Radius API?

De Energielabel Radius API is een endpoint van de Nederland Postcode API waarmee je in één verzoek de energielabels opvraagt van alle adressen binnen een straal rond een coördinaat. Je geeft een latitude, longitude en straal in meters op. De API retourneert vervolgens alle adressen met een energielabel binnen die straal, gesorteerd op afstand.

Hoe groot mag de straal zijn?

De straal is minimaal 1 en maximaal 1000 meter.

Worden adressen zonder energielabel ook teruggegeven?

Nee. Alleen adressen waarvoor minimaal één energielabel is geregistreerd komen in het resultaat voor.

Hoe kom ik aan de coördinaten van een adres?

Vraag het adres op via het /v1/address endpoint met attributes[]=coordinates. Je krijgt dan de latitude en longitude van het adres terug, die je direct kunt gebruiken als middelpunt voor de Energielabel Radius API.

Krijg ik per adres alle energielabelgegevens?

Nee. Het veld energy_label bevat alleen de labelklasse van het meest recente energielabel, van A+++++ tot en met G. Heb je voor een adres ook de energieprestatiegegevens of de labelhistorie nodig, gebruik dan het /v2/energy-label endpoint.

Kan energy_label null zijn?

Ja, maar dat komt zelden voor. Het veld energy_label bevat de labelklasse van het meest recente energielabel van een adres. Is er wel een energielabel geregistreerd, maar is daarvan geen labelklasse bekend, dan is de waarde null.

Kan ik het endpoint uitproberen met een test API-key?

Ja. Met een test API-key werkt het endpoint wanneer het dichtstbijzijnde adres met een energielabel binnen de straal een postcode heeft die begint met 1012, 1015 of 1118. Anders krijg je een 403 Forbidden. De coördinaten van Schiphol Boulevard 800 (latitude 52.305285, longitude 4.750645) zijn een goed startpunt.

Bekijk de volledige API-documentatie voor alle parameters, statuscodes en voorbeelden.