KukiGuide Address Picker

Let your customers pick a Rarotonga address from a map — and have it land straight in your form.

What it does

KukiGuide gives every place on Rarotonga a radial-grid address (e.g. 934 Katai Blk). The address picker embeds that map on your site inside an <iframe>, inline in the page. A customer searches or taps a location and your page receives the resolved address, its permanent block code, and latitude/longitude.

Integration is one script tag and one function call. The picker is served from kuki.guide, so map imagery and the address engine always stay current — you never ship an update.

Live demo

Two ways to use the picker — embedded inline in a page, or opened in a popup from a button.

Inline

A mock delivery-order form with the picker embedded directly. Tap the map or search — the preview line updates on every change; the address field is filled when you press Use this address.

Popup

The picker opened in a modal from a Find Address button — mounted when the popup opens, destroyed when it closes.

Delivery address

Quick start

Integration is one script tag and one mount() call. Pick the pattern that matches the demo above — inline embeds the picker in the page; popup opens it from a button.

Inline

Add a container, the loader script, and a mount() call:

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

<script src="https://kuki.guide/embed.js"></script>
<script>
  KukiPicker.mount('#address-picker', {
    // Fires on every map click / search selection.
    onChange: function (addr) {
      console.log('previewing', addr.address);
    },
    // Fires when the customer presses "Use this address".
    onSelect: function (addr) {
      document.getElementById('address').value = addr.address;
      document.getElementById('block-code').value = addr.code;
    }
  });
</script>

The picker renders inline, filling its container.

Popup

Mount the picker when the popup opens; destroy() it when the popup closes:

<input id="address" readonly>
<button id="find-address">Find Address</button>

<div id="picker-modal" hidden>
  <div id="modal-picker"></div>
  <button id="modal-close">Close</button>
</div>

<script src="https://kuki.guide/embed.js"></script>
<script>
  var modal = document.getElementById('picker-modal');
  var picker = null;

  document.getElementById('find-address').onclick = function () {
    modal.hidden = false;
    picker = KukiPicker.mount('#modal-picker', {
      onSelect: function (addr) {
        document.getElementById('address').value = addr.address;
        closeModal();
      }
    });
  };

  function closeModal() {
    if (picker) { picker.destroy(); picker = null; }
    modal.hidden = true;
  }
  document.getElementById('modal-close').onclick = closeModal;
</script>

Mounting on open (rather than once at page load) keeps the map off the network until the customer actually needs it.

API reference

KukiPicker.mount(target, options)

Builds the picker iframe inside target (a CSS selector or DOM element) and returns a handle.

Option	Type	Description
`onSelect`	function	Called with the payload below when the customer presses "Use this address".
`onChange`	function	Called with the same payload on every map click / search selection — i.e. live, before any confirm.
`address`	string	Pre-select by address string, e.g. `"1008 Katai"`.
`code`	string	Pre-select by permanent block code, e.g. `"1008ka1m"`.
`level`	0–3	Sub-block precision for map taps. 0 = block (~25 m), 1 = ~5 m, 2 = ~1 m. Default 1.
`geolocate`	boolean	Show a "my location" button inside the picker. Default off.
`levelToggle`	boolean	Show the L0 / L1 / L2 badge that lets the customer change sub-block precision. Default on — pass `false` to hide it and lock precision to `level`.
`width`	number\|string	Iframe width. Number → px. Default `'100%'`.
`height`	number\|string	Iframe height. Number → px. Default `480`.

Handle

mount() returns { iframe, destroy }. iframe is the created element; destroy() removes it and detaches the message listener — call it when you unmount the picker (e.g. closing a modal).

Callback payload

onChange and onSelect receive the same object. The type field distinguishes a live change (kuki:change) from a confirmed selection (kuki:address).

Field	Type	Example
`type`	string	`"kuki:change"` or `"kuki:address"`
`version`	number	`1`
`address`	string	`"934 Katai Blk"`
`code`	string	`"934ka1"`
`url`	string	`"https://kuki.guide/934ka1"`
`lat`	number	`-21.2345`
`lng`	number	`-159.7788`
`subBlockLevel`	number	`1`

Tips

Live vs confirmed. Use onChange to preview the selection as the customer explores; use onSelect to commit it when they confirm.
Editing an existing order? Pass code (or address) to open the picker with that location already selected.
Need finer precision? Raise level — handy for marking a gate or meter rather than a whole block.
Sizing. The picker needs room for a map, a search bar and a footer button — keep height at 420 px or more.
Security. The loader only accepts messages from kuki.guide, so a forged postMessage from another origin is ignored. The payload is not secret — it is the same data a public kuki.guide link already exposes.
One script, always current. Pin to https://kuki.guide/embed.js; map and engine updates ship behind it.

Register your integration

Planning to embed the picker on a live site? Please email map@kuki.guide with the site's address. The picker is new and still evolving, so registering lets us:

give you advance notice of any breaking change to embed.js or the message format;
keep your integration working through map-tile API-key changes — including any future allowlisting of approved embedding domains.

It is a courtesy notice - the picker works without it today.

Questions

See kuki.guide or email map@kuki.guide.