Skip to main content
GuidesAPI ReferenceExamples

Free Text Search

Estimated reading time: 5 minutes

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.

info

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​

// Start by setting your token from https://developer.magiclane.com/api/projects
if (gem.core.App.token === undefined)
    gem.core.App.token = "";
let defaultAppScreen = gem.core.App.initAppScreen(
    {
        container: "map-canvas",
        center: [48.8612, 2.333, 7000000] // latitude , longitude, altitude
    }
);
let searchControl = new gem.control.SearchControl();
defaultAppScreen.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. f 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.

Free Text Search Control Custom Options​

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

See the example fullscreen

// Start by setting your token from https://developer.magiclane.com/api/projects
if (gem.core.App.token === undefined)
    gem.core.App.token = "";
let defaultAppScreen = gem.core.App.initAppScreen(
    {
        container: "map-canvas",
        center: [48.8612, 2.333, 7000000] // latitude , longitude, altitude
    }
);
let searchControl = new gem.control.SearchControl(
    {   
        // search options
        highlightOptions: {
                contourColor: { r: 0, g: 255, b: 0, a: 255 },
                searchResultPin: false
        },
        searchPreferences: {
                exactMatch: true,
                maximumMatches: 4,
                addressSearch: true,
                mapPoisSearch: true,
                mapEnvelope: {  // restrict to Paris area
                        topLeft: {
                                latitude: 49.02391,
                                longitude: 1.98219,
                                altitude: 0,
                                bearing: 0
                        },
                        bottomRight: {
                                latitude: 48.61471,
                                longitude: 2.79206,
                                altitude: 0,
                                bearing: 0
                        }
                },
                setCursorReferencePoint: true
        },
        searchResults: {
                initialPlaceSearch: "Paris",
                showLandmarkIcons: true
            }
    }
);
defaultAppScreen.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

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:

Source code for customized options search control:

Right-click on the links and select Save As.

JavaScript Examples​

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