gistda-sphere-react

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

OptionTypeDefaultDescription
locale"th" | "en"provider's language, else "th"Default language of results.
timeoutnumber15000Milliseconds before a request fails with a "timeout" error.
method"auto" | "get" | "post""auto"How requests are sent. See the web services overview.
baseUrlstringhttps://api.sphere.gistda.or.th/servicesService URL, e.g. a proxy.
fetchtypeof fetchglobal fetchYour own fetch implementation.
headersRecord<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.

On this page