Skip to content
EvolveEvolveEvolve

pdok

@evolve-framework/pdok · v1.0.0

GraphQL modules that fill in Dutch addresses from PDOK's Locatieserver, the government's free address search over the BAG register. PdokAddressLookupModule answers addressLookup by postal code and house number, and PdokAddressSuggestModule answers addressSuggest and addressResolve for type-ahead entry, from the contracts in @evolve-framework/schemas. Neither needs an API key or keeps a session.

When to use

  • A shop's address form fills in a Dutch address from a postal code and house number: compose PdokAddressLookupModule.
  • A shop offers type-ahead entry for Dutch addresses: compose PdokAddressSuggestModule.

Both are engine-agnostic, so compose them beside any commerce engine. Lookup and suggest are separate contracts, so a service can take each from a different source, such as the lookup from PDOK and type-ahead from @evolve-framework/loqate.

Get started

  1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

    pnpm add @evolve-framework/pdok @evolve-framework/core graphql
    Requirements3
    @evolve-framework/core>= 1.10.0 < 2.0.0
    @types/node>=22optional
    graphql>= 16.0.0 < 17.0.0

For example:

import {
  PdokAddressLookupModule,
  PdokAddressSuggestModule,
} from "@evolve-framework/pdok";


export const addressModules = [
  new PdokAddressLookupModule({ timeoutMs: 2000 }),
  new PdokAddressSuggestModule({ timeoutMs: 2000 }),
];

Modules

PdokAddressLookupModule

Query.addressLookup for Dutch addresses by postal code and house number, from PDOK's free Locatieserver.

import { PdokAddressLookupModule } from "@evolve-framework/pdok";
new PdokAddressLookupModule(options?: PdokAddressLookupOptions)
OptionTypeDescription
baseUrl?string

Defaults to the public Locatieserver v3.1.

timeoutMs?number

How long a request may take before it counts as unavailable. Defaults to 3 seconds.

fetch?((url: string | URL | Request, options?: RequestInit | undefined, spanName?: string | undefined) => Promise<Response>)

Defaults to the framework's traced fetch.

Extends AbstractModule<unknown>.

PdokAddressSuggestModule

Query.addressSuggest and addressResolve for type-ahead entry of Dutch addresses, from PDOK's free Locatieserver.

import { PdokAddressSuggestModule } from "@evolve-framework/pdok";
new PdokAddressSuggestModule(options?: PdokAddressLookupOptions)
OptionTypeDescription
baseUrl?string

Defaults to the public Locatieserver v3.1.

timeoutMs?number

How long a request may take before it counts as unavailable. Defaults to 3 seconds.

fetch?((url: string | URL | Request, options?: RequestInit | undefined, spanName?: string | undefined) => Promise<Response>)

Defaults to the framework's traced fetch.

Extends AbstractModule<unknown>.

Entry points

@evolve-framework/pdokPdokAddressLookupModule, PdokAddressSuggestModule, pdokCityLookup and their options3 exports