Infer Core SDK API reference

`new InferCore(config)`

The core logic engine for Pro6PP Infer. Manages API communication, state transitions, and keyboard interaction logic.

Initializes a new instance of the Infer engine.

ConfigInferConfig

countryCountryCodeRequiredSets the API path

The country to perform address lookups in.

authKeystringAPI parameter

Your Pro6PP Authorization Key. Optional if using a proxy.

limitnumberAPI parameter

Number of suggestions to request per batch, at most 1000. 0 uses the default.

Default: 20

languageLanguageCodeAPI parameter

Language code for response labels. Affects the language of returned address labels. Only applicable for BE country code.

sortSortOrderAPI parameter

Sort mixed address and place suggestions by relevance or distance. Distance sorting requires the Infer Extended (infer::location) capability. It measures from lat and lng when provided, otherwise from the approximate location of the request IP, and sorts by relevance when neither is available.

Default: 'relevance'

latnumberAPI parameter

Latitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lng must also be provided.

lngnumberAPI parameter

Longitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lat must also be provided.

typesInferTypes

Suggestion types to request. Omit this to preserve the address-only default.

apiUrlstring

If provided, this URL is used as the API endpoint. The query params are appended, including country in lowercase.

If not provided, the SDK defaults to 'https://api.pro6pp.nl/v2/infer/{country}'.

fetcherFetcher

Custom fetch implementation for network requests.

Default: globalThis.fetch

debounceMsnumber

The delay in milliseconds before performing the API search. Note: A lower bound of 50ms is enforced to protect API stability.

Default: 150

maxRetriesnumber

Maximum number of retry attempts after a network error or a 5xx or 429 response. Valid range: 0 to 10.

Default: 0

onStateChange(state: InferState) => void

Callback triggered whenever the internal state (suggestions, loading status, etc.) updates.

onSelect(selection: AddressValue | string | null) => void

Callback triggered when an address selection completes or is cleared. Receives the AddressValue of the selected address, or its label as a string when the selection has no structured value. Receives null when the user edits a completed selection or selects a place after a structured address. Partial selections, such as a city or street, do not trigger it.

onPlaceSelect(selection: PlaceValue | null) => void

Callback triggered when a point of interest is selected, or with null when the user edits the selected place or selects an address instead.

Instance

stateInferState

The current read-only state of the engine. Use onStateChange to react to updates.

handleInput(value)→ void

Processes new text input from the user. Triggers a debounced API request and updates the internal state.

value string

The raw string from the input field.

loadMore()→ void

Increases the current limit and re-fetches the query to show more results.

handleKeyDown(event)→ void

Handles keyboard events for the input field. Supports:

ArrowUp/ArrowDown: Navigate through the suggestion list.
Enter: Select the currently highlighted suggestion.
Space: Automatically inserts a comma if a numeric street number is detected.

event KeyboardEvent | { key: string; target: EventTarget | null; preventDefault: () => void; }

The keyboard event from the input element.

selectItem(item)→ boolean

Manually selects a suggestion or a string value. This is typically called when a user clicks a suggestion in the UI.

item InferResult \| string	The suggestion object or string to select.
Returns	boolean True if the selection is a final address or place.

destroy()→ void

Disposes the engine and prevents pending async work from updating state.

Functions

TypeScript

function getOrderedItems(state: InferState): InferResult[]

Returns suggestions in the order intended for display and keyboard navigation. Mixed and place responses provide the ranked order in suggestions. If that list is empty, fall back to the separate category arrays.

state InferState

TypeScript

function getHighlightSegments(text: string, query: string): HighlightSegment[]

Splits text into matched and unmatched segments for suggestion rendering.

The API matches street and city names on any substring of the accent-folded, lowercased name, so a contiguous occurrence of the folded query is looked up first and highlighted as one segment: query gebouw highlights the gebouw in Klokgebouw, and bazille highlights Bazillé even though the query carries no accent.

When the label does not contain the query verbatim (reordered multi-part queries, fuzzy matches), it falls back to a greedy in-order walk over the same folded text, placing each folded query character at its first available position, so accents fold identically on both paths. If even that fails to place every character, nothing is highlighted.

text string
query string

TypeScript

function getFuzzyHighlightSegments(text: string, query: string): HighlightSegment[]

Splits text into matched and unmatched segments for a close (fuzzy) match.

A fuzzy suggestion need not contain the query, so this highlights the longest common subsequence of the folded query and the folded label: the characters the two share in order, wherever the typo moved them. Unplaced query characters are expected and fine; a label sharing nothing with the query renders unhighlighted.

text string
query string

TypeScript

function formatLabelByInputOrder(query: string, value: AddressValue): string

Formats a label for display based on the user's input order. Components the user typed appear first (in their order), followed by components they didn't type (new info from API).

query string	The user's current query string
value AddressValue	The structured address value from the API
Returns	A formatted label string

TypeScript

function getPlaceAddress(subtitle?: string | null): string

Extracts the address from the API place subtitle.

The API subtitle is formatted as category · address; the SDK only renders the address because the place name already identifies the result.

subtitle? string | null

TypeScript

function supportsInferPlaces(country: string): boolean

Returns whether the Infer API supports place suggestions for a country. Country codes are compared case-insensitively after trimming whitespace.

country string

Constants

INITIAL_STATEInferState

The initial state of the address inference engine.

DEFAULT_STYLESstring

The CSS of the default theme for the .pro6pp-* classes.

INFER_PLACES_COUNTRIESreadonly ["NL", "BE", "DE", "FR", "AT", "ES", "DK", "LU", "IT"]

Countries currently supported by the Infer API for place suggestions.

CSS classes

18 classes

Class	Description
.pro6pp-wrapper	The container element wrapping the input and dropdown.
.pro6pp-input	The input element itself.
.pro6pp-input-addons	The container for the controls inside the input, such as the clear button.
.pro6pp-clear-button	The button that clears the input.
.pro6pp-dropdown	The panel containing the suggestion list and the loader.
.pro6pp-list	The `<ul>` list containing the suggestions.
.pro6pp-item	A single suggestion item (`<li>`).
.pro6pp-item--active	The currently highlighted item (for keyboard navigation).
.pro6pp-item__label	The main text/label of a suggestion.
.pro6pp-item--place	An item for a point of interest rather than an address.
.pro6pp-item__label--match	The part of a label that matches the query.
.pro6pp-item--fuzzy	An item for a close match rather than an exact one.
.pro6pp-item__label--unmatched	The rest of the label.
.pro6pp-item__subtitle	The secondary text (e.g., city or result count).
.pro6pp-item__chevron	The icon indicating a folder/expandable result.
.pro6pp-no-results	The message shown while searching or when no suggestions are found.
.pro6pp-loader-item	The element containing the loading spinner and text.
.pro6pp-mini-spinner	The spinner icon inside the loader item.

Types

AddressSuggestioninterface

A regular address or partial-address suggestion.

labelstringRequired

The text to display in the UI (e.g. "Main Street").

subtitlestring | null

Secondary information (e.g. city name when suggesting a street).

countnumber | string

Number of underlying results found for this suggestion.

exactboolean

False for close (fuzzy) matches that top up the exact matches.

matched_valuestring | null

The lowercase name the fuzzy pass matched, for close matches.

diff_positionsnumber[] | null

0-based query positions that differ from the match, for close matches.

valueAddressValue | string

The actual address data, when this result completes an address.

type'address'

Address suggestions may omit this field, as in existing API responses.

AddressValueinterface

The standardized address object returned upon a successful final selection.

streetstringRequired

The name of the street.

citystringRequired

The name of the city/locality.

latnumber | null

Latitude of the address location.

lngnumber | null

Longitude of the address location.

street_numberstring | number

The street number.

postcodestring

The postal code.

additionstring | null

The street number addition or suffix.

[key: string]unknown

Allow for extra fields if API expands.

CountryCodetype

Supported ISO 3166-1 alpha-2 country codes.

TypeScript

type CountryCode = 'NL'
  | 'DE'
  | 'BE'
  | 'AT'
  | 'DK'
  | 'CH'
  | 'LU'
  | 'FR'
  | 'ES'
  | 'GB'
  | 'IT'
  | (string & {});

Fetchertype

Custom fetch implementation, compatible with the Web Fetch API.

Custom fetch implementation, compatible with the Web Fetch API. Useful for Node.js environments or proxying requests.

TypeScript

type Fetcher = (input: RequestInfo
  | URL, init?: RequestInit) => Promise<Response>;

HighlightSegmentinterface

Represents a segment of text that should be highlighted or left plain.

textstringRequired

The text of the segment.

matchbooleanRequired

True if the segment matches the query.

InferConfiginterface

Configuration options for the Infer engine.

authKeystring

Your Pro6PP Authorization Key. Optional if using a proxy.

countryCountryCodeRequired

The country to perform address lookups in.

apiUrlstring

If provided, this URL is used as the API endpoint. The query params are appended, including country in lowercase.

If not provided, the SDK defaults to 'https://api.pro6pp.nl/v2/infer/{country}'.

fetcherFetcher

Custom fetch implementation for network requests.

Default: globalThis.fetch

limitnumber

Number of suggestions to request per batch, at most 1000. 0 uses the default.

Default: 20

debounceMsnumber

The delay in milliseconds before performing the API search. Note: A lower bound of 50ms is enforced to protect API stability.

Default: 150

maxRetriesnumber

Maximum number of retry attempts after a network error or a 5xx or 429 response. Valid range: 0 to 10.

Default: 0

languageLanguageCode

Language code for response labels. Affects the language of returned address labels. Only applicable for BE country code.

sortSortOrder

Default: 'relevance'

latnumber

Latitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lng must also be provided.

lngnumber

Longitude of the origin used for distance sorting, sent only when sort is 'distance'. When provided, lat must also be provided.

typesInferTypes

Suggestion types to request. Omit this to preserve the address-only default.

onStateChange(state: InferState) => void

Callback triggered whenever the internal state (suggestions, loading status, etc.) updates.

onSelect(selection: AddressValue | string | null) => void

onPlaceSelect(selection: PlaceValue | null) => void

Callback triggered when a point of interest is selected, or with null when the user edits the selected place or selects an address instead.

InferPlacesCountryCodetype

TypeScript

type InferPlacesCountryCode = (typeof INFER_PLACES_COUNTRIES)[number];

InferResulttype

A single item in the suggestion list.

TypeScript

type InferResult = AddressSuggestion
  | PlaceSuggestion;

InferStateinterface

The complete UI state managed by InferCore.

querystringRequired

The current text value of the search input.

stageStage | nullRequired

The current logical stage of the address lookup.

citiesInferResult[]Required

List of city suggestions (used in mixed stage).

streetsInferResult[]Required

List of street suggestions (used in mixed stage).

suggestionsInferResult[]Required

General list of suggestions for the current stage.

placesPlaceSuggestion[]Required

Place suggestions: the separate places list of the API response, or otherwise the place suggestions in suggestions.

isValidbooleanRequired

Flag indicating if the current selection is complete and valid.

valueAddressValue | nullRequired

The selected address value, otherwise null (places use selectedPlace).

selectedPlacePlaceValue | nullRequired

The selected place object, otherwise null.

isErrorbooleanRequired

Flag indicating if the last API request failed.

isLoadingbooleanRequired

Flag indicating if a network request is currently in progress.

hasMorebooleanRequired

Flag indicating if more results are available to load.

selectedSuggestionIndexnumberRequired

The index of the currently highlighted suggestion.

0 to n: An item is highlighted via keyboard navigation.
-1: No item is highlighted.

InferTypestype

The kinds of suggestions requested from the Infer API.

When omitted, the API keeps its address-only default.

TypeScript

type InferTypes = 'address'
  | 'place'
  | 'address,place';

LanguageCodetype

Supported language codes for address labels.

TypeScript

type LanguageCode = 'nl'
  | 'fr'
  | 'de'
  | (string & {});

PlaceSuggestioninterface

A suggestion that represents a point of interest rather than an address.

labelstringRequired

The text to display in the UI (e.g. "Main Street").

subtitlestring | null

Secondary information (e.g. city name when suggesting a street).

countnumber | string

Number of underlying results found for this suggestion.

exactboolean

False for close (fuzzy) matches that top up the exact matches.

matched_valuestring | null

The lowercase name the fuzzy pass matched, for close matches.

diff_positionsnumber[] | null

0-based query positions that differ from the match, for close matches.

type'place'Required

Marks the suggestion as a point of interest.

valuePlaceValueRequired

The place data.

PlaceValueinterface

A point of interest returned by the Infer API.

place_idstringRequired

Stable identifier of the place in the source dataset.

namestringRequired

Display name of the place.

categorystringRequired

Primary place category.

formatted_addressstring | nullRequired

Human-readable address, when available.

streetstring | nullRequired

Street name, when available.

street_numbernumber | nullRequired

Street number, when available.

additionstring | nullRequired

Street number addition, when available.

postcodestring | nullRequired

Postal code, when available.

citystring | nullRequired

City name, when available.

latnumberRequired

Latitude of the place.

lngnumberRequired

Longitude of the place.

SortOrdertype

The ordering applied to mixed address and place suggestions.

TypeScript

type SortOrder = 'relevance'
  | 'distance';

Stagetype

The current step in the address inference process.

empty: No input yet.
mixed: User is prompted to choose between cities and streets.
place: User is selecting a point of interest.
street: User is selecting a street.
city: User is selecting a city.
postcode: User is entering a postcode.
street_number: User is entering a street number.
street_number_first: Specialized mode where number is entered before street.
addition: Selecting a street number addition (e.g., 'A', 'III').
direct: Direct address hit (often via postcode).
final: A complete, valid address has been identified.

TypeScript

type Stage = 'empty'
  | 'mixed'
  | 'place'
  | 'street'
  | 'city'
  | 'postcode'
  | 'street_number'
  | 'street_number_first'
  | 'addition'
  | 'direct'
  | 'final';