JavaScript Maps SDK

Single Search Add-on

Contents

The Single Search add-on control provides a single text box for all location searches. By default, the control displays the results stacked under the search box.

CDN Example

View a working demo and follow the steps below to create your own

<script src="https://maps-sdk.trimblemaps.com/addon/trimblemaps-singlesearch-1.1.2.js"></script>
<!-- Single Search addon reference js -->
<link href="https://maps-sdk.trimblemaps.com/addon/trimblemaps-singlesearch-1.1.2.css" rel="stylesheet">
<!-- Single Search addon reference css -->

TrimbleMaps.APIKey = "YOUR_ACCESS_TOKEN";

const map = (window.map = new TrimbleMaps.Map({
  container: "map",
  zoom: 12.5,
  center: new TrimbleMaps.LngLat(-77.01866, 38.888)
}));

const ctrl = new TrimbleMapsControl.SingleSearch({
  placeholderText: "Search here",
  doneTypingInterval: 700,
  hideResults: true,
  locationRelevance: "mapCenter",
  searchOption: {
    region: TrimbleMaps.Common.Region.WW,
    maxResults: 30
  },
  markerStyle: {},
  markerConfig: {},
  popupConfig: {}
  // Include other optional customization options
});

// Map#addControl takes an optional second argument to set the position of the control.
// If no position is specified the control defaults to `top-right`.

map.addControl(ctrl, "top-left");

Module Bundler Example

Install the npm package.

npm install --save @trimblemaps/trimblemaps-singlesearch

Make sure the CSS file is included in the page either by adding it to the <head> of your HTML file or importing it with your bundler.

Next, import and use the JS module in your code.

Note: Since the multiple add-ons are published in separate packages, the modules in each package are exported individually. You will import each module directly rather than using a single namespace variable of TrimbleMapsControl shown above in the CDN example.

import TrimbleMaps from "@trimblemaps/trimblemaps-js";
import SingleSearch from '@trimblemaps/trimblemaps-singlesearch';

TrimbleMaps.APIKey = "YOUR_KEY_HERE";

const map = new TrimbleMaps.Map({
  container: "map",
  zoom: 12.5,
  center: new TrimbleMaps.LngLat(-77.01866, 38.888)
});

const ctrl = new SingleSearch({
  placeholderText: "Search here",
  doneTypingInterval: 700,
  hideResults: true,
  locationRelevance: "mapCenter",
  searchOption: {
    region: TrimbleMaps.Common.Region.WW,
    maxResults: 30
  },
  markerStyle: {},
  markerConfig: {},
  popupConfig: {}
  // Include other optional customization options
});

map.addControl(ctrl, "top-left");

Customization Options

Parameter NameType/ValuesDescription
doneTypingInterval 
Number
Default: 700
The debounce value in milliseconds. The search web service request fire rate limit to this value.
placeholderText 
String
Default: Address
Placeholder text for the search box.
minSearchTextLength 
Number
Default: 3
If search text is longer than this value, then search can be started.
locationRelevance 
String
Default: null
Available values are “mapCenter”, “device”, or null. If it is set, map view center or device location will be used to assist search.
hideResults 
Boolean
Default: false
Hide results list or not when a result item is clicked on or enter key is pressed on a focused item.
searchOption 
Object
Optional.
See the section below.
markerStyle 
Object
Optional.
See the section below.
markerConfig 
Object
Optional.
See the section below.
popupConfig 
Object
Optional.
See the section below.

Search Option:

The searchOption parameter contains options that are used by the geocoder web service to perform the search.

ParameterType/ValuesDescription
query 
String
Default: null
If it is not null, the search input box value will be ignored by the control. It is optional.
maxResults 
Number
Default: 20
Maximum returned results.
currentLonLat 
LngLat.L.latLng
Default: null
Search near the location provided. Latitude and longitude values are in degrees. It is optional. The control can set current location based on navigator.geolocation location or map view center. They are optional too.
excludedSearchTypes 
String
Default: null
Comma-separated list of types to exclude from the search.
poiCategories 
String
Default: null
Comma-separated list of POI category names by which you want to filter all POI results.Note: To get supported categories, call SearchService.singleSearchGet(“poiCategories”) method.
countries 
String
Default: null
Comma-separated list of country abbreviations by which you want to filter all results.
countryType["ISO", "FIPS", "GENC2", "GENC3"]Default: null
states 
String
Default: null
Comma-separated list of state abbreviations by which you want to filter all results.
region[TrimbleMaps.Common.Region.NA, TrimbleMaps.Common.Region.EU, TrimbleMaps.Common.Region.WW]Required.
success 
Function
Optional.
If it is provided, it will replace the control built-in handler method.
failure 
Function
Optional.
If it is provided, it will replace the control built-in handler method.

Marker Style

After search results are returned, the control will display them as a stacked list under the search input box by default. When a list item is clicked or the Enter key is pressed on an item having the focus in the list, a marker for the location will be shown on the map. The markerStyle parameter determines the marker’s look and feel.

ParameterType/ValuesDescription
externalGraphic 
String
Default: null
If the URL is supplied, it will replace the default icon. If null, the control will choose icon for the marker based on result type.
graphicHeight 
Number
Default: 26
Marker height in pixels.
graphicWidth 
Number
Default: 26
Marker height in pixels.
graphicXOffset 
Number
Default: -13
Marker x-direction offset.
graphicYOffset 
Number
Default: -13
Marker y-direction offset.

Marker Configuration

The markerConfig parameter contains options related to the creation of the marker on the map.

ParameterType/ValuesDescription
exclusive 
Boolean
Default: true
If true, erases all other makers first.
centerOnMap 
Boolean
Default: true
Center the marker on the map.
zoomLevel 
Number
Default: 12
Centers the marker at the zoom level.

The popupConfig parameter contains options related to the creation of the marker popup on the map.

ParameterType/ValuesDescription
show 
Boolean
Default: true
If true, shows popup with the marker.
className 
String
Default: single-search
CSS class name. If you change this value, you need to add your CSS class to your style file.
offset 
Number
Popup location offset.
closeBox 
Boolean
Default: false
If true, shows the close button on the popup.

Events

The primary method of reacting to user interaction with the add-on is through events. The full list of events is available in the API documentation.

A common scenario is to perform some action when a location is selected from the list of results by the user. This can be accomplished with the locationselected event.

TrimbleMaps.APIKey = "YOUR_ACCESS_TOKEN";

const map = new TrimbleMaps.Map({
  /* map options */
});
const ctrl = new TrimbleMapsControl.SingleSearch({
  /* control options */
});

map.addControl(ctrl, "top-left");

ctrl.on("locationselected", (evt) => {
  // The `location` property of the event contains the location data of the
  // search result selected by the user.
  console.log(evt.location);
});

API Documentation

View Single Search API Documentation

Last updated June 15, 2023.
Contents