@omnizoek/sdk

Official TypeScript/JavaScript SDK for the OmniZoek API — Dutch government data in one clean REST API.

Features

• Full TypeScript support — every request and response is typed
• ESM + CJS dual output — works in Node.js, Deno, Bun, and browser bundles
• Automatic retries — exponential back-off on 429 Rate Limit responses
• Typed errors — OmniAuthError, OmniNotFoundError, OmniRateLimitError etc.
• Zero dependencies — uses the native fetch API (Node ≥ 18)

Installation

npm install @omnizoek/sdk
# or
pnpm add @omnizoek/sdk
# or
yarn add @omnizoek/sdk

Quick start

import { OmniClient } from "@omnizoek/sdk";

const omni = new OmniClient({ apiKey: "omni_live_…" });

// Enrich a Dutch address
const address = await omni.geo.enrichAddress({
  postcode: "1012LG",
  houseNumber: "1",
});
console.log(address.city); // "Amsterdam"

// Get the statutory minimum wage for a 21-year-old
const wage = await omni.hr.minimumWage({ age: 21 });
console.log(wage.hourly_eur); // e.g. 13.27

API key

Get a free sandbox key instantly — no sign-up required:

curl -X POST https://api.omnizoek.nl/v1/keys/test

Or visit omnizoek.nl/playground to try every endpoint live.

Endpoints

omni.geo — Geographic enrichment

// Enrich a Dutch address (BAG + PDOK)
const result = await omni.geo.enrichAddress({
  postcode: "1012LG",
  houseNumber: "1",
  // energy?: boolean  — include EP-Online energy label (default: true)
});

// Forward geocode a free-text query
const geo = await omni.geo.geocode({ q: "Damrak 1, Amsterdam", rows: 5 });
// result: { query, results: [{ display_name, lat, lon, postcode, city, … }] }

// Reverse geocode coordinates to an address
const rev = await omni.geo.reverseGeocode({ lat: 52.3756, lon: 4.8951 });
// result: { display_name, postcode, city, street, house_number, … }

Returns: full BAG address, coordinates, municipality, province, energy label.

omni.finance — Financial utilities

// IBAN → BIC
const bic = await omni.finance.ibanToBic({ iban: "NL91ABNA0417164300" });
// result: { iban, bic, bank_name, country_code }

// VAT number verification (EU VIES)
const vat = await omni.finance.vatVerify({
  countryCode: "NL",
  vatNumber: "123456782B01",
});
// result: { valid, status, company_name, address, checked_at, … }

// ECB daily euro exchange rates
const rates = await omni.finance.exchangeRates();
// result: { base: "EUR", date, rates: { USD: 1.08, GBP: 0.85, … } }

// VAT rates for an EU country
const vatRates = await omni.finance.vatRates({ country: "NL" });
// result: { standard_rate: 21, reduced_rates: [9], categories: […] }

omni.compliance — Compliance checks

// Validate a BSN or IBAN checksum
const result = await omni.compliance.validateFinance({
  type: "iban",           // "bsn" | "iban"
  number: "NL91ABNA0417164300",
});
// result: { valid, type, number, algorithm, detail }

omni.hr — HR calculations

// Statutory minimum wage (WML)
const wage = await omni.hr.minimumWage({ age: 21, date: "2024-07-01" });
// result: { age, date, hourly_eur, daily_eur, monthly_eur, law_reference }

// Holiday/public-holiday surcharge
const surcharge = await omni.hr.holidaySurcharge({
  date: "2024-12-25",
  industry: "retail",
});
// result: { is_holiday, holiday_name, surcharge_multiplier, … }

omni.realEstate — Real estate

// EP-Online energy label
const label = await omni.realEstate.energyLabel({
  postcode: "1012LG",
  houseNumber: "1",
});
// result: { energy_label, label_class, registered_at, valid_until, … }

omni.logistics — Logistics

// Zero-emission zone check
const ze = await omni.logistics.emissionZone({ kenteken: "AB123C" });
// result: { ze_compliant, fuel_types, euro_standard, zones_checked, … }

// NS train disruptions
const disruptions = await omni.logistics.transitDisruptions({ stationCode: "ASD" });
// result: { station_code, disruptions: [{ type, title, cause, start, end }], … }

// Full vehicle history from RDW (4 datasets + recalls)
const history = await omni.logistics.vehicleHistory({ kenteken: "AB123C" });
// result: { make, commercial_name, fuel_types, euro_standard, apk_expiry_date, open_recalls, … }

omni.business — Business entity data

// Direct LEI lookup by code
const lei = await omni.business.leiLookup({ lei: "5493001KJTIIGC8Y1R12" });
// result: { legal_name, jurisdiction, status, registered_address, bic_codes, … }

// Search by company name
const results = await omni.business.leiLookup({ name: "ING", country: "NL" });
// result: { query, results: [LeiRecord, …] }

omni.energy — Energy grid

// ENTSO-E negative price / grid trigger
const grid = await omni.energy.gridTrigger(); // defaults to NL
// result: { negative_price, trigger, current_price_eur_mwh, period_start, … }

omni.webhooks — Outbound webhooks

// Register
const wh = await omni.webhooks.register({
  url: "https://example.com/hook",
  events: ["quota.warning", "quota.exceeded"],
});
// result: { webhook_id, secret }  ← store secret for HMAC verification

// List all
const { webhooks } = await omni.webhooks.list();

// Delete
await omni.webhooks.delete(wh.webhook_id);

Error handling

All errors extend OmniError:

import {
  OmniAuthError,
  OmniNotFoundError,
  OmniRateLimitError,
  OmniUpstreamError,
  OmniNetworkError,
} from "@omnizoek/sdk";

try {
  const result = await omni.geo.enrichAddress({ postcode: "0000XX", houseNumber: "0" });
} catch (err) {
  if (err instanceof OmniAuthError)       console.error("Invalid API key");
  if (err instanceof OmniNotFoundError)   console.error("Address not found");
  if (err instanceof OmniRateLimitError)  console.error("Rate limited — retry after", err.retryAfterMs, "ms");
  if (err instanceof OmniUpstreamError)   console.error("Upstream data source unavailable");
  if (err instanceof OmniNetworkError)    console.error("Network error", err.cause);
}

Client options

const omni = new OmniClient({
  apiKey: "omni_live_…",       // required
  baseUrl: "https://api.omnizoek.nl", // optional override
  maxRetries: 3,               // max 429 retries (default: 3)
  retryDelayMs: 500,           // base back-off delay (default: 500 ms)
  timeoutMs: 20_000,           // request timeout (default: 20 s)
});

Requirements

• Node.js ≥ 18 (native fetch)
• Browsers and edge runtimes with fetch support
• TypeScript 5.x (optional, for types)

License

Proprietary — see LICENSE.