gistda-sphere-react

useSearch

Search places, autocomplete, find nearby POIs and look up addresses

useSearch searches Sphere's place data through the map. It works inside SphereMap and anywhere else under SphereProvider. To search without a map, or on a server, use useSphereServices.

import { type PoiResult, useSearch } from "gistda-sphere-react";
import { type FormEvent, useState } from "react";

function PlaceSearch() {
  const { search, isReady } = useSearch();
  const [keyword, setKeyword] = useState("");
  const [places, setPlaces] = useState<PoiResult[]>([]);

  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const { data } = await search(keyword, { limit: 10 });
    setPlaces(data);
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        aria-label="Search places"
        onChange={(event) => setKeyword(event.target.value)}
        value={keyword}
      />
      <button disabled={!isReady} type="submit">
        Search
      </button>
      <ul>
        {places.map((place) => (
          <li key={place.id}>{place.name}</li>
        ))}
      </ul>
    </form>
  );
}

Return value

MethodReturnsDescription
search(keyword, options?)Promise<{ data: PoiResult[], meta }>Places matching a keyword.
suggest(keyword, options?)Promise<{ data: SuggestResult[], meta }>Autocomplete suggestions for a partial keyword.
nearPoi(location, options?)Promise<PoiResult[]>Places near a location.
address(location, options?)Promise<AddressResult | null>The address at a location, or null (see below).
clear()Clear results shown by SearchResults.
enablePopup(state) / isPopupEnabled()Popups for result markers.
setPlaceholder(element, options?)Render Sphere's result list into an element. <SearchResults> does this for you.
setLanguage(language) / getLanguage()Language of results.
isReadybooleantrue once the map is ready.

search, suggest and nearPoi throw if the service returns nothing, with a message that names the service, so wrap calls in try/catch.

Options

search optionDescription
limit, offsetPaging.
spanSearch radius with a unit, e.g. "5km", "500m".
tagOnly places with this tag, e.g. "โรงพยาบาล".
areaOnly places in this area code, e.g. "10" for Bangkok.
datasetDataset to search.

suggest takes limit, offset, area and dataset. nearPoi takes limit, span (degrees) and zoom.

Results

Each PoiResult has id, name, lat, lon and, when available, address, tel, url, tag (a list of tags), distance and more. The id also works with <ObjectOverlay> to draw the place's outline.

Language

Results follow the map's language, which defaults to Thai, so an English keyword can still return Thai names. Set language on SphereProvider or SphereMap for English results, or call setLanguage to change only the search language.

Autocomplete

useSuggest gives suggestions as users type. It waits for typing to pause and ignores responses for older keywords:

import { useSuggest } from "gistda-sphere-react";
import { useState } from "react";

function SearchBox() {
  const [keyword, setKeyword] = useState("");
  const { suggestions } = useSuggest(keyword, { limit: 5 });

  return (
    <>
      <input
        aria-label="Search places"
        onChange={(event) => setKeyword(event.target.value)}
        value={keyword}
      />
      <ul>
        {suggestions.map((suggestion, index) => (
          <li key={`${suggestion.name}:${index}`}>{suggestion.name}</li>
        ))}
      </ul>
    </>
  );
}

If you call suggest yourself, wait for typing to pause and drop responses for older keywords, or a slow response can replace newer suggestions.

Addresses

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

const { address } = useSearch();

async function logAddress() {
  const result = await address({ lon: 100.5018, lat: 13.7563 });
  if (result) {
    console.log(result.province, result.district, result.subdistrict, result.road);
  }
}

address resolves null when there's no address at the location, and also when your API key doesn't have the address service. Search, suggestions and nearby places use other services, so they can work while addresses don't.

On this page