HTML / Vanilla JS Integration

The fastest way to integrate Geophrase into a web page. No build step or bundler is needed. Include the CDN script and initialize the widget.

Ideal for traditional web applications, static sites, and platforms that let you add custom JavaScript. This library is not a one-click Shopify or WooCommerce plugin.

Prerequisites

Create a Geophrase Account.
Generate an API Key from the Dashboard.

1. Include the SDK

Place the script tag at the bottom of <body>, just before your inline script. This guarantees Geophrase is defined before your code runs.

<script src="https://connect.geophrase.com/v1/geophrase.js"></script>

2. Initialize and Open

Create a Geophrase instance and bind .open() to your button.

<button id="geophrase-btn">Select Delivery Location</button>

<script src="https://connect.geophrase.com/v1/geophrase.js"></script>
<script>
  const geo = new Geophrase({
    keyId: 'YOUR_API_KEY_ID', // required in every mode
    mode: 'server',           // server mode needs no secret key; the widget returns a requestId your backend exchanges for the address
    onSuccess: function(result) {
      console.log(result); // { requestId: "..." }
    }
  });

  document.getElementById('geophrase-btn').onclick = function(e) {
    e.preventDefault();
    geo.open();
  };
</script>

Complete Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Title</title>
</head>
<body>

<button id="geophrase-btn">Select Delivery Location</button>
<pre id="result-display"></pre>

<script src="https://connect.geophrase.com/v1/geophrase.js"></script>
<script>
  const geo = new Geophrase({
    keyId: 'YOUR_API_KEY_ID',  // required in every mode; your public Key ID

    // --- MODE ---
    // 'server' (used here): widget returns a short-lived requestId. Pass it to your backend to resolve the address. No secret key in the frontend.
    // 'client' (default):   widget resolves and returns the full address directly. Requires 'key'.
    mode: 'server',

    // key: 'YOUR_API_KEY', // secret key, required when mode is 'client'

    // --- OPTIONAL ---
    theme: 'system',       // 'light' | 'dark' | 'system'
    orderId: 'ORD-8786',   // your internal reference ID
    phone: '9999999999',   // prefills the phone field

    // --- CALLBACKS ---
    onSuccess: function(result) {
      // server mode → result is { requestId: "..." }. POST this to your backend.
      // client mode → result is the full address object.
      document.getElementById('result-display').textContent = JSON.stringify(result, null, 2);
    },
    onError: function(error) {
      console.error("Geophrase error:", error.message);
    },
    onClose: function() {
      console.log("User closed the widget.");
    }
  });

  document.getElementById('geophrase-btn').onclick = function(e) {
    e.preventDefault();
    geo.open();
  };
</script>

</body>
</html>

Configuration Options

Parameter	Type	Default	Required	Description
`keyId`	`string`	-	Yes	Your Key ID, the public prefix of your API key shown in the dashboard. Required in both modes; it tells the widget which account the request belongs to.
`mode`	`string`	`'client'`	No	`'client'` resolves the address in the browser and returns the full address object. `'server'` returns a short-lived `requestId` for your backend to exchange. See Client vs. Server Mode.
`key`	`string`	-	Conditional	Your secret Geophrase API key (the full key string). Required when `mode` is `'client'`. Omit in server mode.
`theme`	`string`	`'system'`	No	Widget theme. `'light'`, `'dark'`, or `'system'` (follows the OS preference).
`orderId`	`string`	-	No	Your internal reference ID. In client mode it is forwarded to the Resolve endpoint and stored against the captured address; in server mode you forward it yourself. Echoed back in the dashboard.
`noteForAgent`	`string`	-	No	Note shown to your delivery agent, never to the customer. Client mode only; notes over 300 characters are cut. It is sent from the customer's device, so the customer can change it; send payment instructions, such as cash to collect, from your server or the dashboard. In server mode, send `note_for_agent` with your resolve call.
`phone`	`string`	-	No	The customer's 10-digit phone number. Pre-fills the phone field in the widget.
`onSuccess`	`function`	-	Yes	Called on completion. Receives an Address Object in client mode, or `{ requestId }` in server mode.
`onError`	`function`	-	No	Called on API or network errors. Receives `{ type, status?, message }`.
`onClose`	`function`	-	No	Called when the user closes the widget without selecting an address.

Next step

React