How Geophrase Works

Geophrase Connect is the developer integration for the GPS Address Capture service. Its SDKs and Vanilla JavaScript library open the Connect Widget, which collects a GPS-pinned delivery address after verifying the customer's mobile number by OTP. It returns structured data together with a QR code and short link that can route a rider to the location.

These docs cover the Geophrase SDKs, Vanilla JavaScript library, integration modes, Resolve endpoint, and response objects. Dashboard workflows such as order and delivery management are intentionally not documented here.

Under the hood, the SDK securely bridges your UI and our mapping API. It handles GPS mapping, address parsing, and OTP verification out of the box, saving you from managing heavy mapping dependencies or building authentication flows.

The Data Flow Lifecycle

Whether you use Vanilla JS, React, or Flutter, the Geophrase architecture follows a simple, sandboxed lifecycle:

1. Initialization & Trigger

The user triggers the flow (e.g., clicking your "Add Address" button). The SDK mounts the Connect Widget as a modal over your application. The heavy mapping dependencies load entirely inside this isolated widget, protecting your app's bundle size and performance.

2. Capture & Verification

Inside the sandboxed widget:

• State Management: GPS permissions and map UI interactions are handled automatically.
• Authentication: Phone numbers are verified strictly via SMS OTP. Returning users bypass OTP for 1-click selection, while new users complete the full verification loop.

3. Secure Request ID Handoff

Upon confirmation, the widget does not pass raw geographic data directly to the host environment. Instead, it generates a short-lived Request ID (a UUID4) and passes it back to the SDK.

4. Resolution (Client vs. Server)

How this Request ID is resolved into an actual address depends on the mode you configure in the SDK:

• Client Mode (Default): The SDK exchanges the Request ID with the Geophrase backend, which validates your API key and returns the final structured JSON Address payload directly to your frontend application. (Zero backend integration required).
• Server Mode: The SDK safely halts and hands the Request ID to your frontend. You then pass it to your own backend server, which exchanges it for the Address payload using your API key. (Maximum security, and lets you defer the paid call until the order is actually placed.)

Why This Architecture?

• Bundle Optimization: By sandboxing the mapping engines inside our widget, your application avoids the heavy bundle cost of installing mapping SDKs directly.
• Data Integrity: The final payload is constructed and sanitized exclusively by the Geophrase backend, eliminating malformed inputs and unstructured strings before they ever reach your database.
• Flexible Security: You can choose between frictionless frontend resolution (client mode) or maximum-security backend resolution (server mode) without changing the user experience.

Next step

Quick Start