Yandex.Maps API
Guide to the YMapsML language
15.05.2015
Yandex.Maps API. Guide to the YMapsML language. Version 1.0
Document build date: 15.05.2015.
This volume is a part of Yandex technical documentation.
Yandex helpdesk site: http://help.yandex.ru
© 2008—2015 Yandex LLC. All rights reserved.
Copyright Disclaimer
Yandex (and its applicable licensor) has exclusive rights for all results of intellectual activity and equated to them means of individualization, used for development, support,
and usage of the service Yandex.Maps API. It may include, but not limited to, computer programs (software), databases, images, texts, other works and inventions, utility models,
trademarks, service marks, and commercial denominations. The copyright is protected under provision of Part 4 of the Russian Civil Code and international laws.
You may use Yandex.Maps API or its components only within credentials granted by the Terms of Use of Yandex.Maps API or within an appropriate Agreement.
Any infringements of exclusive rights of the copyright owner are punishable under civil, administrative or criminal Russian laws.
Contact information
Yandex LLC
http://www.yandex.com
Phone: +7 495 739 7000
Email: [email protected]
Headquarters: 16 L'va Tolstogo St., Moscow, Russia 119021
Contents
Overview .............................................................................................................................................................................................. 4
GML, YMapsML and KML ................................................................................................................................................................ 4
YMapsML usage .................................................................................................................................................................................. 4
Structure of YMapsML ..................................................................................................................................................................... 8
Geographical objects and collections ......................................................................................................................................... 10
Metadata ..................................................................................................................................................................................... 12
Geometric and geographical data ............................................................................................................................................... 13
Representation of maps and objects on a map ........................................................................................................................... 13
Map parameters .................................................................................................................................................................................. 14
Rendering geographical objects ...................................................................................................................................................... 18
Setting geometric and geographical data ................................................................................................................................... 18
Setting the visual appearance of displayed objects ............................................................................................................... 20
Styles .................................................................................................................................................................................. 20
Templates ........................................................................................................................................................................... 23
Yandex.Maps API
Guide to the YMapsML language
Guide to the YMapsML language 4
Overview
YMapsML (Yandex Maps Markup Language) is a language developed by the company Yandex for describing
geographical data. The term "geographical data" refers to any data that is geographically connected with a place.
YMapsML is used as the format for transferring data between Yandex.Maps services and third-party software.
Data in YMapsML format can be displayed on Yandex.Maps, and the geocoding service uses the same format
for returning information about the location of objects.
YMapsML is an open XML format; the formal specification (schema) is available at http://maps.yandex.ru/
schemas/ymaps-1.x/ymaps.xsd, and a description is provided in the YMapsML Reference. For editing data
in YMapsML format, you can use any text editor; for processing data, choose from the wide variety of software
available for working with XML.
GML, YMapsML and KML
The industry standard for describing geographical data is GML — Geographic Markup Language. GML is
developed and maintained by the OGC (Open Geospatial Consortium) and is an international ISO standard.
The first version of the language was released in 2000, and the third, most recent version, in 2007.
GML contains a large number of elements and geographical objects can be described in great detail. However,
the price to be paid for universality is a complex language, a significant amount of data to transfer, and more
computing resources.
There are two main ways to adapt GML to specific tasks: profiling, and developing “application schemas”. With
the first method, the necessary subset of elements is pulled out of the GML schema using GML's own resources.
With the second method, a new schema is created that contains its own elements along with GML elements.
The first method is for creating simpler versions of GML, while the second is for creating formats that
are optimized for particular tasks.
Recently, KML (Keyhole Markup Language) has become more popular as a language for describing
geographical data; it was developed by the company Keyhole for the Keyhole Earth Viewer. In 2004, Google
acquired Keyhole, and Keyhole Earth Viewer was renamed Google Earth.
KML is not an application schema or a GML profile; the KML specification is defined by its native schema.
This schema borrows several elements from GML that describe the geometry of geographical objects. KML is
used as a geographical data format for Google Earth and the Google Maps services.
Parallel to the development of KML, which was a closed format until recently, Yandex was developing
the YMapsML language as a GML application schema for its own geoinformation services. In 2008, KML was
published as an OGC standard. In the same year, the YMapsML specification and the Yandex.Maps API were
published, enabling the use of this language when accessing Yandex geoinformation services.
When compared with KML, the distinctive features of YMapsML are its simplicity and better stylization, which
uses a system of styles and templates to define the visual appearance of objects being displayed. The simplicity
of YMapsML is due to the lack of three-dimensional descriptions of geographical data (KML is used in Google
Earth, which works with 3D models).
Data in YMapsML format is handled correctly by most software that works with the third version of GML.
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.
Yandex.Maps API
Guide to the YMapsML language
Guide to the YMapsML language 5
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,
for example, based on the information contained in a 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. Exporting information from user maps in the My Maps service.
The My maps service gives users the opportunity to create and save personal maps that display sections
of an area with markers placed on them.
3. 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.
4. 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 Gaia, Mapserver, or OpenLayers.
5. 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, let's examine a basic YMapsML file. We will make this file accessible over HTTP, for example,
at the address http://api.yandex.com.tr/maps/ymapsml/examples/xml/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>
Yandex.Maps API
Guide to the YMapsML language
Guide to the YMapsML language 6
<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>
The file contains information about the geographical object where Mikhail Bulgakov's novel begins. 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 (http://api.yandex.com.tr/maps/ymapsml/examples/
intro.html).
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://
www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<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.0/?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("/maps/doc/ymapsml/1.x/examples/xml/
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 are loaded, the load method transforms
them into a GeoObjectCollection object and passes the object reference to the handler function.
When viewed in a browser, this page will look like this:
Yandex.Maps API
Guide to the YMapsML language
Guide to the YMapsML language 7
Yandex.Maps API
Guide to the YMapsML language
8
Structure of YMapsML
YMapsML documents consist of elements belonging to five namespaces: http://maps.yandex.ru/ymaps/1.x,
http://maps.yandex.ru/representation/1.x, http://www.opengis.net/gml, http://maps.yandex.ru/attribution/1.x
and http://www.w3.org/2005/Atom. We will assume that the prefixes ymaps, repr, gml, attr and atom
correspond to these namespaces, and we will be identifying the namespaces by their prefixes.
The table below shows the original namespaces:
Namespace
Schema URL
Definition
ymaps
http://maps.yandex.ru/ymaps/1.x
A language for representing
geographical data in the form of abstract
geographical objects and collections.
gml
http://www.opengis.net/gml
GML – the geography description
standard.
repr
http://maps.yandex.ru/representation/
1.x
Contains rules for displaying
geographical objects on Yandex maps.
attr
http://maps.yandex.ru/attribution/1.x
Contains details on who provided
information about an organization that
is shown on Yandex maps.
atom
http://www.w3.org/2005/Atom
Atom is a syndication format
for describing sets of web resources.
Each YMapsML element contains either one or more elements from the specified namespaces, or text, which
in any case can include HTML code. HTML markup is always “shown on the screen”, meaning it is displayed
as text in the browser. The exception is HTML code that is contained in the gml:description and repr:text elements
located inside repr:Template. This code is interpreted by the browser and rendered as formatted text.
Let's look at the structure of a YMapsML document.
Yandex.Maps API
Guide to the YMapsML language
9
The root element of a document is the ymaps:ymaps element. It can contain attr:Attribution elements,
one ymaps:GeoObjectCollection element and one repr:Representation element. Any of these elements may be
omitted, or even all three may be omitted. The last case is a bit exotic. An “empty” document is usually used
as a draft to be filled in later.
The top-level ymaps:GeoObjectCollection element is a container for all the geographical objects and their
collections that are included in the document. The repr:Representation element is used for defining the visual
appearance of these objects, as well as for setting map parameters. The attr:Attribution element contains details
on who provided information about an organization that is shown on Yandex maps.
The YMapsML document that is provided as an example in the section YMapsML usage contains
the ymaps:GeoObjectCollection element, but does not contain the repr:Representation element. This means that
Yandex.Maps API
Guide to the YMapsML language
10
when displaying this document via the JavaScript API, the map display parameters and the visual appearance
of geographical objects will be determined automatically.
Geographical objects and collections
To describe geographical objects in YMapsML, we use the ymaps:GeoObject element. A population
of geographical objects can be put together in a collection, using the ymaps:GeoObjectCollection element
to describe it.
To provide compatibility with the GML standard, each of these elements is wrapped in one of the container
elements — gml:featureMember or gml:featureMembers. The only exception is the
ymaps:GeoObjectCollection element, which is located in the ymaps:ymaps root element.
The difference between these containers consists of the following. The gml:featureMember element can contain
either a single object description (ymaps:GeoObject), or a single collection description
(ymaps:GeoObjectCollection). The gml:featureMembers element can contain any number of descriptions
of geographical objects or collections.
The structure of a ymaps:GeoObject element containing a description of a geographical object appears as follows.
Yandex.Maps API
Guide to the YMapsML language
11
Yandex.Maps API
Guide to the YMapsML language
12
The geographical object can be matched to the following data:
1. Metadata.
2. Geometric and geographical data.
3. Information about the visual representation of a geographical object.
4. Information about who provided data about an organization.
Collections can be used to group together both geographical objects and collections themselves. Considering
the information above that ymaps:GeoObject and ymaps:GeoObjectCollection elements are enclosed
in gml:featureMember and gml:featureMembers containers, the structure of the ymaps:GeoObjectCollection
elements will look rather predictable.
Metadata
When working with geographical objects and collections, it is often helpful to give them names and descriptions
and supply them with other additional information. Any data that describes geographical objects or groups
of them and is not related to geometric or geographical data will be referred to as metadata.
Yandex.Maps API
Guide to the YMapsML language
13
The following elements are provided for placing metadata about geographical objects and collections
in YMapsML:
1. gml:name — Name of a geographical object or collection.
2. gml:description — Description of a geographical object or collection. May contain HTML code.
Restrictions on using HTML code in the gml:description element are the same as the restrictions that
apply to using HTML code in templates.
3. gml:metaDataProperty — Any other metadata in XML format describing a geographical object
or collection. The gml:metaDataProperty element contains ymaps:AnyMetaData, where data
is placed.
Geometric and geographical data
The following elements are used for describing geometric properties of objects and their geographical coordinate
positioning:
1. gml:Point — Geometric point. It is used in cases when the shape and size of a geographical object are not
important. The position of the point is set using geographical coordinates.
2. gml:LineString — Polyline (line). Defined by setting the geographical coordinates of its points.
3. gml:LinearRing — Closed polyline (line). Defined by setting the geographical coordinates of its points. It is
automatically closed by connecting the first and last points.
4. gml:Polygon — Polygon. A shape that has closed polylines for both its interior and exterior edges. It is
defined by setting the geographical coordinates of the points on the polylines that make up the polygon
boundaries. All polylines are automatically closed by connecting the first and last points.
Note:
The GML standard assumes that the first and last points of closed polylines are the same. Automatically closing
polylines is a feature of the Yandex.Maps JavaScript API.
All the elements listed can be displayed using built-in tools in the JavaScript API.
Another type of geographical data is a polygon outline. A polygon outline of an object or collection is a polygon
that has a geographical object (or all the objects in a collection) inside it.
To create this type of polygon, the gml:boundedBy element is used. If this element is located inside
the ymaps:GeoObject and ymaps:GeoObjectCollection elements, it is purely informative and does not directly
affect the display of objects on the map. If the gml:boundedBy element is inside the repr:View element,
it determines the map viewport.
Representation of maps and objects on a map
YMapsML has elements that let you define map parameters and the visual appearance of objects displayed on a
map.
To set map parameters, the repr:View element is used. You can use it to set the map type and viewport.
When displaying YMapsML via the JavaScript API, each geographical object that has geographical
and geometric data specified is represented by one or more visual objects: markers, polylines or polygons.
The visual appearance of geographical objects is preset, but you can change it by using styles and templates.
Styles let you define or redefine certain parameters for displaying geographical objects, as well as create custom
HTML representations using templates. To set styles, the repr:Style element is used; for templates,
the repr:Template element is used.
Yandex.Maps API
Guide to the YMapsML language
Guide to the YMapsML language 14
Map parameters
You can use YMapsML to set the map type and viewport. The repr:View element is intended for this.
The Yandex.Maps API supports showing three built-in types of maps:
•
MAP — “Roadmap” map type. Schematic view of the objects in an area. Used by default.
•
SATELLITE — “Satellite” map type. A satellite map of the area.
•
HYBRID — “Hybrid” map type. Satellite map of an area with names of geo objects overlayed on it.
The repr:mapType element can contain one of the map type identifiers provided in the list.
The map viewport is a rectangular area that is defined by setting the coordinates of the upper and lower points.
To set the viewport for a map, the gml:boundedBy element is used.
Consider the following example. We'll put all the map types that are supported by the service on the HTML
page for the map — “roadmap”, “satellite” and “hybrid” — and set a viewport for each of them.
maptypes.html (http://api.yandex.com.tr/maps/ymapsml/examples/maptypes.html)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://
www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>YMapsML examples. Map parameters</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<script src="http://api-maps.yandex.ru/2.0/?load=package.full&lang=en-US"
type="text/javascript"></script>
<script language="JavaScript" type="text/javascript">
window.onload = function () {
ymaps.ready(function() {
// The "Map" map type
var mapMap = new ymaps.Map('mapTypeId', {
center: [39.92751, 32.86437],
zoom: 8
});
ymaps.geoXml.load("/maps/doc/ymapsml/1.x/examples/xml/
maptype.xml")
.then(function (res) {
if (res.mapState) {
// Changes the map parameters
res.mapState.applyToMap(mapMap);
}
});
// The "Satellite" map type
var mapSatellite = new ymaps.Map('satelliteTypeId', {
center: [39.92751, 32.86437],
zoom: 8
});
ymaps.geoXml.load("/maps/doc/ymapsml/1.x/examples/xml/
satellitetype.xml")
Yandex.Maps API
Guide to the YMapsML language
Guide to the YMapsML language 15
.then(function (res) {
if (res.mapState) {
// Changes the map parameters
res.mapState.applyToMap(mapSatellite);
}
});
// The "Hybrid" map type
var mapHybrid = new ymaps.Map('hybridTypeId', {
center: [39.92751, 32.86437],
zoom: 8
});
ymaps.geoXml.load("/maps/doc/ymapsml/1.x/examples/xml/
hybridtype.xml")
.then(function (res) {
if (res.mapState) {
// Changes the map parameters
res.mapState.applyToMap(mapHybrid);
}
});
});
}
</script>
</head>
<body>
<div id="mapTypeId" style="width:640px; height:400px;"></div>
<div id="satelliteTypeId" style="width:315px; height:200px; float: left;
margin: 10px 10px 0 0"></div>
<div id="hybridTypeId" style="width:315px; height:200px; float: left; margin:
10px 0 0 0"></div>
</body>
</html>
maptype.xml (http://api.yandex.com.tr/maps/ymapsml/examples/xml/maptype.xml)
<?xml version="1.0" encoding="UTF-8"?>
<ymaps:ymaps
xmlns:ymaps="http://maps.yandex.ru/ymaps-1.x"
xmlns:gml="http://
www.opengis.net/gml">
<repr:Representation xmlns:repr="http://maps.yandex.ru/representation-1.x">
<repr:View>
<repr:mapType>MAP</repr:mapType>
<gml:boundedBy>
<gml:Envelope>
<gml:upperCorner>32.765636 39.978172</gml:upperCorner>
<gml:lowerCorner>32.95927 39.89288</gml:lowerCorner>
</gml:Envelope>
</gml:boundedBy>
</repr:View>
</repr:Representation>
</ymaps:ymaps>
satellitetype.xml (http://api.yandex.com.tr/maps/ymapsml/examples/xml/satellitetype.xml)
Yandex.Maps API
Guide to the YMapsML language
Guide to the YMapsML language 16
<?xml version="1.0" encoding="UTF-8"?>
<ymaps:ymaps
xmlns:ymaps="http://maps.yandex.ru/ymaps-1.x"
xmlns:gml="http://
www.opengis.net/gml">
<repr:Representation xmlns:repr="http://maps.yandex.ru/representation-1.x">
<repr:View>
<repr:mapType>SATELLITE</repr:mapType>
<gml:boundedBy>
<gml:Envelope>
<gml:upperCorner>32.823858 39.951596</gml:upperCorner>
<gml:lowerCorner>32.893553 39.916715</gml:lowerCorner>
</gml:Envelope>
</gml:boundedBy>
</repr:View>
</repr:Representation>
</ymaps:ymaps>
hybridtype.xml (http://api.yandex.com.tr/maps/ymapsml/examples/xml/hybridtype.xml)
<?xml version="1.0" encoding="UTF-8"?>
<ymaps:ymaps
xmlns:ymaps="http://maps.yandex.ru/ymaps-1.x"
xmlns:gml="http://
www.opengis.net/gml">
<repr:Representation xmlns:repr="http://maps.yandex.ru/representation-1.x">
<repr:View>
<repr:mapType>HYBRID</repr:mapType>
<gml:boundedBy>
<gml:Envelope>
<gml:upperCorner>32.823858 39.951596</gml:upperCorner>
<gml:lowerCorner>32.893553 39.916715</gml:lowerCorner>
</gml:Envelope>
</gml:boundedBy>
</repr:View>
</repr:Representation>
</ymaps:ymaps>
When viewing the maptypes.html file in a browser, the map will look as follows.
Yandex.Maps API
Guide to the YMapsML language
Guide to the YMapsML language 17
Yandex.Maps API
Guide to the YMapsML language
18
Rendering geographical objects
The Yandex.Maps service lets you put visual objects on maps: geo objects (markers, polylines and polygons),
as well as balloons and popup hints.
All YMapsML elements that are for describing geometric and geographical data have visual representations
and are displayed using geo objects.
The table shows the relationship between YMapsML elements and geo objects.
YMapsML element and corresponding geometric Geo object and its name
shape
gml:Point
ymaps.Placemark
geometric point
marker
gml:LineString
ymaps.Polyline
polyline
polyline
gml:LinearRing
ymaps.Polyline
closed polyline
polyline
gml:Polygon
ymaps.Polygon
polygon
polygon
Setting geometric and geographical data
The section Geometric and geographical data lists the elements that are used for defining geometric properties
of geographical objects. Each element corresponds to a geometric shape and a geo object that is used
for displaying this shape on the map.
The geometric shape is bound to a locality by setting the coordinates of corresponding points. For a geometric
point, its coordinates are set; for a polyline, the coordinates of its points; for a polygon, the coordinates of the
points of the closed polylines that make up its exterior and interior edges.
The coordinates of points and polyline points are set using the gml:pos and gml:posList elements. To specify
coordinates that define the viewport or a polygon outline, the gml:lowerCorner and gml:upperCorner elements
are used.
To set the coordinates of a point, its longitude and latitude are listed in order and separated by a space.
For example, <gml:pos>55.0298 82.9197</gml:pos>. This is how coordinates are set for points that
are described using the gml:pos, gml:lowerCorner and gml:upperCorner elements. When setting coordinates
for a sequence of points using the gml:posList element, pairs of point coordinates are separated by a space in the
same way. For example, <gml:posList>55.0298
82.9197
55.0496
82.9694</
gml:posList>.
Polyline and closed polyline
To set the points of a polyline, either two or more gml:pos elements or the gml:posList element can be used.
<ymaps:GeoObject>
<gml:name>Polyline</gml:name>
<gml:description>The coordinates for points on a polyline can be defined using
two or more gml:pos elements</gml:description>
<gml:LineString>
<gml:pos>32.199411 58.601185</gml:pos>
<gml:pos>32.189411 58.595185</gml:pos>
</gml:LineString>
</ymaps:GeoObject>
Example:
Yandex.Maps API
Guide to the YMapsML language
19
YMapsML file: http://api.yandex.com.tr/maps/ymapsml/examples/xml/linestring.xml.
HTML page: http://api.yandex.com.tr/maps/ymapsml/examples/linestring.html.
<ymaps:GeoObject>
<gml:name>Closed polyline</gml:name>
<gml:description>The coordinates for points on a polyline can also be defined
using the gml:posList element</gml:description>
<gml:LinearRing>
<gml:posList>37.178027 55.486953 38.040535 55.486953 38.040535 56.018499
37.178027 56.018499</gml:posList>
</gml:LinearRing>
</ymaps:GeoObject>
Example:
YMapsML file: http://api.yandex.com.tr/maps/ymapsml/examples/xml/linearring.xml.
HTML page: http://api.yandex.com.tr/maps/ymapsml/examples/linearring.html.
Polygon
The exterior boundary of a polygon consists of a closed polyline, which is described using
the gml:LinearRing element.
<ymaps:GeoObject>
<gml:name>Polygon</gml:name>
<gml:description>The exterior boundary of a polygon consists of a closed
polyline</gml:description>
<gml:Polygon>
<gml:exterior>
<gml:LinearRing>
<gml:posList>37.178027 55.486953 38.040535 55.486953 38.040535
56.018499 37.178027 56.018499</gml:posList>
</gml:LinearRing>
</gml:exterior>
</gml:Polygon>
</ymaps:GeoObject>
In this example, the gml:LinearRing element is located inside the gml:exterior container. This reflects the fact
that a polygon can have not only an exterior edge, but an interior edge as well (a "hole" inside the polygon).
In addition, the number of interior holes is unlimited.
The interior boundary of a polygon is also set using a closed polyline. The gml:LinearRing element is wrapped
in the gml:interior container. In the current version of the Yandex.Maps API, the contents of the gml:interior
element are not interpreted. A feature for processing interior edges of polygons is planned for one of the
upcoming versions of the API.
Example:
YMapsML file: http://api.yandex.com.tr/maps/ymapsml/examples/xml/polygon.xml.
HTML page: http://api.yandex.com.tr/maps/ymapsml/examples/polygon.html.
Viewport and polygon outline
The viewport and polygon outline of a geographical object or collection are described using
the gml:boundedBy element. These areas are defined by setting the point coordinates of the lower left and upper
right corners.
To set point coordinates for the lower left corner, the gml:lowerCorner element is used, and for the upper right
corner, the gml:upperCorner element is used.
Yandex.Maps API
Guide to the YMapsML language
20
<ymaps:GeoObject>
<gml:name>Polyline</gml:name>
<gml:description>A polygon outline can be set for a geographical object or
collection</gml:description>
<gml:boundedBy>
<gml:Envelope>
<gml:lowerCorner>45 60</gml:lowerCorner>
<gml:upperCorner>30 50</gml:upperCorner>
</gml:Envelope>
</gml:boundedBy>
<gml:LineString>
<gml:pos>32.199411 58.601185</gml:pos>
<gml:pos>32.189411 58.595185</gml:pos>
</gml:LineString>
</ymaps:GeoObject>
An example of setting the viewport on a map is provided in the section Map parameters.
Setting the visual appearance of displayed objects
YMapsML lets you determine the visual appearance of objects displayed on a map. Since visualization
of YMapsML elements is performed using geo objects that have a preset appearance, we are basically talking
about changing the standard method of displaying geo objects.
To change the visual appearance of displayed objects via YMapsML, styles are used. Styles let you set certain
parameters for displaying geo objects and create a custom HTML representation using templates.
To define styles, the repr:Style element is used; for templates, the repr:Template element is used. To specify
which style should be applied when displaying a geographical object or collection, use the ymaps:style element.
<ymaps:GeoObject>
<gml:style>#customStyle</gml:name>
<gml:Point>
<gml:pos>27.431259 38.621162</gml:pos>
</gml:Point>
</ymaps:GeoObject>
Here, #customStyle is a link to the ID of the repr:Style element that contains the style description. The link
to the style ID is always prefixed by the “#” symbol.
The link can reference a style located not only in the current file, but also in external YMapsML files that can be
accessed over HTTP. In this case, the link to the style has the format <YMapsML file URL>#<template
ID or inherited style ID>.
<repr:style>
http://api.yandex.com.tr/maps/ymapsml/examples/xml/
overlays_styles.xml#manisa
</repr:style>
An example of loading a style from an external file is provided on the http://api.yandex.com.tr/maps/ymapsml/
examples/ page.
When defining a geographical object or collection, you can link to a style, but not to a template; in other words,
it is incorrect to link to the repr:Templateelement. Templates are used to define the HTML representation of geo
objects that use styles. Techniques for using templates are described in the section Templates.
Styles
Styles are used for changing the parameters of the standard representation of geo objects. For example, you can
set the thickness of polyline lines or the fill color for polygons.
styles.html (http://api.yandex.com.tr/maps/doc/doc/jsapi/2.x/examples/ymapsml/styles.html)
Yandex.Maps API
Guide to the YMapsML language
21
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://
www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>YMapsML examples. Using styles</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<script src="http://api-maps.yandex.ru/2.0/?load=package.full&lang=en-US"
type="text/javascript"></script>
<script language="JavaScript" type="text/javascript">
window.onload = function () {
ymaps.ready(function () {
var myMap = new ymaps.Map('map', {
center: [39.919948, 32.868109],
zoom: 16
});
// Calls a callback function after the YMapsML data is loaded
ymaps.geoXml.load("/maps/doc/ymapsml/1.x/examples/xml/
styles.xml")
.then(function (res) {
// Adds a collection of geo objects to the map
myMap.geoObjects.add(res.geoObjects);
}, function (error) {
alert("Error when loading styles: " +
error);
});
});
}
</script>
</head>
<body>
<div id="map" style="width:640px; height:400px;"></div>
</body>
</html>
styles.xml (http://api.yandex.com.tr/maps/doc/ymapsml/1.x/examples/xml/styles.xml)
<?xml version="1.0" encoding="UTF-8"?>
<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">
<repr:Representation>
<repr:Style gml:id="customStyle">
<repr:lineStyle>
<repr:strokeColor>FF9911</repr:strokeColor>
<repr:strokeWidth>7</repr:strokeWidth>
</repr:lineStyle>
</repr:Style>
<repr:Style gml:id="customStyle1">
<repr:parentStyle>#customStyle</repr:parentStyle>
<repr:lineStyle>
<repr:strokeColor>FF0000</repr:strokeColor>
</repr:lineStyle>
</repr:Style>
</repr:Representation>
<ymaps:GeoObjectCollection>
<gml:name>A polyline and its style</gml:name>
<gml:featureMembers>
<ymaps:GeoObject>
<gml:name>Route</gml:name>
<gml:description>A route shown as a polyline</gml:description>
<gml:LineString>
<gml:pos>32.86689 39.920241</gml:pos>
<gml:pos>32.867639 39.919722</gml:pos>
<gml:pos>32.868598 39.919121</gml:pos>
Yandex.Maps API
Guide to the YMapsML language
22
<gml:pos>32.868802 39.919052</gml:pos>
<gml:pos>32.869596 39.918895</gml:pos>
<gml:pos>32.870851 39.918681</gml:pos>
<gml:pos>32.871474 39.918595</gml:pos>
</gml:LineString>
<ymaps:style>#customStyle1</ymaps:style>
</ymaps:GeoObject>
</gml:featureMembers>
</ymaps:GeoObjectCollection>
</ymaps:ymaps>
When viewed in a browser, the styles.htm file will look as follows.
Each type of geo object has its own YMapsML element (child of the repr:Style element) that is used for setting
its display parameters. So, for example, to set display parameters for polylines and closed polylines,
the repr:lineStyle element is used, while for markers, the repr:iconStyle or repr:iconContentStyle elements
are used.
Element defining a geo object
Elements that define the appearance of geo objects,
as well as balloons and hints
gml:Point — Geometric point. Displayed using a marker
repr:iconStyle — Marker icon parameters
repr:iconContentStyle — Marker icon content
repr:hintContentStyle — Link to a template that defines
the contents of a popup hint that appears when hovering over
the marker with the mouse
repr:ballonContentStyle — Link to a template that defines
the contents of a balloon that appears when clicking on the
marker
gml:LineString — Polyline
repr:lineStyle — Line parameters
repr:hintContentStyle — Link to a template that defines
the contents of a popup hint that appears when hovering over
the line with the mouse
repr:ballonContentStyle — Link to a template that defines
the contents of a balloon that appears when clicking on the
line
Yandex.Maps API
Guide to the YMapsML language
23
Element defining a geo object
Elements that define the appearance of geo objects,
as well as balloons and hints
gml:LinearRing — Closed polyline
repr:lineStyle — Parameters of a line that connects the points
of a polyline
repr:hintContentStyle — Link to a template that defines
the contents of a popup hint that appears when hovering over
the closed polyline with the mouse
repr:ballonContentStyle — Link to a template that defines
the contents of a balloon that appears when clicking on the
closed polyline
gml:Polygon — Polygon
repr:polygonStyle — Parameters of closed polylines that
define the boundaries of a polygon and its background color
repr:hintContentStyle — Link to a template that defines
the contents of a popup hint that appears when hovering over
the polygon with the mouse
repr:ballonContentStyle — Link to a template that defines
the contents of a balloon that appears when clicking on the
polygon
YMapsML supports style inheritance. This makes it possible for a style to use parameters and templates defined
earlier in a different style. To indicate an inherited style, the repr:parentStyle element is used.
<repr:Style gml:id="styleHospital">
<repr:parentStyle>#commonStyle</repr:parentStyle>
</repr:Style>
An example of style inheritance is provided on the http://api.yandex.com.tr/maps/doc/ymapsml/1.x/examples/
page.
Styles can link to templates. If a style links to a template, the parameters that are set in it do not affect the visual
appearance of the object being displayed using this style. However, these parameters can be used in the template
itself. A link to a template is set using the repr:template element.
<repr:Style gml:id="offices">
<repr:balloonContentStyle>
<repr:template>#balloonTemplate</repr:template>
</repr:balloonContentStyle>
</repr:Style>
The template and inherited style can be located not only in the current file, but also in external YMapsML files
that can be accessed over HTTP. In this case, the link to them has the format <YMapsML file
URL>#<template ID or inherited style ID>.
<repr:template>
http://api.yandex.com.tr/maps/ymapsml/examples/xml/
ballooncontentstyle.xml#balloonTemplate
</repr:template>
or
<repr:parentStyle>
http://api.yandex.com.tr/maps/ymapsml/examples/xml/
ballooncontentstyle.xml#offices
</repr:parentStyle>
Templates
Templates are used for generating custom HTML representations of geo objects, balloons and hints. For example,
if you need to display markers using not only an image with a shadow, but with text as well, you will need
to construct an appropriate template for the text and enable it in the style that is used for displaying markers.
Yandex.Maps API
Guide to the YMapsML language
24
To define the template, use the repr:Template element, which contains the HTML code (the template body)
inside the repr:text container.
<repr:Template gml:id="hintTemplate">
<repr:text><div style="color:blue">Hint</div></repr:text>
</repr:Template>
In many cases, the style does not allow you to change the visual appearance of an object in any other way, besides
using a template (for example, see repr:balloonContentStyle).
The template is an integral part of the style that the geographical object or collection references.
When using a template, the value of any XML element that is located inside a ymaps:GeoObject
or ymaps:GeoObjectCollection element can be accessed by calling the corresponding variable.
To define variables, use strings of the type $[variable_name|default_value].
The variable name is the location of this XML element inside the element that the style is applied to. The location
is set by listing in order the names of all the parent elements and the name of the element itself; a dot is used
as a separator.
Let's assume that the description of the geographical object looks like this:
<GeoObject>
<gml:name>Yandex office on Samokatnaya street</gml:name>
<gml:metaDataProperty>
<AnyMetaData>
<address>1 Samokatnaya Street, building 21, Moscow, 111033</address>
<phone>+7 495 739-70-00</phone>
<fax>+7 495 739-70-70</fax>
</AnyMetaData>
</gml:metaDataProperty>
<gml:Point>
<gml:pos>37.678514 55.758255</gml:pos>
</gml:Point>
</GeoObject>
Then the balloon template that displays the name of the object, the address, and the phone number of the office,
might look like this:
<Template gml:id="balloonTemplate">
<text>
<div style="font-size:12px;">
<div style="color:#ff0303;font-weight:bold">$[name]</div>
<div>Address: $[metaDataProperty.AnyMetaData.address]</div>
<div>Telephone: $[metaDataProperty.AnyMetaData.phone|none]</div>
<text>
</Template>
If the office phone is not specified (i.e. delete the "phone" element from the example provided), the string “none”
will be displayed in place of the phone number.
There are several rules restricting the use of certain HTML elements and attributes in template text. The list
of restrictions is provided in the following table.
Restrictions on HTML usage in templates
Script and iframe elements are ignored
Any script and iframe elements are removed together with
their contents.
Example:
<div><script>alert(\"XSS\")"</script></div>
is replaced with
<div />
Yandex.Maps API
Guide to the YMapsML language
25
Attributes that are responsible for calling event handlers Attributes that are responsible for calling event handlers
are ignored
(onclick, onchange, onkeypress, etc.) are removed from
elements together with their contents.
Example:
<div onclick="alert(\"XSS\")">$[name]</div>
is replaced with
<div>$[name]</div>
The class attribute is ignored
The class attribute is removed from elements together with
its contents.
Example:
<div class="login">$[name]</div>
is replaced with
<div>$[name]</div>
The schema must be defined in the href attribute of the link If the link URL does not specify the schema (protocol) or uses
URL; the javascript schema is ignored
the javascript schema, the href attribute is removed together
with its contents.
Example:
<a
href="$
[metaDataProperty.AnyMetaData.test.a]">link
</a>
is replaced with
<a>link</a>
The "position:absolute" property for the "style" attribute If the "style" attribute contains the "position:absolute"
is ignored
property, this property is removed.
Example:
<div
div>
style="position:absolute">$[name]</
is replaced with
<div>$[name]</div>
CSS expressions are ignored
Yandex.Maps API
If the "style" attribute contains CSS expressions (only
supported by Internet Explorer up to version 8), it is removed
together with its contents.
Guide to the YMapsML language
Yandex.Maps API
Guide to the YMapsML language
15.05.2015