AddressDesk Documentation

Overview

AddressDesk provides two integration methods. Use the REST API when you want complete control over your user interface and HTTP requests. Use the JavaScript SDK when you want to attach autocomplete to an existing input or mount a complete address form into a page.

Quick start

Set the API base URL and API key for your environment. The examples use shell variables so that credentials do not need to be embedded directly in every command.

API_BASE="http://localhost:8000"
ADDRESSDESK_API_KEY="YOUR_API_KEY"

curl -G "$API_BASE/v1/addresses/suggest" \
  --data-urlencode "q=mar" \
  --data-urlencode "country=DE" \
  --data-urlencode "limit=6" \
  -H "Accept: application/json" \
  -H "X-API-Key: $ADDRESSDESK_API_KEY"

curl -X POST "$API_BASE/v1/addresses/validate" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADDRESSDESK_API_KEY" \
  -d '{
    "street": "Marienplatz",
    "house_number": "1",
    "postal_code": "80331",
    "city": "München",
    "region": "Bayern",
    "country_code": "DE"
  }'

Authentication

AddressDesk SDK requests send the API key using the X-API-Key request header. REST API calls should use the same header.

X-API-Key: YOUR_API_KEY
Accept: application/json

The SDK adds Accept: application/json and X-API-Key automatically. Validation requests that use a JSON body also set Content-Type: application/json.

Address suggestions

Returns address suggestions for the supplied query. The JavaScript SDK requests this endpoint when the configured input reaches the minimum character count.

Query parameters

Request

curl -G "$API_BASE/v1/addresses/suggest" \
  --data-urlencode "q=mar" \
  --data-urlencode "country=DE" \
  --data-urlencode "limit=6" \
  -H "Accept: application/json" \
  -H "X-API-Key: $ADDRESSDESK_API_KEY"

JavaScript request

const params = new URLSearchParams({
  q: 'mar',
  country: 'DE',
  limit: '6'
});

const response = await fetch(
  API_BASE + '/v1/addresses/suggest?' + params,
  {
    headers: {
      Accept: 'application/json',
      'X-API-Key': API_KEY
    }
  }
);

if (!response.ok) {
  throw new Error('Request failed: ' + response.status);
}

const payload = await response.json();
const addresses = payload.results || [];

console.log(addresses);

Address suggestion fields

The SDK reads an array from payload.results. Each result should provide the fields needed by your UI and any configured form field mappings.

{
  "results": [
    {
      "id": "address-record-id",
      "label": "Marienplatz 1, 80331 München, Germany",
      "street": "Marienplatz",
      "house_number": "1",
      "postal_code": "80331",
      "city": "München",
      "region": "Bayern",
      "country_code": "DE"
    }
  ]
}

The sample response illustrates the fields consumed by this SDK; the exact response is determined by your running API.

Validate an address

Submit structured address data for validation. The dashboard example and the address form send a JSON object containing the address fields.

Request headers

Accept: application/json
Content-Type: application/json
X-API-Key: YOUR_API_KEY

Request body

{
  "street": "Marienplatz",
  "house_number": "1",
  "postal_code": "80331",
  "city": "München",
  "region": "Bayern",
  "country_code": "DE"
}

Request with cURL

curl -X POST "$API_BASE/v1/addresses/validate" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ADDRESSDESK_API_KEY" \
  -d '{
    "street": "Marienplatz",
    "house_number": "1",
    "postal_code": "80331",
    "city": "München",
    "region": "Bayern",
    "country_code": "DE"
  }'

Call the endpoint from JavaScript

const response = await fetch(
  API_BASE + '/v1/addresses/validate',
  {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      street: 'Marienplatz',
      house_number: '1',
      postal_code: '80331',
      city: 'München',
      region: 'Bayern',
      country_code: 'DE'
    })
  }
);

if (!response.ok) {
  throw new Error('Validation request failed: ' + response.status);
}

const result = await response.json();
console.log(result);

Response format

Your backend determines the final validation response. The dashboard UI in this project expects a status, a message, and optional check details similar to this example.

{
  "status": "matched_in_address_index",
  "message": "Address matched in the address index.",
  "missing_fields": [],
  "checks": {
    "required_fields": "passed",
    "postal_code_format": "passed",
    "address_index_match": "matched"
  },
  "postal_deliverability": "not_checked"
}

The embedded form considers a result explicitly invalid only when valid === false or is_valid === false. A response containing a different status does not automatically cause the form to reject the address. Use onInvalidAddress and your backend's response contract to implement stricter rules.

JavaScript SDK

The SDK exports two classes: AddressAutocomplete for attaching a suggestions menu to an existing input, and AddressDeskAddressForm for mounting a complete address form inside a target element.

Attach autocomplete to existing fields

HTML

Provide an input for the search query and, optionally, other inputs to receive the selected address fields.

<label for="address-search">Address</label>
<input
  id="address-search"
  type="text"
  autocomplete="off"
  placeholder="Start typing an address"
/>

<label for="street">Street</label>
<input id="street" type="text" />

<label for="house-number">House number</label>
<input id="house-number" type="text" />

<label for="postal-code">Postal code</label>
<input id="postal-code" type="text" />

<label for="city">City</label>
<input id="city" type="text" />

<label for="country-code">Country code</label>
<input id="country-code" type="text" value="DE" />

Initialize the SDK

import { AddressAutocomplete } from './addressdesk-sdk.js';

const autocomplete = AddressAutocomplete.init({
  apiKey: 'YOUR_API_KEY',
  apiUrl: 'https://your-api.example.com',
  selector: '#address-search',
  minChars: 2,
  debounceMs: 220,
  limit: 6,
  fields: {
    street: '#street',
    house_number: '#house-number',
    postal_code: '#postal-code',
    city: '#city',
    country: '#country-code'
  },
  onSelect(address) {
    console.log('Selected address:', address);
  },
  onError(error) {
    console.error('Address suggestions failed:', error);
  }
});

How it works

1. The SDK locates the input using selector or input.
2. It wraps the input and creates a suggestions menu below it.
3. After the minimum number of characters, it waits for the configured debounce interval and requests suggestions.
4. Choosing a suggestion fills the configured fields and calls onSelect.
5. The user can navigate suggestions with the keyboard or dismiss the menu with Escape.
6. Call destroy() when the input is removed or the integration is no longer needed.

Selection fields

Map SDK output keys to elements with the fields option. Each value can be a CSS selector or an element.

fields: {
  street: '#street',
  house_number: '#house-number',
  postal_code: '#postal-code',
  city: '#city',
  region: '#region',
  country_code: '#country-code'
}

The SDK also recognizes the aliases houseNumber, postalCode, country, and countryCode when mapping a selected record. If a field is not found or the record has no corresponding value, that field is left unchanged.

Country filtering

Provide a fixed country code, a function returning the current country code, or omit the country option and map fields.country to a country input.

country: 'DE'

country: () => document.querySelector('#country-code').value

When the country changes in a form, the value is read when a new suggestion request is built.

Validate with the SDK

The autocomplete instance exposes validate() and validateSelected(). These methods return a Promise that resolves with the decoded API response or rejects with an error.

Validate structured fields

const result = await autocomplete.validate(
  {
    street: document.querySelector('#street').value,
    house_number: document.querySelector('#house-number').value,
    postal_code: document.querySelector('#postal-code').value,
    city: document.querySelector('#city').value,
    country_code: document.querySelector('#country-code').value
  },
  {
    body: {
      street: document.querySelector('#street').value,
      house_number: document.querySelector('#house-number').value,
      postal_code: document.querySelector('#postal-code').value,
      city: document.querySelector('#city').value,
      country_code: document.querySelector('#country-code').value
    }
  }
);

console.log(result);

Validate the selected suggestion

const result = await autocomplete.validateSelected({
  body: {
    street: document.querySelector('#street').value,
    house_number: document.querySelector('#house-number').value,
    postal_code: document.querySelector('#postal-code').value,
    city: document.querySelector('#city').value,
    country_code: document.querySelector('#country-code').value
  }
});

Customize the validation request

The call-level options path, method, and body override the instance defaults for that request. The instance can also provide a reusable validationBody function.

const autocomplete = AddressAutocomplete.init({
  apiKey: 'YOUR_API_KEY',
  selector: '#address-search',
  validationPath: '/v1/addresses/validate',
  validationMethod: 'POST',
  validationBody(address) {
    return {
      street: address.street,
      house_number: address.house_number,
      postal_code: address.postal_code,
      city: address.city,
      country_code: address.country_code
    };
  }
});

For a GET validation method, the SDK converts the supplied body into query parameters. For other methods, it sends the body as JSON. Confirm which method and body format your server supports.

Mount a complete address form

Use AddressDeskAddressForm.mount() to render a form in an existing container. The form includes a search input, address fields, an autocomplete menu, a submit button, feedback messages, and AddressDesk branding.

HTML container

<div id="address-form"></div>

Minimal integration

Start with the required connection settings, a target element, and an onSubmit callback. The SDK supplies the form fields, autocomplete behavior, validation flow, and default labels.

import { AddressDeskAddressForm } from './addressdesk-sdk.js';

const API_KEY = 'YOUR_API_KEY';
const API_URL = 'https://your-api.example.com';

const addressForm = AddressDeskAddressForm.mount({
  apiKey: API_KEY,
  apiUrl: API_URL,
  target: '#address-form',
  buttonColor: '#5146E5',
  onSubmit(address, validationResult) {
    console.log(address);
  }
});

Complete integration example

import { AddressDeskAddressForm } from './addressdesk-sdk.js';

const addressForm = AddressDeskAddressForm.mount({
  apiKey: 'YOUR_API_KEY',
  apiUrl: 'https://your-api.example.com',
  target: '#address-form',
  country: 'DE',
  title: 'Shipping address',
  description: 'Find your address and confirm your details.',
  submitLabel: 'Continue',
  loadingLabel: 'Please wait…',
  validateOnSubmit: true,
  requireSelection: true,
  onSelect(address) {
    console.log('Address selected:', address);
  },
  onSubmit(address, validationResult) {
    console.log('Address:', address);
    console.log('Validation:', validationResult);
  },
  onInvalidAddress(result, address) {
    console.error('Address rejected:', result, address);
  },
  onError(error) {
    console.error('Form error:', error);
  }
});

Submission flow

1. When requireSelection is enabled, the user must select an item from the AddressDesk suggestions.
2. The form reads the current values and assembles a structured address object.
3. When validateOnSubmit is enabled, it sends the configured validation request.
4. If the response explicitly sets valid or is_valid to false, the form displays an error and calls onInvalidAddress.
5. Otherwise, it displays the success message and calls onSubmit(address, validationResult).
6. When validation is disabled, onSubmit receives the address and null as the validation result.

Customize the form for a German-language audience

You can localize the form by providing your own text for the title, description, field labels, button labels, and configurable status messages. Set country: 'DE' to start with Germany as the country code and filter address suggestions for Germany. The country option does not translate the interface automatically; the strings below provide the German wording.

import { AddressDeskAddressForm } from './addressdesk-sdk.js';

const API_KEY = 'YOUR_API_KEY';
const API_URL = 'https://your-api.example.com';
let addressForm = null;

try {
  addressForm = AddressDeskAddressForm.mount({
    apiKey: API_KEY,
    apiUrl: API_URL,
    target: '#address-form',
    country: 'DE',
    title: 'Lieferadresse',
    description: 'Finde deine Adresse und bestätige deine Angaben.',
    searchLabel: 'Adresse suchen',
    searchPlaceholder: 'Tippe hier, z. B. Marienplatz',
    streetLabel: 'Straße',
    houseNumberLabel: 'Hausnummer',
    postalCodeLabel: 'Postleitzahl',
    cityLabel: 'Ort',
    countryLabel: 'Ländercode',
    submitLabel: 'Weiter zur Zahlung',
    loadingLabel: 'Adresse wird überprüft…',
    selectedMessage: 'Adresse ausgewählt. Prüfe deine Angaben, bevor du fortfährst.',
    selectionRequiredMessage: 'Bitte wähle eine Adresse aus den Vorschlägen aus.',
    validatingMessage: 'Adresse wird überprüft…',
    successMessage: 'Adresse erfolgreich überprüft.',
    buttonColor: '#734234',
    minChars: 2,
    debounceMs: 250,
    limit: 6,
    validateOnSubmit: true,
    requireSelection: true,
    onSelect(address) {
      console.log('Ausgewählte Adresse:', address);
    },
    onValidation(result, address) {
      console.log('Validierungsergebnis:', result);
      console.log('Geprüfte Adresse:', address);
    },
    onInvalidAddress(result, address) {
      console.warn('Adresse ist ungültig:', result, address);
    },
    onSubmit(address, validationResult) {
      console.log('Adresse:', address);
      console.log('Validierungsergebnis:', validationResult);
    },
    onError(error) {
      console.error('AddressDesk-Fehler:', error);
    },
    onValidationError(error, address) {
      console.error('Adressvalidierung fehlgeschlagen:', error, address);
    }
  });
} catch (error) {
  console.error('AddressDesk konnte nicht initialisiert werden:', error);
}

Set title or description to false to hide the corresponding text. The buttonColor option sets the form's --addressdesk-button-color CSS custom property. The example localizes configurable labels and messages; built-in error text that has no corresponding option remains in the SDK's default language.

Configuration reference

Shared request options

Autocomplete options

Address form options

The form also accepts label and message overrides, including searchLabel, searchPlaceholder, streetLabel, houseNumberLabel, postalCodeLabel, cityLabel, countryLabel, selectedMessage, selectionRequiredMessage, validatingMessage, successMessage, and loadingLabel.

Callbacks

Use callbacks to update your application when an address is selected, validation completes, or a request fails.

const autocomplete = AddressAutocomplete.init({
  apiKey: 'YOUR_API_KEY',
  selector: '#address-search',
  onSelect(address) {
    console.log('Selected:', address);
  },
  onError(error) {
    console.error('Suggestion error:', error);
  },
  onValidation(result, address) {
    console.log('Validation result:', result);
    console.log('Validated value:', address);
  },
  onValidationError(error, address) {
    console.error('Validation failed:', error);
    console.log('Submitted value:', address);
  }
});

Lifecycle and cleanup

The SDK adds DOM elements and event listeners. Destroy an instance when its input, form container, or page section is being removed.

autocomplete.destroy();
addressForm.destroy();

AddressAutocomplete.destroy() clears its timer, aborts active requests, removes listeners, restores the original input to its previous location, and removes the SDK wrapper. AddressDeskAddressForm.destroy() destroys its autocomplete instance, removes the form submission listener, and removes the mounted form.

Errors and troubleshooting

Security and production use