Getting an API key
Get a GISTDA Sphere API key, restrict it to your sites, and enable the services you use
Steps
- Go to sphere.gistda.or.th and create an account.
- Create an API key.
- Add the hosts (domains) where your app runs.
- 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:
| Host | Purpose |
|---|---|
localhost | Local development |
example.com | Production |
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:
| Feature | Service | Symptom when missing |
|---|---|---|
| The map, markers, shapes, layers | Map | The map stays empty. |
useSearch search and suggestions, <Tag> | Search, POI | Errors from search/suggest, empty tag layers. |
useSearch().address, right-click menu address | Address (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 services | The matching service | SphereServiceError with code "key". |
| Static maps | Static map | The 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_PUBLIC_SPHERE_API_KEY=your_api_keyimport { SphereProvider } from "gistda-sphere-react";
<SphereProvider apiKey={process.env.NEXT_PUBLIC_SPHERE_API_KEY!}>VITE_SPHERE_API_KEY=your_api_keyimport { 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.