In-ADS Developer Guide

Transcription

1 Version Estonian Land Board

2 Table of contents 1. Introduction Requirements Embed code generation Main modes of operation Object types and priorities Map layers Selection of base layers Selection of map layers Additional WMS layers EHAK filter Marking the location on the map Generated code for In-ADS widget In-ADS widget Map Address search Apartment search Historic addresses In-ADS API Functions hideresult() setaddress(address) showmap() hidemap() searchaddress (ads_oid, bbox) setinfo(turnon) togglefullscreen (turnon) Events mapnavigate inaadressloaded addressselected ESTONIAN LAND BOARD

3 5.3 Input description Output description Output of object-based search Output of address-based search In-ADS editor API Drawing and editing Redisplay of existing shape on the map Style Input description Functions setgeomobject(geomobject, fit) sectvectorobjects(features, style, fit) getinads() Events featureadded featuremodified featureselected In-ADS style Description of gazetteer service Input description Output description ESTONIAN LAND BOARD

4 1. Introduction In-ADS widget is an embeddable HTML5/JavaScript code, which can easily be integrated into custom web solutions to provide a high-quality address search functionality. The In-ADS widget can be used either as a classical address search bar, or by systems that need to find a list of normalized addresses, meeting the requirements set by ADS, with all relevant meta-information. This guide is meant for developers, who generate embed code by using the respective interface and integrate it into information systems. The output of the code generator is highly suitable e.g. for adding an address search function to a website. On the initial page of the user interface there is a sample In-ADS widget, which the user can see and try out. There are also links to the user guide and the developer guide. The first one is meant both for everyday users, who want to use the generated code directly, and for developers, who wish to use In-ADS e.g. in an information system. Interacting with In-ADS widget happens via JavaScript interface. Various events like selecting the address (that are implemented as DOM events) trigger In-ADS widget to return JavaScript object with address data. The external system can also invoke different functions of In-ADS. 2. Requirements The In-ADS widget uses HTML5 standard. Thus, supported are browsers that support the above standard. Currently (as of the 16 th of October 2014) the supported browsers are: Internet Explore versions 10 and 11 Safari version or newer Google Chrome version m or newer Mozilla Firefox version or newer. The recommended minimum size of the widget with a map is 300x300 px. ESTONIAN LAND BOARD

5 3. Embed code generation The user can generate In-ADS HTML5 embed code dynamically by using the web interface that separates configurable options into different pages. 3.1 Main modes of operation First the desired mode of operation has to be chosen: Mode of operation Address search bar with a map Address search bar with a map (by default the map is hidden) Address search bar without a map Only map for displaying the location Description Both the address search box and the map, on which the found addresses are displayed, are shown. It is also possible to select the address on the map. Similar to the previous option, but by default the map is hidden. There is a separate button for displaying and hiding the map Only the address search box is displayed. In this mode only address-based search is enabled. Only the map is displayed and addresses cannot be searched through the user interface. This mode is meant for displaying specific addresses pre-set during the creation of the In-ADS widget. It is possible for the user to make a selection from among the addresses displayed on the map. Additionally, the ID value of a DIV element, into which the In-ADS widget will be placed, must be set. If the user is willing to change the appearance of the widget, it s possible to check the option to use a custom CSS file. If this option is selected, the widget s CSS file is not used ( nocss :true). As the widget uses jquerymobile (version 1.4.3) layout, the use of a respective CSS file is recommended in order to make the creation of custom layout easier. The CSS file is available at ESTONIAN LAND BOARD

6 css If so desired, also the jquerymobile TheremeRoller tool ( can be used. This tool enables an easy styling of all kinds of jquerymobile widgets and a generation of a respective CSS file. While using TheremeRoller, besides the addition of CSS file, also the jquery and jquerymobile JavaScript files must be added to the header. Example: <link rel="stylesheet" href=" /> <script type="text/javascript" src=" ></script> <script type="text/javascript" src=" min.js"></script> <script type="text/javascript" src=" </script> There are also optional choices whether to display a scale bar and a measuring tool on the map or not. For the use of the In-ADS widget in full screen mode (e.g. in mobile version) the box Show Full Screen must be checked. 3.2 Object types and priorities A radio button allows to choose between the address-based and object-based searches. ESTONIAN LAND BOARD

7 Object types: General address search all object types are searched for and found addresses are returned (if multiple objects are related to a single address, the one with the highest priority is displayed in conformity with priority rules) Select object types (object-based search) object types to be searched for can be selected. The search result returns all found objects matching the searched address, the sequence of objects is based on priority rules. If also building is selected, it will be possible to restrict the search in a way that only buildings with the uniqueness requirement of an address are searched for. Buildings requiring a unique address are e.g. residential buildings, schools, commercial buildings, accommodation buildings, hospitals, etc.; buildings not requiring a unique address are e.g. sheds and other outbuildings in which people are not expected to reside on a daily basis. In the search for buildings also apartments can be included. Users can be allowed to enter also new apartments (apartment number), but these are ESTONIAN LAND BOARD

8 not saved in ADS being only of an informative value to the external system. NB! Any information about apartments missing in ADS (new apartments), or about data contradicting to the reality or otherwise problematic should be sent to Priority rules define which object has preference in address-based search or in what sequence objects are displayed in object-based search. 3.3 Map layers Selection of base layers If the selected mode of operation includes also a map, it will be possible to choose the background maps to be added to the widget. If more than one layer is selected, it will also be possible to set the default base layer Selection of map layers In addition to the background map, other map layers can be added to the map, e.g. addresses or cadastral parcels (these map layers are always displayed on the map and the user cannot turn them on/off) Additional WMS layers Besides the background map and the Land Board s maps, additional WMS layers of third parties can also be displayed on the map. To be able to do that, the URL of WMS service with the VERSION and LAYERS parameters must be inserted. For example: ds_hoone_aadr. Multiple WMS layers can be added. Additionally specified WMS layers will be displayed on top of the map in the order of adding and they cannot be managed further. 3.4 EHAK filter ESTONIAN LAND BOARD

9 EHAK filter allows to limit search results to county, local government or settlement level. In this case objects are searched for only from the selected EHAK area and the map is by default opened in the selected EHAK area. 3.5 Marking the location on the map Provided that Only map for displaying the location mode of operation has been chosen, it is possible to visualise the location on the map together with tooltips. To add a location to the map, the desired address has to be entered into the search bar and a choice made from the list, or an appropriate location clicked on the map. After the choice has been made, a textbox with the found addresses will be displayed next to the map and a marker with a tooltip will be shown on the map. The tooltip text can be changed by entering an appropriate name into the box. Several locations can be added to the map by repeating the above actions. Tooltips can be deleted by clicking the button Delete next to the text box or the button Delete objects at the end of the list. Zoom to button will zoom the map to the extent of selected objects. The chosen location will also serve as the initial view of the generated in-ads widget. To change the initial view, it is necessary to navigate on this page to a desired location. 3.6 Generated code for In-ADS widget The code that was generated according to previous choices will be presented on the last page. The code to be added to the header of HTML page (JavaScript of the In-ADS widget): And JavaScript part of the In-ADS widget. For example: ESTONIAN LAND BOARD

10 The example of HTML-page that uses the generated code is also provided: The height and width of DIV element can be used for setting the width, and in case a map is included, also the height of the widget. The default width of the widget is 100% and the default height for the widget with a map is 450 px. When the widget is used with a map neither the widget itself, nor the surrounding container can be hidden (style= display:none ). In-ADS can be used also over HTTPS ( 4. In-ADS widget 4.1 Map Depending on the configuration, the widget consists either of a map with a search field, only a map, only a search field or a search field and a button with which it is possible to show/hide the map. The map component consists of a map window. The layers displayed on the map cannot be managed by the user. The components to be displayed on the map are as following: ESTONIAN LAND BOARD

11 1. Selection list of base layers (a predefined choice of base maps). In addition to using the mouse, it is possible to move around in the list by using Up and Down arrows and confirming the choice with Enter. 2. Navigation buttons for zooming the map in and out. Zooming in/out can be done also by using the mouse wheel. 3. Information button By turning on the information button and clicking on an object on the map, the user can see a more detailed information about the object. Information will be displayed according to the preselected object types. When search by address was selected, a list of all objects found in this location will be returned. When certain object types were selected, the result displays objects only from these types. The window can be closed by using the Esc key. By clicking on the map it is possible to choose the address (providing the mode of operation includes a map). For that it is necessary to navigate to the desired location and click on the searched object. If there is only one object in the selected location, the address of this object will be displayed in the address search bar and an orange marker will be displayed on the place of click. If there are several objects of the same type in the selected location, the user will be asked to choose the object. After making the selection and confirming it, the address of the selected object will be displayed in the address search bar. In the scales between 1:4000 and 1:40000 the returned selection of objects includes cadastral parcels, EHAK, territorial units and traffic spaces. In larger scales also buildings are included. If only certain types of objects are predefined, only these will be suggested to the user. 4.2 Address search ESTONIAN LAND BOARD

12 By entering an address into the search box, a selection of found addresses will be returned. The list of results contains always at maximum 10 addresses. If the searched address is not among the found addresses, the search must be specified further. In case the number of found addresses is 5 or less, the found addresses will directly be displayed on the map that will be zoomed to the proper extent (provided the mode of operation includes a map). In this case there is an orange marker in front of each address, which shows where the given address is located on the map. With the object-based search (the types of objects to be searched from were predefined) the search result displays also the object type (KÜ cadastral parcel, HÜ EHAK, LP traffic surface, VK territorial unit, H building). In addition to mouse, also the keys tab and shift+tab can be used for moving up and down in the list of displayed addresses by confirming the choice with Enter. When the user does not know the address or cannot find it for whatever reason, it is always possible to choose the address on the map (providing the mode of operation includes a map). For that it is necessary to navigate to the desired location and click on the searched object. If there is only one object in the selected location, the address of this object will be displayed in the address search bar and an orange marker will be displayed on the place of click. If there are several objects of the same type in the selected location, the user will be asked to choose the object. After making the selection and confirming it, the address of the selected object will be displayed in the address search bar. In the scales larger than 1:5000 only EHAK, territorial unit and traffic space objects are suggested. In scales smaller than 1:5000 cadastral parcels, buildings, streets and traffic spaces are displayed. If only certain types of objects are predefined, only these will be suggested to the user Apartment search ESTONIAN LAND BOARD

13 If settings enable also searching by apartments, there are two options how to do it. If the entered address includes the apartment number (separated by hyphen), e.g. Sõle 5-40, the returned results will show addresses together with apartment numbers. When only the address of a building is entered, then, after making a choice from the address list, a separate list with apartment numbers will appear from which the user can choose the desired apartment. Also the Up and Down keys can be used for moving around in the list and the choice can be confirmed with the Enter key. In case the settings of the In-ADS widget enable also adding of new apartments, the list includes an option other. By choosing it, a new dialogue box will be opened into which the user can enter the apartment number. Non-residential apartments have their own designation (MR). The number of an apartment, which does not exist in ADS, can also be entered into the search bar together with the address Historic addresses When the user searches by historic addresses (e.g. võidu väljak), the search results will still display the valid addresses, but the historic part of the address is shown in brackets in capital letters (e.g.vabaduse väljak (VÕIDU VÄLJAK), Kesklinna linnaosa, Tallinna linn, Harju maakond). 5. In-ADS API Interacting with In-ADS widget happens via JavaScript interface. Various events like selecting the address (that are implemented as DOM events) trigger In-ADS widget to return JavaScript object with address data. The external system can also invoke different In-ADS functions. 5.1 Functions The In-ADS widget includes the following functions: ESTONIAN LAND BOARD

14 5.1.1 hideresult() As after making the selection from the list of returned addresses, the list is neither emptied nor hidden, the external system can do it, if so desired, by invoking the function hideresult(). Example: var inaadress = new InAadress({"mode":1, "container":"inaadress", "baselayers":["aluskaart"], "defaultbaselayer":"aluskaart"}) document.addeventlistener('addressselected', function(e){ inaadress.hideresult(); }); This function can be used only with a mode of operation that contains the address search field (input parameter mode value 1, 2 or 3) setaddress(address) input: address(string) address text to be displayed User-selected address can also be set as a value of address search box by using the method setaddress(address). This method does not perform address search, it only sets a value of address search box. Example: var inaadress = new InAadress({"mode":1, "container":"inaadress", "baselayers":["aluskaart"], "defaultbaselayer":"aluskaart", "searchlayers":["katastriyksus"]}) document.addeventlistener('addressselected', function(e){ var aadress = e.detail.aadress; aadress = aadress.split(", ").reverse().join(", ESTONIAN LAND BOARD

15 "); }); inaadress.setaddress(aadress); This function can be used only with a mode of operation that contains the address search field (input parameter mode value 1, 2 or 3) showmap() When the widget is working in a mode in which the map is by default hidden ( mode value 2), it is possible to show the map programmatically. E.g. if the user selects the address from the list, the address will be indicated also on the map, but the map will not be shown automatically. var inaadress = new InAadress({"mode":2, "container":"inaadress", "baselayers":["aluskaart"], "defaultbaselayer":"aluskaart"}) document.addeventlistener('addressselected', function(e){ inaadress.showmap(); }); hidemap() When the widget is working in a mode in which the map is by default hidden ( mode value 2), it is possible to hide the map programmatically. Example: var inaadress = new InAadress({"mode":2, "container":"inaadress", "baselayers":["aluskaart"], "defaultbaselayer":"aluskaart"}) document.addeventlistener('addressselected', function(e){ inaadress.hidemap(); }); ESTONIAN LAND BOARD

16 5.1.5 searchaddress (ads_oid, bbox) input: ads_oid(array) - array of values of the address object s identifier (throughout all versions) to be searched and displayed on the map. Bbox(String) sets the BBOX extent ( minx,miny,maxx,maxy ) into which the objects will be displayed. Additionally that parameter can be set as a coefficient that multiplies the extent of the input address objects so that the overall extent will be accordingly wider. When the widget is working in the mode in which there is only the map ( mode value 4), it is possible to search address objects and display them on the map by using the function searchaddress(ads_oid). Example: var inaadress = new InAadress({"mode":4, "container":"inaadress", "baselayers":["aluskaart"], "defaultbaselayer":"aluskaart"}) document.addeventlistener('inaadressloaded', function(e){ inaadress.searchaddress(["ee ","me "]); }); setinfo(turnon) When the widget is working in the mode in which the map is included ( mode value 1, 2 or 4), it is possible to turn the information query on/off programmatically. Example: var inaadress = new InAadress({"mode":1, "container":"inaadress", "baselayers":["aluskaart"], ESTONIAN LAND BOARD

17 "defaultbaselayer":"aluskaart"}) inaadress.setinfo(true); togglefullscreen (turnon) It is possible to turn on or off the full screen mode. The full screen mode can be used only in the search with a map and in map view (mode=1 or mode=4). Example: var inaadress = new InAadress({"mode":1, "container":"inaadress", "baselayers":["aluskaart"], "defaultbaselayer":"aluskaart"}) inaadress.togglefullscreen(true); 5.2 Events Various activities trigger the In-ADS widget s DOM customevent events that will be sent to the external system mapnavigate The event will be invoked after every navigation on the map. Map BBOX extent [minx, miny, maxx, maxy] will be included. Example: var inaadress = new InAadress({"mode":1, "container":"inaadress", "baselayers":["aluskaart"], "defaultbaselayer":"aluskaart"}) ESTONIAN LAND BOARD

18 document.addeventlistener('mapnavigate', function(e){ alert("kaardi BBOX: " + e.detail); }); inaadressloaded The event will be invoked after initial loading of the In-ADS widget has been completed. This event is useful in cases when after initializing the In-ADS widget there is something to be done right afterwards. In this case the widget can be called only after it has completed the loading. Example: var inaadress = new InAadress({"mode":1, "container":"inaadress", "baselayers":["aluskaart"], "defaultbaselayer":"aluskaart"}) document.addeventlistener('inaadressloaded', function(e){ alert("komponent lõptas laadimise."); }); addressselected This event is to be called when triggered by the following actions: the user has entered an address into the search field and chosen the address from the returned results the user clicks on the address marker on the map (orange marker with a star) the user selects an apartment from the list of apartments the user checks the option other, enters the flat number into the opened box and presses the OK button the user clicks on the map on the location, where one object is found the user clicks on the map on the location, where there are several objects of the same type, the user selects the desired object and presses the choose address button. ESTONIAN LAND BOARD

19 Example: var inaadress = new InAadress({"mode":1, "container":"inaadress", "baselayers":["aluskaart"], "defaultbaselayer":"aluskaart"}) document.addeventlistener('addressselected', function(e){ var info = e.detail; alert( valitud aadress: + info.aadress); }); 5.3 Input description While creating the In-ADS widget, JSON object that configures the mode of operation and general functionality of In-ADS, must be supplied. The object may have the following properties: Property Description Compulsor y container ID value of a DIV element, into which the In- yes ADS widget will be placed mode Mode in which the In-ADS widget operates. yes Possible values: 1 address search bar with a map, 2 address search bar with a map (by default hidden), 3 only address search bar, 4 only map searchlayers What type of objects are searched for. no Without value, search is address-based, with value object-based. These are Array type properties the enabled elements of which are: EHITISHOONE, KATASTRIYKSUS, TANAV, VAIKEKOHT and EHAK unhoone When searchlayers parameter includes the value EHITISHOONE, it is possible to additionally filter search results in a way no ESTONIAN LAND BOARD

20 baselayers defaultbaselayer maplayers appartment ads_oid Bbox that only buildings with UN identifier (unique address) are searched for. Value options: false all buildings are searched (by default), true only buildings with UN identifier are searched. Which base layer options are enabled on the map. These are Array type properties the enabled elements of which are: ALUSKAART, ORTOFOTO and HYBRIID. When the mode of operation does not include a map, this property has no value. Default base layer sets which of the base layers is selected on the map by default. Possible values are ALUSKAART, ORTOFOTO or HYBRIID. Additional layers to be displayed on the map. In addition to the background map, it is possible to display also cadastral parcels and/or addresses. These are Array type properties the enabled elements of which are: KATASTRIYKSUS and AADRESSID. Sets whether apartments are searched or not. Value options are: 0 apartments are not searched (default value), 1 apartments are searched, 2 apartments are searched and entering of a non-existing apartment is also allowed. When the mode value is 4 (only map), array of values of the address object s identifier (throughout all versions) to be displayed on the map can be predefined. When the mode value is 4 (only map), this parameter can predefine the BBOX extent ( minx,miny,maxx,maxy ) into which the search result will be displayed. The parameter can also have a numeric value (bbox- multiplier). In the latter case the extent of the input address objects will be yes yes no no no no ESTONIAN LAND BOARD

21 multiplied so that the overall extent will be accordingly wider. nocss In order to use the In-ADS widget with a different style, this parameter shall be set to true. Value options are: false css file is loaded (default value), true css file is not loaded. lang Language parameter. By default Estonian - et, English is also possible en fullscreenmode This parameter enables to display the In- ADS widget in full screen mode. Value options are: true full screen view, false displayed as big as the container element into which it is displayed showscale When the value is set to true, scale will be displayed on the map. Default value is false. The parameter is considered only when In- ADS is used with a map. WMS A possibility to display on the In-ADS map additional WMS layers. Value is a list of WMS addresses, which must include also the list of layers and version number. E.g.: [ e_aadr ] tools A possibility to display on the map additional tools. Currently only the measuring tool is supported. Value is the list of tool names: "tools":["measure"] noinfo When value is set to true, the information query button will not be displayed on the map. noaddressmapselect When value is set to true, addresses cannot be selected by clicking on the map. markers With this parameter it is possible to display points on the map together with the marker. Value is the object with properties bbox and addresses. E.g. "markers": {"bbox": [ , , , no no no no no no no no no ESTONIAN LAND BOARD

22 ihist ], "addresses": [{"x": " ", "y": " ", "title": "Punkti märgend" }]} Weather to search from historic addresses. Value is year number (eg 1993) from which addresses are searched. By default, if no parameter value are given, all historic addresses are included in search. If value is 0, then historic addresses are excluded. no Example: var inaadress = new InAadress({"container":"inAadress", "mode":1, appartment:1, searchlayers:["ehak", "EHITISHOONE"], "baselayers":["aluskaart","hybriid"], "defaultbaselayer":"aluskaart", maplayers:["katastriyksus", "AADRESSID"]}); 5.4 Output description As the result of various activities data about address object(s) selected by the user will be sent to the external system. Input data will be transmitted via DOM customevent events. The name of event is addressselected and JSON object, containing address data, will be supplied. Example: document.addeventlistener('addressselected', function(e){ var info = e.detail; alert( valitud aadress: + info.aadress); }); The event addressselected is to be called when triggered by the following actions: ESTONIAN LAND BOARD

23 the user has entered an address into the search field and chosen the address from the returned results the user clicks on the address marker on the map (orange marker with a star) the user selects an apartment from the list of apartments the user checks the option other, enters the flat number into the opened box and presses the OK button the user clicks on the map on the location, where one object is found the user clicks on the map on the location, where there are several objects of the same type, the user selects the desired object and presses the choose address button. The structure of output JSON object varies, depending on the chosen priority of search. The possible search priorities are: address-based search - the value of input parameter searchlayers is empty and the search result displays found addresses object-based search - the value of input parameter searchlayers is set and the result displays address objects Output of object-based search In case of object-based search and selection of object on the map JSON object has the following structure: { "aadress": "Harju maakond, Tallinna linn, Põhja- Tallinna linnaosa, Kolde pst 8", "paadress": "Kolde pst 8, Põhja-Tallinna linnaosa, Tallinna linn, Harju maakond", "lahiaadress": "Kolde pst 8", "liik": "EE", "orig_tunnus": "EE ", "ads_oid": "EE ", "koodaadress": " CW000061FK ", "ehak": "0614", "ehakov": "0784", "ehakmk": "0037", ESTONIAN LAND BOARD

24 "adob_id": " ", "adr_id": " ", "un_tunnus": "1", "x": "539625", "y": " ", "b": " ", "l": " ", "kood4": "0000", "kood5": "04CW", "kood6": "0000", "kood7": "61FK", "maakond": "Harju maakond", "omavalitsus": "Tallinn", "asustusyksus": "Põhja-Tallinna linnaosa", "vaikekoht": "", "liikluspind": "Kolde pst", "nimi": "", "aadress_nr": "8", "paralleelaadress": "Harju maakond, Tallinna linn, Põhja-Tallinna linnaosa, Kolde pst 8//Harju maakond, Tallinna linn, Põhja-Tallinna linnaosa, Kolde pst 10", "seotud": [ { "aadress": "Harju maakond, Tallinna linn, Põhja-Tallinna linnaosa, Kolde pst 10", "paadress": "Kolde pst 10, Põhja-Tallinna linnaosa, Tallinna linn, Harju maakond", "lahiaadress": "Kolde pst 10", "liik": "EE", "orig_tunnus": "EE ", "koodaadress": " CW000061FK ", "ehak": "0614", "ehakov": "0784", "ehakmk": "0037", "ads_oid": "EE ", "adob_id": " ", ESTONIAN LAND BOARD

25 } ] }, "adr_id": " ", "un_tunnus": "1", "x": "539625", "y": " ", "b": " ", "l": " ", "kood4": "0000", "kood5": "04CW", "kood6": "0000", "kood7": "61FJ", "maakond": "Harju maakond", "omavalitsus": "Tallinn", "asustusyksus": "Põhja-Tallinna linnaosa", "vaikekoht": "", "liikluspind": "Kolde pst", "nimi": "", "aadress_nr": "6" When also apartment search is allowed and the user has searched an apartment, the output includes apartment data. Example: { "aadress": "Harju maakond, Tallinna linn, Mustamäe linnaosa, Mustamäe tee 161-7", "paadress": "Mustamäe tee 161-7, Mustamäe linnaosa, Tallinna linn, Harju maakond", "lahiaadress": "Mustamäe tee 161-7", "liik": "ER", "kort_nr": "7", "orig_tunnus": " ", "koodaadress": " JVC00003DGJ ", "ehak": "0482", "ehakov": "0784", ESTONIAN LAND BOARD

26 } "ehakmk": "0037", "ads_oid": "ER ", "adob_oid": " ", "adr_id": " ", "hoone_ads_oid": "EE ", "un_tunnus": "1", "x": "538903", "y": " ", "b": " ", "l": " ", "kood4": "0000", "kood5": "0JVC", "kood6": "0000", "kood7": "3DGJ", "kood8": "AM84", "maakond": "Harju maakond", "omavalitsus": "Tallinn", "asustusyksus": "Mustamäe linnaosa", "vaikekoht": "", "liikluspind": "Mustamäe tee", "nimi": "", "aadress_nr": "161" Unlike the building, there is an additional field kort_nr containing apartment number. Additionally, just like in case of building, there may be fields paralleelaadress, provided there are several apartments with the same ads_oid value. In case entering of new apartments is enabled and the user has entered a new apartment, which does not exist in ADS, the output displays the selected building s data and the entered apartment is in the field kort_nr. Besides, there is a field uus_kort with value true, which defines that it is an apartment nonexisting in ADS. Example: { "aadress": "Harju maakond, Tallinna linn, Mustamäe ESTONIAN LAND BOARD

27 linnaosa, Mustamäe tee 161", "paadress": "Mustamäe tee 161, Mustamäe linnaosa, Tallinna linn, Harju maakond", "lahiaadress": "Mustamäe tee 161", "liik": "EE", "kort_nr": "999", "uus_kort": "true", "orig_tunnus": " ", "koodaadress": " JVC00003DGJ ", "ehak": "0482", "ehakov": "0784", "ehakmk": "0037", "ads_oid": "EE ", "adob_oid": " ", "adr_id": "220380", "un_tunnus": "1", "x": "538903", "y": " ", "b": " ", "l": " ", "kood4": "0000", "kood5": "0JVC", "kood6": "0000", "kood7": "3DGJ", "kood8": "undefined", "maakond": "Harju maakond", "omavalitsus": "Tallinn", "asustusyksus": "Mustamäe linnaosa", "vaikekoht": "", "liikluspind": "Mustamäe tee", "nimi": "", "aadress_nr": "161" } Descriptions of properties Property Description aadress Full address of object ESTONIAN LAND BOARD

28 paadress Full address of object in reversed order lahiaadress Proximate address of object liik Code of object type in ADS information system orig_tunnus Object identifier ads_oid Value of address object identifier (throughout all versions) adr_id Technical identifier of address in ADS adob_id Value of address object identifier hoone_ads_oid When the found object is part of building (apartment), this parameter shows the ads_oid value of the building in which the given part of building is located. un_tunnus Indicates whether the object has a uniqueness requirement. kort_nr Apartment number uus_kort An apartment non-existing in ADS. koodaadress Code made of codes of address classifiers ehak Code of settlement unit ehakov Code of local government ehakmk Code of county kood4 Code of territorial unit kood5 Code of traffic space kood6 Code of name kood7 Code of address number kood8 Code of apartment number maakond Name of county omavalitsus Name of local government asustusüksus Name of settlement unit vaikekoht Name of territorial unit liikluspind Name of traffic space nimi Name aadress_nr Address number X x coordinate of object s reference point Y y coordinate of object s reference point B Geographic coordinate of object s reference point north latitude L Geographic coordinate of object s reference point east longitude ESTONIAN LAND BOARD

29 mapx When the user clicked on the map and selected an object, the output includes the chosen location s x coordinate mapy When the user clicked on the map and selected an object, the output includes the chosen location s y coordinate paralleelaadress In case of a parallel address (in output there are more than one object with the same ADS_OID value), the value is parallel address (separated by a double-slash // ). When there is only one object, the parameter is omitted. seotud The rest of objects with the same ADS_OID value. When there is only one object, the parameter is omitted Output of address-based search In case of address-based search the JSON object has the following structure: { [{ "aadress": "Harju maakond, Tallinna linn, Mustamäe linnaosa, Ehitajate tee 5", "paadress": "Ehitajate tee 5, Mustamäe linnaosa, Tallinna linn, Harju maakond", "lahiaadress": "Ehitajate tee 5", "liik": "EE", "orig_tunnus": "EE ", "koodaadress": " JYH00000NH ", "ehak": "0482", "ehakov": "0784", "ehakmk": "0037", "ads_oid": "EE ", "adob_oid": " ", "adr_id": "292266", "un_tunnus": "1", "primary":"true" "x": "538124", "y": " ", "b": " ", "l": " ", ESTONIAN LAND BOARD

30 }, { "kood4": "0000", "kood5": "0JYH", "kood6": "0000", "kood7": "0NH4", "maakond": "Harju maakond", "omavalitsus": "Tallinn", "asustusyksus": "Mustamäe linnaosa", "vaikekoht": "", "liikluspind": "Ehitajate tee", "nimi": "", "aadress_nr": "5" "aadress": "Harju maakond, Tallinna linn, Mustamäe linnaosa, Ehitajate tee 5", "paadress": "Ehitajate tee 5, Mustamäe linnaosa, Tallinna linn, Harju maakond", "lahiaadress": "Ehitajate tee 5", "liik": "EE", "orig_tunnus": "EE ", "koodaadress": " JYH00000NH ", "ehak": "0482", "ehakov": "0784", "ehakmk": "0037", "ads_oid": "EE ", "adob_oid": " ", "adr_id": "292266", "un_tunnus": "1", "x": "538168", "y": " ", "b": " ", "l": " ", "kood4": "0000", "kood5": "0JYH", "kood6": "0000", "kood7": "0NH4", ESTONIAN LAND BOARD

31 "maakond": "Harju maakond", "omavalitsus": "Tallinn", "asustusyksus": "Mustamäe linnaosa", "vaikekoht": "", "liikluspind": "Ehitajate tee", "nimi": "", "aadress_nr": "5", "seotud": [ { "aadress": " Harju maakond, Tallinna linn, Mustamäe linnaosa, Ehitajate tee 6", "paadress": "Ehitajate tee 6, Mustamäe linnaosa, Tallinna linn, Harju maakond", "lahiaadress": "Ehitajate tee 6", "liik": "EE", "orig_tunnus": "EE ", "koodaadress": " JYH00000NH ", "ehak": "0482", "ehakov": "0784", "ehakmk": "0037", "ads_oid": "EE ", "adob_oid": " ", "adr_id": " ", "un_tunnus": "1", "x": "538168", "y": " ", "b": " ", "l": " ", "kood4": "0000", "kood5": "0JYH", "kood6": "0000", "kood7": "0NH4", "maakond": "Harju maakond", "omavalitsus": "Tallinn", "asustusyksus": "Mustamäe linnaosa", "vaikekoht": "", ESTONIAN LAND BOARD

32 ] "liikluspind": "Ehitajate tee", "nimi": "", "aadress_nr": "6" }, }, { "aadress": "Harju maakond, Tallinna linn, Mustamäe linnaosa, Ehitajate tee 5", "paadress": "Ehitajate tee 5, Mustamäe linnaosa, Tallinna linn, Harju maakond", "lahiaadress": "Ehitajate tee 5", "liik": "EE", "orig_tunnus": "EE ", "koodaadress": " JYH00000NH ", "ehak": "0482", "ehakov": "0784", "ehakmk": "0037", "ads_oid": "EE ", "adob_oid": " ", "adr_id": "292266", "un_tunnus": "1", "x": "538162", "y": " ", "b": " ", "l": " ", "kood4": "0000", "kood5": "0JYH", "kood6": "0000", "kood7": "0NH4", "maakond": "Harju maakond", "omavalitsus": "Tallinn", "asustusyksus": "Mustamäe linnaosa", "vaikekoht": "", "liikluspind": "Ehitajate tee", "nimi": "", ESTONIAN LAND BOARD

33 } "aadress_nr": "5" }] When also apartment search is allowed and the user has searched an apartment, the output includes apartment data similar to the object-based search. The output of address-based search consists of an array, which contains one or more output objects of the object-based search. However, when the user selects the object on the map, the structure of output is object-based (see Output of object-based search). Descriptions of properties Property Description aadress Full address of object paadress Full address of object in reversed order lahiaadress Proximate address of object liik Code of object type in ADS information system orig_tunnus Object identifier ads_oid Value of address object identifier (throughout all versions) adob_id Value of address object identifier adr_id Technical identifier of address in ADS hoone_ads_oid When the main data are apartment s data, this parameter shows the ads_oid value of the building. un_tunnus Indicates whether the object has a uniqueness requirement. kort_nr Apartment number uus_kort An apartment non-existing in ADS. koodaadress Code made of codes of address classifiers ehak Code of settlement unit ehakov Code of local government ehakmk Code of county kood4 Code of territorial unit kood5 Code of traffic space kood6 Code of name kood7 Code of address number ESTONIAN LAND BOARD

34 kood8 Code of apartment number maakond Name of county omavalitsus Name of local government asustusüksus Name of settlement unit vaikekoht Name of territorial unit liikluspind Name of traffic space nimi Name aadress_nr Address number primary Shows whether the object is of the highest priority (it can be also several objects). X x coordinate of object s reference point Y y coordinate of object s reference point B Geographic coordinate of object s reference point north latitude L Geographic coordinate of object s reference point east longitude mapx When the user clicked on the map and selected an object, the output includes the chosen location s x coordinate mapy When the user clicked on the map and selected an object, the output includes the chosen location s y coordinate paralleelaadress In case of a parallel address (in output there are more than one object with the same ADS_OID value), the value is parallel address (separated by a double-slash // ). When there is only one object, the parameter is omitted. seotud The rest of objects with the same ADS_OID value. When there is only one object, the parameter is omitted. 6. In-ADS editor API The In-ADS widget can also be used as a simple map editor tool. For this purpose instead of the script inaadress.min.js the script editor.min.js shall be used. <script type="text/javascript" src=" ></script> ESTONIAN LAND BOARD

35 6.1 Drawing and editing This component enables drawing of simple shapes on the map. By activating the editor, additional buttons for drawing and editing will be displayed on the map (one tool button is displayed, by hovering the mouse over it, two buttons will appear, or three - when measuring is also in use). With the input parameter drawing it is possible to set the drawing button to be turned on by default while activating the editor. The input parameter geomtype defines which type of features (point, line, polygon) are allowed to be added (value can be set to only one of them), the parameter multigeom defines whether drawing of multipoint, multiline or multipolygon features is allowed or not. The parameter format defines in what format geometry will be kept (values GML, KML or GeoJSON) and the parameter editstyle defines the style of the feature to be edited. In drawing mode points can be added on the map. A double-click will end drawing. After drawing has been completed, the event featureadded together with the drawn shape and current BBOX will be passed to the external system. By selecting the editing tool, it is possible to edit the existing features. In case of multigeometry, after choosing the feature it will be possible to add points (by grabbing a virtual point between two points and dragging the new point to a desired location), to modify (by dragging the existing point), to delete (by hovering the mouse over the point and pressing delete key or by clicking on the point, which opens a dialogue box and then pressing yes button), or to move the shape (by grabbing the red point in the middle of the shape and moving it to a desired place) and to rotate (by grabbing the red point in the shape s bottom right corner and rotating the shape). Each modification triggers the event featuremodified, which together with geometry is passed to the external system. 6.2 Redisplay of existing shape on the map To display the existing shape as editable on the map, the In-ADS editor has an input parameter geomobject, which provides the geometry and, if desired, also alpha-numeric data of the object to be edited in GML, KML or GeoJSON formats. In case when multiple geometry objects are given, only the first one is used and others will be ignored. Further, the styling will be supplied by populating the ESTONIAN LAND BOARD

36 editstyle parameter (see 6.3 Style) and geometry by populating the format parameter (see 6.1 Drawing and editing). In KML or GeoJSON formats style can be contained also in geomobject data and there is no need to use the editstyle parameter. If GML, KML or GeoJSON text data contain the name field, its value will be displayed on the map into a tooltip. All text data that the object had in its input data will be returned to the external system unchanged. By default the map window will zoom to the object, but optionally also the BBOX extent could be given instead. When the editor component has already been created, the object to be edited can be set with the function setgeomobject(geomobject, fit). Calling this function will remove the previous editable object and replace it with a new one, the fit parameter sets whether to fit the object in the map window or not. Calling this function will automatically change the value of the geomtype parameter according to the type of geometry of the object that was loaded into the In-ADS editor. 6.3 Style For styling the In-ADS editor has an input parameter editstyle, which defines the style of the object to be edited. The following attributes can be set: stroke width, stroke colour, stroke opacity, fill colour and fill opacity. In case of a point feature the icon s url, its height and width and x,y offsets from point can be set. In KML format the following descriptions are supported: LineStyle, PolyStyle and IconStyle along with the attributes strokecolor, strokewidth, fillcolor. In case of icon elements thefollowing attributes are supported: scale, href (icon s url), hotspot (icon s positioning), w (width) and h (height). In GeoJSON format style can be set with the object features parameter style. The following attributes are supported: fill, fill-opacity, stroke, stroke-opacity, stroke-width, marker, marker-width, marker-height, marker-x and marker-y. 6.4 Input description For the creation of the In-ADS editor, JavaScript object configuring the mode of operation and functionality of the editor must be supplied. This section lists ESTONIAN LAND BOARD

37 only the input parameters that are related to the editor. All input parameters of the In-ADS widget are valid also for the editor, except that of mode, which need not to be included and the default value of which is 1. If the parameter is provided, the value options are 1, 2 or 4. The object may have the following properties: Property Description Compulsory format In which format geometry is kept. Possible Yes values are: GML, GeoJSON or KML geomtype Which type of geometries can be drawn. no Possible values are: point, line or polygon. Without value drawing and editing are not allowed multigeom Are multipoint, multiline or multipolygon no geometries allowed. When value is true, allowed, false not allowed. drawing Is the drawing tool by default turn on. By no default false. editstyle Style of editable object. Value is the object with parameters fillcolor, fillopacity, strokecolor, strokeopacity, strokewidth. In case of point object the icon object with parameters externalgraphic, graphicwidth, no graphicheight, graphicxoffset and graphicyoffset geomobject This parameter is for displaying the existing no object on the map and editing it. Value is data in KML, GML or GeoJSON format. vectorobjects With this parameter vector objects to be no displayed to the background layer can be supplied. Value is the object with parameters features and style mode In which mode the In-ADS editor operates. Possible values: 1 address search with a map, 2 address search with a map (by default hidden), 4 only map. Default value is 1 no ESTONIAN LAND BOARD

38 noinfo When value is set to true, the information query button will not be displayed on the map. noaddressmapselect When value is set to true, addresses cannot be selected by clicking on the map labelmode Whether to display the value of attribute name (if existing) as a tooltip, which will be displayed with mouse over the object, or as a label, which is visible all the time. Default value is tooltip no no no Example: creation of editor in editing mode: var editor = new InAadressEditor({ "container": "inaadresseditor", "searchlayers": ["EHAK", "TANAV", "KATASTRIYKSUS", "EHITISHOONE"], "appartment": 2, "defaultbaselayer": "ALUSKAART", "baselayers": ["ALUSKAART", "ORTOFOTO", "HYBRIID"], "maplayers": ["KATASTRIYKSUS"], "format": "GeoJSON", "drawing": true, "geomtype": "polygon", "multigeom": false, "editstyle": { "fillcolor": "#FF0000", "fillopacity": "0.5", "strokecolor": "#000000", "strokeopacity": "0.9", "strokewidth": "2" } }); Example: creation of editor with the existing object: var editor = new InAadressEditor({ "container": "inaadresseditor", "searchlayers": ["EHAK", "KATASTRIYKSUS", ESTONIAN LAND BOARD

39 "EHITISHOONE"], "appartment": 1, "defaultbaselayer": "ALUSKAART", "baselayers": ["ALUSKAART", "HYBRIID"], "maplayers": ["KATASTRIYKSUS"], "format": "GeoJSON", "drawing": true, "geomtype": "point", "multigeom": false, "editstyle": { "icon": { "url": " "width": "5", "height": "5", "offsetx": "2.5", "offsety": "5" } }, "geomobject":'{ "type": "Feature","crs": {"type": "EPSG","properties": {"code": 3301}}, "geometry": { "type": "Point", "coordinates": [ , ] }, "properties": { "id": " ", "name": "Rapla maakond, Juuru vald" } } ' }); Example: creation of editor with the existing object and background objects: var editor = new InAadressEditor({ "container": "inaadresseditor", "searchlayers": ["EHAK", "KATASTRIYKSUS", "EHITISHOONE"], "defaultbaselayer": "ALUSKAART", "baselayers": ["ALUSKAART", "HYBRIID"], "maplayers": ["KATASTRIYKSUS"], "format": "KML", "drawing": true, ESTONIAN LAND BOARD

40 "geomtype": "point", "multigeom": false, "editstyle": { "icon": { "url": " "width": "5", "height": "5", "offsetx": "2.5", "offsety": "5" } }, "geomobject": '<kml xmlns=" ark><name>in-ads objekt</name><description></description><polygon><outer BoundaryIs><LinearRing><coordinates> , , , , , , , </coordinates></Lin earring></outerboundaryis></polygon></placemark></folde r></kml>', "vectorobjects": { "style": { "fillcolor": "#FFDD00", "fillopacity": ".3", "strokecolor": "#DDCC00", "strokeopacity": "1", "strokewidth": "3", "icon": { "url": " "width": "12", "height": "24", ESTONIAN LAND BOARD