Quick Start

This guide takes you from zero to a working Geophrase integration.

Want to see the end result first? The live demo at demo.geophrase.com shows the Connect Widget in action.

1. Get Your API Key

Sign up for a Geophrase Account.
Navigate to your dashboard and generate a new API key. Every integration needs its Key ID (the public prefix, shown in the dashboard); client mode also needs the secret key. See API Keys & Security.

2. Drop in the UI Component

Choose the framework that matches your stack.

Option A: Vanilla JavaScript (HTML)

Include the CDN script in your <head> and bind it to your action button.

<!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="address-display"></pre>

<script src="https://connect.geophrase.com/v1/geophrase.js"></script>
<script>
  const geo = new Geophrase({
    keyId: 'YOUR_API_KEY_ID',
    key: 'YOUR_API_KEY',
    orderId: 'ORD-8786', // Optional
    phone: '9999999999', // Optional; prefills the phone field

    onSuccess: function(address) {
      document.getElementById('address-display').textContent = JSON.stringify(address, 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>

Full Vanilla JS documentation

Option B: React / Next.js

npm install @geophrase/react

import { useState } from 'react';
import { useGeophrase } from '@geophrase/react';

function Checkout() {
  const [result, setResult] = useState(null);

  const { open } = useGeophrase({
    keyId: 'YOUR_API_KEY_ID',
    key: 'YOUR_API_KEY',
    orderId: 'ORD-98765', // Optional
    phone: '9999999999',  // Optional; prefills the phone field
    onSuccess: (address) => setResult(address),
    onError:   (error)   => console.error("Error:", error.message),
    onClose:   ()        => console.log("User closed the widget.")
  });

  return (
    <div>
      <button onClick={open}>Select Delivery Location</button>
      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
    </div>
  );
}

export default Checkout;

Full React documentation · Full Next.js documentation

Option C: React Native

npm install @geophrase/react-native react-native-webview react-native-device-info @react-native-community/geolocation

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import { GeophraseConnect } from '@geophrase/react-native';

export default function MobileCheckout() {
  const [visible, setVisible] = useState(false);
  const [result, setResult] = useState(null);

  return (
    <View>
      <Button title="Select Delivery Location" onPress={() => setVisible(true)} />

      <GeophraseConnect
        visible={visible}
        apiKeyId="YOUR_API_KEY_ID" // required in both modes; your public Key ID
        mode="server"             // server mode needs no secret key; see Full React Native documentation below
        theme="system"            // 'light' | 'dark' | 'system'
        orderId="ORD-98765"       // Optional
        phone="9999999999"        // Optional; prefills the phone field
        onSuccess={(result) => { setResult(result); setVisible(false); }}
        onError={(error) => console.error('Geophrase error:', error.message)}
        onClose={() => setVisible(false)}
      />
    </View>
  );
}

Full React Native documentation

Option D: Flutter

flutter pub add geophrase_flutter

import 'package:flutter/material.dart';
import 'package:geophrase_flutter/geophrase_flutter.dart';

void openGeophrase(BuildContext context) {
  Navigator.of(context).push(
    MaterialPageRoute(
      fullscreenDialog: true,
      builder: (routeContext) => GeophraseConnect(
        apiKeyId: 'YOUR_API_KEY_ID', // required in both modes; your public Key ID
        mode: 'server',           // server mode needs no secret key; see Full Flutter documentation below
        theme: 'system',          // 'light' | 'dark' | 'system'
        orderId: 'ORD-98765',     // Optional
        phone: '9999999999',      // Optional; prefills the phone field
        onSuccess: (result) {
          Navigator.of(routeContext).pop();
          if (result is GeophraseRequestId) debugPrint('Request ID: ${result.requestId}');
          if (result is GeophraseAddress) debugPrint('Address: ${result.shortCode}');
        },
        onError: (error) => debugPrint('Geophrase error: ${error.message}'),
        onClose: () => Navigator.of(routeContext).pop(),
      ),
    ),
  );
}

Full Flutter documentation

Next step

Client vs. Server Mode