Client vs. Server Mode

The Geophrase SDK supports two modes that determine how the Request ID is resolved into an address. The user experience is identical in both; the difference is entirely architectural.

How Each Mode Works

Client Mode (Default)

The SDK resolves the Request ID directly from the browser using your API key and returns the full address to your onSuccess callback.

Client Mode Flow

1. User confirms address in the widget.
2. Widget passes the Request ID to the SDK.
3. SDK calls the Resolve endpoint using your key.
4. onSuccess is called with the full address object.

Use this if you don't have a backend, or want the fastest possible integration.

const geo = new Geophrase({
    keyId: 'YOUR_API_KEY_ID',  // required in both modes
    mode: 'client',            // default, can be omitted
    key: 'YOUR_API_KEY',       // secret key, required in client mode
    onSuccess: (address) => console.log(address)
});

Server Mode

The SDK halts after receiving the Request ID and hands it directly to your onSuccess callback. Your frontend forwards it to your backend, which exchanges it for the full address using your API key.

Server Mode Flow

1. User confirms address in the widget.
2. Widget passes the Request ID to the SDK.
3. onSuccess is called with something like { requestId: "d098dc34-8995-4c07-b10c-1abcade94651" }.
4. Your frontend POSTs the Request ID to your backend.
5. Your backend calls the Resolve endpoint using your key.
6. Full address is returned to your backend.

Use this if you have a backend and want your API key entirely off the frontend. Server mode also lets you defer the paid resolve call. You can store the Request ID and only exchange it once the order is actually placed (e.g. after payment succeeds, or once COD is confirmed). See Deferring the resolve call.

const geo = new Geophrase({
    keyId: 'YOUR_API_KEY_ID',  // required in both modes
    mode: 'server',            // secret key stays on your backend
    onSuccess: ({ requestId }) => {
        fetch('/api/resolve-address', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ requestId })
        });
    }
});

Which Should I Use?

Server mode with server IP whitelisting in the dashboard is the most secure configuration. Only requests from your own backend server can use the key, making it effectively impossible to misuse even if intercepted.

Next step

HTML / Vanilla JS