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
| Method | Returns | Description |
|---|---|---|
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. | |
isReady | boolean | true 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 option | Description |
|---|---|
limit, offset | Paging. |
span | Search radius with a unit, e.g. "5km", "500m". |
tag | Only places with this tag, e.g. "โรงพยาบาล". |
area | Only places in this area code, e.g. "10" for Bangkok. |
dataset | Dataset 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.