useSphereServices
A typed client for Sphere's REST web services, using the provider's API key
useSphereServices returns the web services client set up with your SphereProvider API key. Use it for routing, geocoding, elevation, static maps, agriculture, disaster and population data. No map is needed.
Each button calls a Sphere web service around Victory Monument.
import { type Location, SphereServiceError, useSphereServices } from "gistda-sphere-react";
import { useEffect, useState } from "react";
function Elevation({ location }: { location: Location }) {
const services = useSphereServices({ locale: "en" });
const [meters, setMeters] = useState<number | null>(null);
useEffect(() => {
const controller = new AbortController();
services.geo
.elevation(location, { signal: controller.signal })
.then((points) => setMeters(points[0]?.elevation ?? null))
.catch((error) => {
if (error instanceof SphereServiceError && error.code === "key") {
console.warn("Enable the elevation service for this API key.");
}
});
return () => controller.abort();
}, [services, location]);
return <span>{meters === null ? "…" : `${meters} m`}</span>;
}Options
| Option | Type | Default | Description |
|---|---|---|---|
locale | "th" | "en" | provider's language, else "th" | Default language of results. |
timeout | number | 15000 | Milliseconds before a request fails with a "timeout" error. |
method | "auto" | "get" | "post" | "auto" | How requests are sent. See the web services overview. |
baseUrl | string | https://api.sphere.gistda.or.th/services | Service URL, e.g. a proxy. |
fetch | typeof fetch | global fetch | Your own fetch implementation. |
headers | Record<string, string> | – | Extra headers for every request, such as for your own proxy. |
The client is memoized: it only changes when the options do.
Without React
Outside React, or on a server, create the same client with createSphereServices. Import it from gistda-sphere-react/services to leave out React and the map code:
import { createSphereServices } from "gistda-sphere-react/services";
const services = createSphereServices({ apiKey: process.env.SPHERE_API_KEY! });
const { data } = await services.search.search("โรงพยาบาล", { limit: 5 });On a server, a key limited to certain domains also needs the referer option. See On a server, and Web services for every service, error handling and examples.