Skip to content
EvolveEvolveEvolve

photon

@evolve-framework/photon · v1.0.0

A GraphQL module for type-ahead address entry through Photon, the open-source geocoder over OpenStreetMap, in the countries you configure. PhotonAddressSuggestModule answers addressSuggest and addressResolve from the contract in @evolve-framework/schemas. It needs no API key: by default it asks the public instance komoot runs, and it can point at one you host.

When to use

  • A shop's address form suggests addresses while the buyer types, without a paid address service.
  • A shop moving off @evolve-framework/loqate: both serve the same contract, so swapping LoqateAddressSuggestModule for this one changes nothing for the storefront.

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/photon @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 { PhotonAddressSuggestModule } from "@evolve-framework/photon";


export const addressSuggest = new PhotonAddressSuggestModule({
  countries: ["BE", "DE", "FR", "NL"],
});

Modules

PhotonAddressSuggestModule

Query.addressSuggest and addressResolve from a Photon geocoder over OpenStreetMap, for type-ahead address entry in the configured countries.

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

import { PhotonAddressSuggestModule } from "@evolve-framework/photon";
new PhotonAddressSuggestModule(options: PhotonAddressSuggestOptions)
OptionTypeDescription
countriesreadonly string[]

The countries to answer for, as ISO 3166-1 alpha-2 codes; any other country answers null without a request.

baseUrl?string

Defaults to the public instance; point it at a self-hosted Photon.

timeoutMs?number

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

minQueryLength?number

The fewest characters a search needs before Photon is asked. Defaults to 3.

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