Search

useSearch wraps MapKit's Search service with promise-based search and autocomplete methods plus reactive isSearching and error state. usePointsOfInterestSearch does the same for category-constrained point-of-interest lookups.

useSearch

<script setup lang="ts">
  import { VMap, VMarkerAnnotation, useSearch } from '@geoql/v-mapkit';

  const { search, autocomplete, isSearching, error } = useSearch();

  const query = ref('');
  const suggestions = shallowRef<Array<{ displayLines?: string[] }>>([]);
  const results = shallowRef<mapkit.Place[]>([]);

  // live autocomplete as the user types
  async function onInput(value: string) {
    const response = await autocomplete(value);
    suggestions.value = response.results;
  }

  // full search → place results
  async function runSearch(value: string) {
    const response = await search(value);
    results.value = response.places;
  }
</script>

<template>
  <VMap :access-token="token">
    <VMarkerAnnotation
      v-for="(place, i) in results"
      :key="i"
      :coordinates="[place.coordinate.latitude, place.coordinate.longitude]"
      :annotation="{ title: place.name }"
    />
  </VMap>
</template>

Returns

Property	Type	Description
`search`	`(query, options?) => Promise<mapkit.SearchResponse>`	Full place search
`autocomplete`	`(query, options?) => Promise<mapkit.SearchAutocompleteResponse>`	Live suggestions
`isSearching`	`Ref<boolean>`	`true` while a request is in flight
`error`	`Ref<Error \| null>`	Last error, or `null`

search accepts mapkit.SearchOptions and autocomplete accepts mapkit.SearchAutocompleteOptions (region, coordinate, language) as an optional second argument.

Tip

Debounce autocomplete so you don't fire a request per keystroke. A ~250ms debounce (e.g. VueUse's useDebounceFn) gives responsive suggestions without flooding the service.

usePointsOfInterestSearch

Fetches points of interest constrained by category, region, and other options — without a free-text query.

<script setup lang="ts">
  import { usePointsOfInterestSearch } from '@geoql/v-mapkit';

  const { search, isSearching, error } = usePointsOfInterestSearch();

  async function loadCafes(region: mapkit.CoordinateRegion) {
    const response = await search({
      region,
      pointOfInterestFilter: mapkit.PointOfInterestFilter.including([
        mapkit.PointOfInterestCategory.Cafe,
      ]),
    });
    return response.places;
  }
</script>

Returns

Property	Type	Description
`search`	`(options) => Promise<mapkit.PointsOfInterestSearchResponse>`	POI search by `mapkit.PointsOfInterestSearchOptions`
`isSearching`	`Ref<boolean>`	`true` while a request is in flight
`error`	`Ref<Error \| null>`	Last error, or `null`

The result places are MapKit Place objects — drop them onto the map with VPlaceAnnotation or feed a coordinate to VMarkerAnnotation.

See the live Search example.