YMapsML usage

YMapsML is an open, documented and simple XML language for describing geographical data. The Yandex.Maps JavaScript API provides ways to automatically load information from YMapsML files and display it on a map.

Yandex projects that involve cartographic services use this format to exchange data. The Yandex.Maps geocoding service accepts calls over the HTTP protocol and returns the response in YMapsML format.

Based on the information provided here, we can define the main uses for YMapsML:

  1. Generating a YMapsML file and displaying the information contained in it via the JavaScript API.

    Creating a YMapsML file is easy — just use any text editor to enter the necessary information in accordance with the language specification. To get an idea of what a YMapsML file looks like, see the examples provided in this guide. These examples are convenient to use as starting points for your own experiments.

    Of course, manual editing of YMapsML files is fairly rare. The files are usually generated automatically based on information contained in the database. YMapsML is an XML format. Almost all modern programming languages and development environments include tools for presenting data in XML. So automatic generation of YMapsML files is not a particularly difficult task.

    Currently, a large amount of geographical data is presented in XML formats. This can be shown by the large number of languages that are GML application schemas or profiles. It doesn't require much effort to display this type of data on Yandex.Maps — it is sufficient to convert them to YMapsML format (for example, using XSLT).

    On the Examples page you can see an example of Yandex.Maps displaying earthquake information, where the earthquake data is originally supplied in GeoRSS format. YMapsML is used as a transitional format that is easy to convert GeoRSS feeds to.

  2. Getting information from the geocoding service via HTTP request.

    The geocoding service can determine the coordinates of a geographical object and get information about it, based on its name or address. And vice-versa, the address of an object on a map can be determined by its coordinates — reverse geocoding.

    Results are returned in YMapsML format. This means that objects that are found can immediately be placed on Yandex.Maps. In addition, the resulting data is easy to analyze visually or extract using software.

  3. Displaying geographical data in YMapsML by third-party geoinformation services.

    Since YMapsML is a standard GML application schema, data in this format can be displayed and processed using software that supports GML version 3, such as Mapserver and OpenLayers.

  4. Using YMapsML as a storage format for geographical data.

    YMapsML can be used when geographical data needs to be in a format that is convenient for both use and storage. Geographical data is often stored in databases, or in the internal notation of various software.

    If it is necessary to make reserve copies or transfer data to “external” programs, the issue arises of choosing a format for representing the information. In this case, YMapsML could be the right decision. Data in this format is easy to analyze visually, and can be processed by the Yandex.Maps API as well as software that supports GML 3.x.

As an example, look at a basic YMapsML file named intro.xml:
<?xml version="1.0" encoding="windows-1251"?>
<ymaps:ymaps xmlns:ymaps="http://maps.yandex.ru/ymaps/1.x" xmlns:repr="http://maps.yandex.ru/representation/1.x" xmlns:gml="http://www.opengis.net/gml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maps.yandex.ru/schemas/ymaps/1.x/ymaps.xsd">
    <ymaps:GeoObjectCollection>
        <gml:name>Mosques</gml:name>
        <gml:featureMembers>
            <ymaps:GeoObject>
                <gml:name>Sultan Ahmed Mosque</gml:name>
                <gml:description>The Sultan Ahmed Mosque is popularly known as the Blue Mosque for the blue tiles adorning the walls of its interior.</gml:description>
                <gml:Point>
                    <gml:pos>28.976896 41.005346</gml:pos>
                </gml:Point>
            </ymaps:GeoObject>
        </gml:featureMembers>
    </ymaps:GeoObjectCollection>
</ymaps:ymaps>

This file contains information about the geographical object Sultan Ahmed Mosque. The position of the object is marked on the map by a dot with the specified geographical coordinates.

To display the information, we will use the JavaScript API, which has built-in tools for displaying YMapsML files. To do this, we create the following HTML page:
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>YMapsML Examples. Displaying a geographical object</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <script src="http://api-maps.yandex.ru/2.1/?load=package.full&lang=en-US" type="text/javascript"></script>
    <script type="text/javascript">
         window.onload = function () {
             ymaps.ready(function () {
                 var myMap = new ymaps.Map('map', {
                     center: [41.010993, 28.966627],
                     zoom: 8
                 });
          //After the data in the YMapsML file is loaded, a callback function is called 
                ymaps.geoXml.load("intro.xml")
                            .then(function (res) {
          //Add a collection of geo objects to the map  
                                 myMap.geoObjects.add(res.geoObjects);
                             }, function (error){   // Called if the YMapsML file failed to load
                alert('Error: ' + error);
            });
        });
         }     
    </script>
</head>
<body>
    <div id="map" style="width:600px;height:400px"></div>
</body>
</html>

To load the YMapsMl file, the load method is used. After the data is loaded, the load method transforms it into a GeoObjectCollection object and passes the object reference to the handler function.

When viewed in a browser, this page will look like this: