Skip to content

Free Text Search

This guide shows you how to use free text search control on an interactive map with various options.

When to use

  • To render a searchable interactive map.

What is needed

  • Magic Lane API key token

  • Web server (an example is provided)

Setup

Get your Magic Lane API key token: if you do not have a token, see the Getting Started guide.

This project needs a web server. If you do not have access to a web server, you can easily install a local web server, see the Installing a Local Web Server guide. In this project we use a local web server.

Free Text Search Control using Default Options

The finished example using default search control options will look like this:

See the example fullscreen

If the search result is a region, its contour/perimeter is rendered on the map in red.

The map supports pan and zoom, and is fully 3D, so holding down the shift key and panning will simultaneously rotate and tilt the map.

How it works

 1// Start by setting your token from https://developer.magiclane.com/api/projects
 2if (gem.core.App.token === undefined)
 3     gem.core.App.token = "";
 4let defaultAppScreen = gem.core.App.initAppScreen(
 5     {
 6             container: "map-canvas",
 7             center: [48.8612, 2.333, 7000000] // latitude , longitude, altitude
 8     }
 9);
10let searchControl = new gem.control.SearchControl();
11defaultAppScreen.addControl(searchControl);
The map is rendered in the div container with the id map-canvas in the HTML page.
The map is initially centered on the specified coordinates, given as latitude and longitude in degrees, and altitude in meters.
A defaultAppScreen.addControl(searchControl); is added to the map, which includes a free text search box.
If the search result is an area, such as a country or region, its perimeter will be drawn on the map. The color of the perimeter can be optionally specified using rgba (red, green, blue, alpha) values between 0 and 255, otherwise a default color will be used.
 1<html>
 2
 3<head>
 4  <meta charset="utf-8">
 5  <title>Search Example - MagicLane Maps SDK for JavaScript</title>
 6  <link rel="stylesheet" type="text/css" href="https://www.magiclane.com/sdk/js/gem.css">
 7</head>
 8
 9<body>
10  <div id="map-canvas" style="width: 100%; height: 100%; position: absolute;">
11  </div>
12  <script type="text/javascript" src="https://www.magiclane.com/sdk/js/gemapi.js"></script>
13  <script type="text/javascript" src="token.js"></script>
14  <script type="text/javascript" src="jsHelloSearch01.js"></script>
15</body>
16
17</html>
map-canvas is the id of the drawing area where the map is rendered. The canvas is configured to fill the browser window.
At the bottom, gemapi.js, the Maps SDK for JavaScript is loaded.
Next, the JavaScript source of this example is loaded.

Free Text Search Control Custom Options

The finished example using customized search control options will look like this:

See the example fullscreen

How it works

 1// Start by setting your token from https://developer.magiclane.com/api/projects
 2if (gem.core.App.token === undefined)
 3     gem.core.App.token = "";
 4let defaultAppScreen = gem.core.App.initAppScreen(
 5     {
 6             container: "map-canvas",
 7             center: [48.8612, 2.333, 7000000] // latitude , longitude, altitude
 8     }
 9);
10let searchControl = new gem.control.SearchControl(
11     { // search options
12             highlightOptions: {
13                     contourColor: { r: 0, g: 255, b: 0, a: 255 },
14                     searchResultPin: false
15             },
16             searchPreferences: {
17                     exactMatch: true,
18                     maximumMatches: 4,
19                     addressSearch: true,
20                     mapPoisSearch: true,
21                     mapEnvelope: {  // restrict to Paris area
22                             topLeft: {
23                                     latitude: 49.02391,
24                                     longitude: 1.98219,
25                                     altitude: 0,
26                                     bearing: 0
27                             },
28                             bottomRight: {
29                                     latitude: 48.61471,
30                                     longitude: 2.79206,
31                                     altitude: 0,
32                                     bearing: 0
33                             }
34                     },
35                     setCursorReferencePoint: true
36             },
37             searchResults: {
38                     initialPlaceSearch: "Paris",
39                     showLandmarkIcons: true
40             }
41     }
42);
43defaultAppScreen.addControl(searchControl);
The search control options used in this example are:

  • highlightOptions.contourColor: search result highlight contour color (if available)

  • highlightOptions.searchResultPin set to false: highlight result landmark icon instead of using search result pin icon

  • searchPreferences.exactMatch set to true: find exact match related to the search input text string

  • searchPreferences.maximumMatches: number of search results to display, maximum 5

  • searchPreferences.addressSearch set to true: use the address search

  • searchPreferences.mapPoisSearch set to true: use the POIs search

  • searchPreferences.mapEnvelope: map area in which to restrict the search results

  • searchPreferences.setCursorReferencePoint set to true: the search reference coordinate is set at the last cursor position, if set to false (default) the reference point is the center of the map envelope

  • searchResults.initialPlaceSearch: specify a start-up location

  • searchResults.showLandmarkIcons set to true: display the landmark icons next to the search results

 1<html>
 2
 3<head>
 4  <meta charset="utf-8">
 5  <title>Search Example - MagicLane Maps SDK for JavaScript</title>
 6  <link rel="stylesheet" type="text/css" href="https://www.magiclane.com/sdk/js/gem.css">
 7</head>
 8
 9<body>
10  <div id="map-canvas" style="width: 100%; height: 100%; position: absolute;">
11  </div>
12  <script type="text/javascript" src="https://www.magiclane.com/sdk/js/gemapi.js"></script>
13  <script type="text/javascript" src="token.js"></script>
14  <script type="text/javascript" src="jsHelloSearch02.js"></script>
15</body>
16
17</html>

Files

The finished example consists of the project directory containing these files:

  • JavaScript code (.js file extension)

  • HTML code (.html file extension)

To run the example, the HTML file is loaded in a browser.

Source code for default options search control:
JavaScript
HTML
Source code for customized options search control:
JavaScript
HTML

right-click on the links and select Save As.

JavaScript Examples

Maps SDK for JavaScript Examples can be downloaded or cloned with Git