Autocomplete widget

This widget allows you to add to your site search for various objects by address, coordinates, name and other parameters. You can even add your own objects for output in the suggests bar. Also this widget is easy to combine with our map. You can view the source code on GitHub.

Page preparation

To add the widget, you must perform several steps:

  1. Get access key to Visicom Tiles and Visicom Data API services.
  2. In the head section of the page add СSS file with the widget styles
<link rel="stylesheet" href="https://api.visicom.ua/apps/visicom-autocomplete.min.css">
  1. Add loading of the “engine” itself, preferably before the closing body tag.
<script src="https://api.visicom.ua/apps/visicom-autocomplete.min.js"></script>
  1. Define a div in which the widget will be displayed. An element with a <a> tag is required. This item will disappear upon initialization.
<div id="visicom-autocomplete">
    <a href="https://api.visicom.ua/" target="_blank">© Visicom</a>
</div>

Widget initialization

To initialize the widget, you need to insert the following code between the script tags:

let ac = new visicomAutoComplete({        
    apiKey : 'YOUR_AUTHORITY_KEY',
}); 

Do not forget to replace ** YOUR_AUTHORITY_KEY ** with the key received during registration. In addition to the specified parameter ** apiKey ** there are other useful options. Currently supported options:

  • apiKey — your Visicom Data API access key (required, if no links are specified for proxying)
  • selector — the selector of the element in which the widget is created (optional, default = '#visicom-autocomplete')
  • width — widget width (optional, default = '100%')
  • height — widget height (optional, default = null)
  • placeholder — text shown when the input field is empty (optional, default = 'Search...')
  • minCahrs — the minimum number of characters at which the search will begin (optional, default = 3). The smaller the number, the more queries will be made
  • delay — the delay between entering characters at which the search will begin, ms (optional, default = '150'). The smaller the number, the more queries will be made
  • suggestsLimit — the maximum number of suggests to display (optional, default = '5')
  • lang — search language (optional, default = 'local', you can also specify one of: 'uk', 'en', 'ru')
  • searchTextPrefix — this text will be inserted in the query before the text from the input field. So you can specify your city, so that the search is related to it (optional, default = '')
  • onSuggestSelected — the function that will be called when choosing a suggest (optional, default = () => console.log)
  • map — created map object (used with Leaflet library) (optional). When choosing a suggest, the map will zoom on this place. If not specified, only the onSuggestSelected function will be called
  • marker — Your own marker to display on the map (optional)
  • proxyApiGeocodeUrl — URL for proxying a geocode request (optional). In this case, you do not need to specify your access key to Visicom Data API. A GET request will be sent to your server with the following parameters: text (text that is searched), lang, key (API key), limit (suggestsLimit)
  • proxyApiFeatureUrl — URL for proxying a feature request (optional). In this case, you do not need to specify your access key to Visicom Data API. A GET request will be sent to your server with the following parameters: feature_id (the id of the feature object that is being requested), lang, key (API key)
  • includeCategories - only features with this categories will be included in results. (optional, array of strings, default = [])
  • excludeCategories - features with this categories will be excluded from results. (optional, array of strings, default = [])
  • customFeatures — array of your objects (optional). Objects from this list will have the highest priority when displayed in suggests. Each object in the array should contain 3 fields: html (text displayed in suggest), keywords (text that contains the keywords for searching), coords (an array of two coordinates of your object)

When using a proxy server, be sure to return the exact same JSON object that your server received from Visicom Data API. When the widget is initialized, an object will be returned in Javascript that has the following methods:

  • clear — clears the input field and all suggests

A whole example with a map

<!DOCTYPE html>
<html lang="uk">
  <head>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
      <link rel="stylesheet" href="https://unpkg.com/leaflet@1.3.4/dist/leaflet.css">
	<link rel="stylesheet" href="https://api.visicom.ua/apps/visicom-autocomplete.min.css">
  </head>
  <body>
    
    <div id="visicom-autocomplete">
      <a href="https://api.visicom.ua/" target="_blank">© Visicom</a>
    </div>
    <div id="map" style="width: 800px; height: 400px;"></div>

  </body>
  <script type="text/javascript" src="https://api.visicom.ua/apps/visicom-autocomplete.min.js"></script>
  <script src="https://unpkg.com/leaflet@1.3.4/dist/leaflet.js"></script>
  <script>

    document.addEventListener('DOMContentLoaded', function(){
        let map = new L.Map('map', {
            center: new L.LatLng(50.455002, 30.511284), 
            zoom: 9,                                
            layers : [
                new L.TileLayer(
                    // paste below your private API key in key parameter
                    'https://tms{s}.visicom.ua/2.0.0/planet3/base_ru/{z}/{x}/{y}.png?key=YOUR_AUTHORITY_KEY',
                    {
                    maxZoom : 19,
                    tms : true,
                    attribution : 'Данные карт © 2019 ЧАО «Визиком»',
                    subdomains : '123'
                    }        
                )
            ]
        }); 

        let ac = new visicomAutoComplete({        
            selector : '#visicom-autocomplete',      // search div selector
            apiKey : 'YOUR_AUTHORITY_KEY',                 // paste here your private API key
            placeholder : 'Search your places...',   // placeholder for search input
            minChars : 3,                            // min chars to start searching
            delay : 150,                             // delay between key pressed for search to start
            width : '400px',                         // width of search input
            height : '35px',                         // height of search input
            map: map,                                // map object to zoom on it
            suggestsLimit : 5,                       // limit of suggests to display
            includeCategories : [],                  // include only features with this categories in results
            excludeCategories : [],                  // exclude features with this categories from results
            maxCharsInSuggest: 55,                   // max chars to display in suggest
            lang : 'local',                             // language for searching
            onSuggestSelected : suggest => console.log('Suggest selected: ' + (suggest.html)), 
            customFeatures: [{                       // custom feature objects
                    html: 'наша фирма',
                    keywords: 'киев вербицкого наша фирма',
                    coords:[50, 30],
                },
                {
                    html: 'тестовый вариант',
                    keywords: 'чернигов шевченко 23',
                    coords:[50.46537, 30.48019],
                }],
        });
    });
  </script>
</html>

Result

Visicom-autocomplete