EP-Online Energy Label Scraper

An Apify Actor that looks up registered Dutch energy labels on EP-Online by postcode and house number (huisnummer).

API key: Not required for normal use — default website scrape needs no key.
Optional: only if you choose Official Public API as the data source, request your own RVO key at apikey.ep-online.nl (free registration via RVO; not supplied by this Actor).

What it does

• Scrapes registered energielabel data from EP-Online for each address (live HTTP search, HTML parsing, structured JSON output) — default, no key
• Or calls the official Public API (public.ep-online.nl, v5) when you set data source to Official Public API and supply an optional encrypted API key (Apify secret input)
• Batch lookup for many addresses in one run
• Optional EP-Online search filters (same checkboxes as the website — applied to scraped results so your dataset matches the site UI)
• Handles 0, 1, or many label rows per address (e.g. multiple verblijfsobjecten)
• Extracts label class, dates, certificate holder, performance metrics, and measured values from each result card
• Conservative rate limits for F5 bot mitigation on ep-online.nl
• Pay Per Event billing with cost caps

Input

API key & data source (read first)

Default (scrape)	No API key. Leave EP-Online API key empty.
Official Public API (officialApi)	You need an RVO API key → request it at apikey.ep-online.nl (also linked from EP-Online open data). Paste it in the Actor’s EP-Online API key field (encrypted secret on Apify).

Setting	When to use	API key
dataSource: scrape (default)	Same data as the EP-Online website UI; filters applied after scrape	Not used — leave key empty
dataSource: officialApi	RVO Public REST API v5 — BAG IDs, NTA metrics, full officialApiRecord on each row	Your key from apikey.ep-online.nl → epOnlineApiKey

On Apify: paste your key into the Actor’s EP-Online API key field in the Console input form or API run body. It is stored as an encrypted secret input and is not shown in run logs.

After you have a key (Official API only):

1. Confirm activation from RVO’s e-mail (within 24 hours).
2. Save the key when RVO shows it — they do not e-mail the key itself.
3. In this Actor: Data source = Official Public API, paste key into EP-Online API key.

Addresses (required)

Field	Type	Description
addresses	array	List of { "postcode", "houseNumber", "houseNumberAddition?" }

Postcode is normalized (uppercase, spaces removed). You can pass houseNumber as 18 with houseNumberAddition C, or combined as 18C in houseNumber. Invalid rows are skipped with a warning; the run fails if none are valid.

Address match mode

EP-Online does not search on huisnummertoevoeging — a query for 1015KP 18C still returns every unit at 18 (A, B, C, D, …). By default the Actor keeps only the row whose result header matches your requested unit.

Value	Behavior
exact (default)	One dataset row per matching unit (e.g. only 1015KP 18 C)
all	Every unit EP-Online returns at that house number

Each result row includes resultAddress, addressMatched, and resultsAtSearchCount (how many units EP-Online returned before filtering).

Search filters

How to read each checkbox

Value	Meaning
false (default)	Ignore this filter — does not remove that type. With every box off, you get all scraped registrations.
true	Narrow results — keep rows that match this category (combined with other groups; see below).

Optional searchFilters mirror the checkboxes on ep-online.nl. For each address the Actor scrapes the full EP-Online search results page, extracts every registration card, then applies your filter settings when building the dataset — same idea as ticking boxes on the website.

Groups (Registration type, Status, Building class, Scope): if every box in a group is off, that group does not narrow anything. If any box in a group is on, a row must match at least one turned-on option in that group.

Input field	EP-Online (NL)	When true (when false, ignored)
filterEnergyLabel	Energielabel	Only energielabel registrations (in this group)
filterTailoredAdvice	Maatwerkadvies	Only maatwerkadvies registrations (in this group)
filterStatusExisting	Bestaand	Rows with status Bestaand
filterStatusNewLicenseApplication	Vergunningsaanvraag	Rows with status Vergunningsaanvraag
filterStatusNewCompletion	Oplevering	Rows with status Oplevering
filterFunctionResidential	Woningbouw	Residential (woningbouw) rows
filterFunctionUtility	Utiliteitsbouw	Utility / commercial rows
filterScopeResidence	Verblijfsobject	Unit-level (verblijfsobject) scope
filterScopeBuilding	Pand	Whole-building (pand) scope
filterDeletedFalse	Verwijderd (hidden on site)	Omit deleted registrations

How filtering works on the website: EP-Online returns the full result list for a postcode + house number; checkbox filters narrow what you see in the UI. This Actor follows the same pattern: it loads all registration cards for the address, then applies your searchFilters when building dataset rows.

Performance

Field	Default	Description
maxConcurrency	1	Parallel lookups (max 3)
maxRequestsPerMinute	30	Address lookups per minute
proxyConfiguration	off	Apify proxy (recommended if rate-limited)

Example — single address

{
  "addresses": [
    {
      "postcode": "1221JV",
      "houseNumber": "40"
    }
  ]
}

Example — batch with filters

{
  "addresses": [
    { "postcode": "1221JV", "houseNumber": "40" },
    { "postcode": "1012AB", "houseNumber": "1", "houseNumberAddition": "A" }
  ],
  "searchFilters": {
    "filterFunctionResidential": true,
    "filterStatusExisting": true
  },
  "maxConcurrency": 1,
  "maxRequestsPerMinute": 30
}

Scrape vs Official API — what you get (verified runs)

Both modes return the same shared columns (labelClass, dates, certificateHolder, performanceMetrics, measuredValues, rawFields, …). Each row also has dataSource (scrape | officialApi) and, for API runs, a full officialApiRecord object (typed JSON from RVO OpenAPI). Official API requires your key from apikey.ep-online.nl (see API key & data source above).

Example comparison with addressMatchMode: exact and all search filters off.

Example A — utiliteitsgebouw 1221JV 40 (label B)

	Website scrape	Official Public API v5
API key	Not needed	Your RVO key in EP-Online API key
Label & holder	B, E-Label Nederland B.V.	Same
Energy index	1,11 (from HTML)	1,11
performanceMetrics	Empty — the public result card for this registration does not render the BEREKEND/EIS grid	Empty — API response has no NTA metric fields for this record either
measuredValues	Empty on scrape	Bouwjaar 1991
Extra in rawFields	Dutch site labels: registratienummer, BAG verblijfsobject id, EI forfaitair, …	Gebouwklasse Utiliteitsbouw, SBIcode, BerekendeCO2Emissie, BerekendeEnergieverbruik, Berekeningstype, BAG IDs, …
officialApiRecord	null	Full v5 object (ISO dates, numeric EnergieIndex, Bouwjaar, …)
Dates (survey / valid until)	26-01-2017 / 26-01-2027	25-01-2017 / 25-01-2027 (API uses midnight UTC; website text can differ by one day)

Takeaway: for some utiliteits registrations the website shows a short card. The API still adds building class, SBI, CO₂, total energy use, bouwjaar, and machine-readable BAG fields you will not get from scrape alone.

Example B — woningbouw 1015KP 18 C (label C)

	Website scrape	Official Public API v5
performanceMetrics	6 rows (Energiebehoefte, primair fossiel, hernieuwbaar, temperatuuroverschrijding, warmtebehoefte, …) — EIS column mostly - on the site	Same 6 calculated values (mapped to the same labels/units); EIS still - when the API does not return requirement fields for this label
measuredValues	Parsed from HTML when shown (e.g. gebruiksoppervlakte)	Gebruiksoppervlakte thermische zone, Compactheid, Bouwjaar
rawFields	Extra Dutch labels from the card	Status Bestaand, Gebouwtype Appartement, Gebouwsubtype Tussendak, BAGPandIDs, all NTA numbers as strings, CO₂ / total verbruik, …
officialApiRecord	null	Complete structured record (e.g. BAGVerblijfsobjectID, Gebouwklasse Woningbouw)

Takeaway: for typical woningbouw units, scrape and API align on core metrics shown on EP-Online. Choose Official API when you need BAG/NTA export fields, numeric types in officialApiRecord, bulk-friendly REST access, or fields that never appear on the HTML card.

When to use which

Choose scrape (default)	Choose officialApi
No RVO key; mirror the website UI and filter checkboxes	You have an RVO API key from apikey.ep-online.nl
OK with HTML-derived formatting (commas, Dutch labels in rawFields)	Want officialApiRecord + consistent API field names for pipelines
Fine with ep-online.nl rate limits / optional proxy	Prefer direct JSON from public.ep-online.nl (still rate-limit via maxRequestsPerMinute)

Search filters (searchFilters) apply in both modes after data is fetched (scrape: parsed cards; API: mapped from API fields such as Gebouwklasse and Status).

Output

One dataset item per energy label row (or one row with lookupStatus: not_found when nothing matches).

Field	Description
searchPostcode, searchHouseNumber, searchHouseNumberAddition, searchValue	Search context
labelClass, energyIndex, registrationDate, surveyDate, validUntil, certificateHolder	Registration block (top-level)
performanceMetrics	Array of { label, berekend, eis, unit } — one entry per grid row (amounts separate from unit)
measuredValues	Array of { label, value, unit } — e.g. usable floor area 117,49 + m²
rawFields	Other Dutch scalar fields
resultIndex, totalResultsAtAddress, lookupStatus, scrapedAt	Meta

Example performanceMetrics entry:

{
  "label": "Warmtebehoefte",
  "berekend": "157,04",
  "eis": "-",
  "unit": "kWh/m²⋅jr"
}

Rate limiting

EP-Online uses F5 bot mitigation. Defaults (maxConcurrency: 1, maxRequestsPerMinute: 30) are conservative. If you see HTTP 429:

• Lower maxRequestsPerMinute
• Enable proxyConfiguration

Without a proxy, the Actor aborts on 429 instead of retrying the same IP indefinitely.

Pay Per Event billing

Event	Charged by	Description
apify-actor-start	Apify (auto)	Once per run start
apify-default-dataset-item	Apify (auto)	Once per dataset row pushed
ep-online-lookup	Custom	Once per input address processed
retry-event	Custom	Once per retry on a failed lookup request
event-proxy	Custom	Once per run when using Apify Proxy (no group)
event-proxy-group	Custom	Once per run when using a proxy group

In the Apify Console, open this Actor’s Pricing tab for current event rates. Cap spend with Max total charge (USD) or Max paid dataset items when you start a run.

Disclaimer

This Actor is for lawful use only. By using it you agree to:

• Respect EP-Online / RVO terms and applicable law
• Avoid excessive request rates
• Use data responsibly

This Actor is not affiliated with or endorsed by RVO or EP-Online.

Resources

• EP-Online
• EP-Online open data & API key registration
• Public API v5 (Swagger)
• Apify Documentation
• Run this Actor via API