Skip to content
EvolveEvolveEvolve

loqate

@evolve-framework/loqate · v1.0.0

A GraphQL module for type-ahead address entry through Loqate's Capture service, in the countries you configure. LoqateAddressSuggestModule answers addressSuggest and addressResolve from the contract in @evolve-framework/schemas. Loqate has no lookup by postal code and house number, so this package has no module for addressLookup.

When to use

  • A shop's address form suggests addresses while the buyer types, in countries outside the Netherlands.

It is engine-agnostic, so compose it beside any commerce engine. To fill in Dutch addresses by postal code as well, compose PdokAddressLookupModule from @evolve-framework/pdok beside it.

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/loqate @evolve-framework/core graphql
    Requirements3
    @evolve-framework/core>= 1.8.0 < 2.0.0
    @types/node>=22optional
    graphql>= 16.0.0 < 17.0.0

For example:

import { LoqateAddressSuggestModule } from "@evolve-framework/loqate";


export const addressLookup = new LoqateAddressSuggestModule({
  apiKey: process.env.LOQATE_API_KEY ?? "",
  countries: ["BE", "DE", "FR", "GB"],
});

Modules

LoqateAddressSuggestModule

Query.addressSuggest and addressResolve from Loqate's Capture service, for type-ahead address entry in the configured countries.

Every query answers null for a country it is not configured for, or when Loqate is unavailable, so a form falls back to another way of entering the address.

import { LoqateAddressSuggestModule } from "@evolve-framework/loqate";
new LoqateAddressSuggestModule(options: LoqateAddressSuggestOptions)
OptionTypeDescription
apiKeystring

The Loqate API key, from the site's secret configuration.

countriesreadonly string[]

The countries to answer for, as ISO 3166-1 alpha-2 codes. Loqate covers nearly every country and bills per resolved address, so a site names the ones it sells to; any other country answers null without a request.

baseUrl?string

Defaults to Loqate's Capture Interactive endpoints.

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/loqateLoqateAddressSuggestModule and its options1 export