Getting started with Search

_{Last updated: April 7, 2026 | 5 minutes read}

The Maps SDK for TypeScript provides flexible and robust search functionality, allowing you to search for locations using text queries and coordinates:

• Text Search: Perform searches using a text query and geographic coordinates to prioritize results within a specific area.
• Search Preferences: Customize search behavior using various options, such as allowing fuzzy results, limiting search distance, or specifying the number of results.
• Category-Based Search: Filter search results by predefined categories, such as gas stations or parking areas.
• Proximity Search: Retrieve all nearby landmarks without specifying a text query.

Text search

The simplest way to search for something is by providing text and specifying coordinates. The coordinates serve as a hint, prioritizing points of interest (POIs) within the indicated area.

import { SearchService, SearchPreferences, Coordinates, GemError, Landmark } from '@magiclane/maps-sdk';

const text = "Paris";
const coords = new Coordinates({ latitude: 45, longitude: 10 });
const preferences = SearchPreferences.create({
  maxMatches: 40,
  searchAddresses: true,
  searchMapPOIs: true
});

const taskHandler = SearchService.search({
  textFilter: text,
  referenceCoordinates: coords,
  preferences: preferences,
  onCompleteCallback: (err: GemError, results: Landmark[]) => {
    // If there is an error or there aren't any results, the method will return an empty list.
    if (err === GemError.success) {
      if (results.length === 0) {
        console.log("No results");
      } else {
        console.log(`Number of results: ${results.length}`);
        results.forEach(result => {
          console.log(`- ${result.name} at ${result.coordinates.latitude}, ${result.coordinates.longitude}`);
        });
      }
    } else {
      console.error(`Error: ${err}`);
    }
  }
});

note

The SearchService.search method returns null only when the geographic search fails to initialize. In such cases, calling SearchService.cancelSearch(taskHandler) is not possible. Error details will be delivered through the onComplete callback of the SearchService.search method.

The err provided by the callback function can have the following values:

Value	Significance
GemError.success	Successfully completed
GemError.reducedResult	Search was successfully completed but only a subset of results were returned
GemError.cancel	Cancelled by the user
GemError.noMemory	Search engine couldn't allocate the necessary memory for the operation
GemError.invalidInput	Search input is invalid, e.g. referenceCoordinates are invalid
GemError.operationTimeout	Search was executed on the online service and the operation took too much time to complete (usually more than 1 min, depending on the server overload state)
GemError.networkFailed	Search was executed on the online service and the operation failed due to bad network connection

Specifying preferences

As seen in the previous example, before searching we need to specify some SearchPreferences. The following characteristics apply to a search:

Field	Type	Default Value	Explanation
allowFuzzyResults	boolean	true	Allows fuzzy search results, enabling approximate matches for queries.
maxMatches	number	40	Maximum number of search results to return.
thresholdDistance	number	maximum int value	Maximum distance (in meters) from the search coordinates to consider results.

Example with more preferences:

const preferences = SearchPreferences.create({
  maxMatches: 20,
  searchAddresses: true,
  searchMapPOIs: true
});

Category-based search

You can filter search results by specific categories:

import { SearchService, LandmarkCategory, Landmark, GemError } from '@magiclane/maps-sdk';

const coords = new Coordinates({ latitude: 48.858844, longitude: 2.294351 }); // Paris
const preferences = SearchPreferences.create({
  maxMatches: 10,
  searchAddresses: true,
  searchMapPOIs: true
});

const taskHandler = SearchService.search({
  textFilter: "", // Empty text for category-only search
  referenceCoordinates: coords,
  preferences: preferences,
  onCompleteCallback: (err: GemError, results: Landmark[]) => {
    if (err === GemError.success) {
      console.log(`Found ${results.length} results`);
    }
  }
});

Proximity search

Retrieve all nearby landmarks without specifying a text query:

const coords = new Coordinates({ latitude: 40.748817, longitude: -73.985428 }); // New York
const preferences = SearchPreferences.create({
  maxMatches: 50,
  searchAddresses: true,
  searchMapPOIs: true
});

const taskHandler = SearchService.search({
  textFilter: "",
  referenceCoordinates: coords,
  preferences: preferences,
  onCompleteCallback: (err: GemError, results: Landmark[]) => {
    if (err === GemError.success) {
      console.log(`Found ${results.length} nearby landmarks`);
    }
  }
});

Canceling a search

If you need to cancel an ongoing search operation:

if (taskHandler) {
    SearchService.cancelSearch(taskHandler);
    console.log('Search cancelled');
}

Using Promises (Alternative Pattern)

You can wrap the search in a Promise for async/await usage:

function searchAsync(
  text: string,
  coords: Coordinates,
  preferences: SearchPreferences
): Promise<Landmark[]> {
  return new Promise((resolve, reject) => {
    const taskHandler = SearchService.search({
      textFilter: text,
      referenceCoordinates: coords,
      preferences: preferences,
      onCompleteCallback: (err: GemError, results: Landmark[]) => {
        if (err === GemError.success) {
          resolve(results);
        } else {
          reject(new Error(`Search failed with error: ${err}`));
        }
      }
    });
    
    if (!taskHandler) {
      reject(new Error('Failed to initialize search'));
    }
  });
}

// Usage
try {
  const results = await searchAsync("Restaurant", coords, preferences);
  console.log(`Found ${results.length} restaurants`);
} catch (error) {
  console.error('Search error:', error);
}

Next Steps

Now that you understand basic search functionality, you can explore:

• Reverse geocoding (converting coordinates to addresses)
• Forward geocoding (converting addresses to coordinates)
• Auto-suggestion for search queries
• Custom landmark search