gistda-sphere-react

Getting an API key

Get a GISTDA Sphere API key, restrict it to your sites, and enable the services you use

Steps

  1. Go to sphere.gistda.or.th and create an account.
  2. Create an API key.
  3. Add the hosts (domains) where your app runs.
  4. Enable the services your app uses (see below).

Allowed hosts

The key is sent with every request and is visible in the browser, so the host list is what protects it. Add every place your app runs:

HostPurpose
localhostLocal development
example.comProduction

If the map works on one local port but not another (for example localhost:3000 but not localhost:5173), check whether the host entry includes a port.

Services

Each Sphere service has to be enabled for your key. When one isn't, Sphere usually doesn't report a clear error, so features just seem not to work. This table shows what each feature needs:

FeatureServiceSymptom when missing
The map, markers, shapes, layersMapThe map stays empty.
useSearch search and suggestions, <Tag>Search, POIErrors from search/suggest, empty tag layers.
useSearch().address, right-click menu addressAddress (reverse geocoding)address() resolves null.
<ObjectOverlay>POI details (poi/get)Nothing is drawn, and onError fires after the timeout.
useRoute, <RouteGuide>Routing"timeout" error after 20 seconds. Fly mode still works.
Web servicesThe matching serviceSphereServiceError with code "key".
Static mapsStatic mapThe image doesn't load.

Using the key

Pass the key to SphereProvider:

import { SphereProvider } from "gistda-sphere-react";

<SphereProvider apiKey="YOUR_API_KEY">
  <App />
</SphereProvider>

Keep it in an environment variable, so it stays out of source control.

Next.js: .env.local
NEXT_PUBLIC_SPHERE_API_KEY=your_api_key
import { SphereProvider } from "gistda-sphere-react";

<SphereProvider apiKey={process.env.NEXT_PUBLIC_SPHERE_API_KEY!}>
Vite: .env
VITE_SPHERE_API_KEY=your_api_key
import { SphereProvider } from "gistda-sphere-react";

<SphereProvider apiKey={import.meta.env.VITE_SPHERE_API_KEY}>

Environment variables prefixed for the browser (NEXT_PUBLIC_, VITE_) still end up in your JavaScript. Host restrictions are what keep the key safe. For server-side calls with createSphereServices, use a separate key without the browser prefix. Servers don't send the host that Sphere checks, so a host-restricted key also needs the referer option there.

On this page