1. No category

Yandex.Maps Static API
Developer's guide
15.05.2015
Yandex.Maps Static API. Developer's guide. 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 Static 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 Static API or its components only within credentials granted by the Terms of Use of Yandex.Maps Static 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: pr@yandex-team.ru
Headquarters: 16 L'va Tolstogo St., Moscow, Russia 119021
Contents
About this document ............................................................................................................................................................................ 4
Overview of the Static API .................................................................................................................................................................. 4
Map center ........................................................................................................................................................................................... 5
Map size ............................................................................................................................................................................................... 6
Viewport .............................................................................................................................................................................................. 7
Zoom level ........................................................................................................................................................................................... 8
Map layers and types ........................................................................................................................................................................... 9
Traffic ................................................................................................................................................................................................ 12
Placemarks ......................................................................................................................................................................................... 12
Lines and polygons ............................................................................................................................................................................ 16
Automatic map positioning ................................................................................................................................................................ 20
Map localization ................................................................................................................................................................................. 22
Index .................................................................................................................................................................................................. 23
Yandex.Maps Static API
Developer's guide
Developer's guide
About this document
This guide is a detailed reference for the Yandex.Maps Static API. It explains the flow for working with the API,
summarizes all the URL parameters, and describes each parameter in detail with working examples.
The guide is intended for website developers who want to use static images from Yandex.Maps on their
web pages.
Overview of the Static API
The Static API generates a map image based on the parameter values passed to the service in a URL with
the following format:
http://static-maps.yandex.ru/1.x/?lang=en-US&{URL parameters}
The substring {URL parameters} contains a sequence of pairs in the format {parameter
name}={parameter value}, separated by the ampersand symbol (&).
The following example is a request for a map image of the center of Ankara with two numbered markers:
http://static-maps.yandex.ru/1.x/?lang=en-US&ll=32.810152,39.889847& \
size=450,450&z=10&l=map&pt=32.810152,39.889847,pm2rdl1~32.870152,39.869847,pm2rd
l99
Attention!
Line breaks in the examples are indicated with backslash symbols ( \ ), which you should remove when copying
the examples into your web page HTML code or your browser address string.
The complete list of URL parameters is shown below.
Parameter
Data type and example
Description
l
string,[string]...
List of layers that define the type of map: map (roadmap), sat
(satellite) and sat,skl (hybrid). Mandatory parameter. For more
information, see Map layers and types.
l=map
Yandex.Maps Static API
Developer's guide
4
Developer's guide
Parameter
Data type and example
Description
ll
float,float
Longitude and latitude of the map center in degrees; see Map
center.
ll=32.810152,39.889847
spn
float
spn=0.01,0.01
z
integer
Range of the map's viewport by longitude and latitude (in degrees);
see Viewport.
Zoom level of the map (0-17); see Zoom level.
z=10
size
integer,integer
size=450,450
pt
Height and width of the requested map image (in pixels); see Map
size.
string
Contains definitions of one or more markers to be displayed on the
(MarkerDefinition1~Mark map.
erDefinition2~...)
Each marker definition contains its coordinates (longitude
pt=32.810152,39.889847,pm and latitude) along with information on its appearance (including
2rdl1~32.870152,39.869847 style, color, size and the marker text). Marker definitions
,pm2rdl99
are separated by a tilda (~).
For more information, see Placemarks.
pl
string
Contains definitions of geometric figures (polylines and polygons)
(FigureDefinition1~Figu to display on the map.
reDefinition2~...)
The figure definition contains coordinates for its points (either
a comma-separated list, or encoded), along with information on line
pl=c:ec473fFF,f:
00FF00A0,w:5, \
color and thickness, and the fill color (for polygons). Figure
37.51,55.83,37.67,55.82,3 definitions are separated by a tilda (~).
7.66,55.74, \
37.49,55.70,37.51,55.83
lang
string (languageregion)
lang=en-US
For more information, see Lines and polygons
Locale.
•
language — Two-letter language code. Specified in ISO
639-1 format.
•
region — Two-letter country code. Specified in ISO
3166-1 format.
The following locales are currently supported:
•
lang=ru-RU
•
lang=tr-TR
•
lang=en-US
For more information, see Map localization.
Map center
The center of the map image is set in the ll parameter. Its longitude and latitude (in degrees) are set off by
commas in the parameter. The ll parameter is used either with the spn parameter (viewport), or with the z
parameter (zoom level).
Yandex.Maps Static API
Developer's guide
5
Developer's guide
Tip:
1. The map center usually shows a specific object of interest (building, city, etc.). To find an object's
geographical coordinates by its address or name, you can use the Yandex.Maps geocoding service.
2. On the Yandex.Maps page the browser address bar shows a URL with the necessary parameters
for displaying the map fragment that you see on the screen. These parameters include the coordinates of the
object found via search (the sll parameter), the coordinates of the map center (the ll parameter), and the
map viewport (the spn parameter). You can use the values of these parameters to request a static image
of a map fragment.
Attention!
If the ll parameter is not set, the Static API automatically positions the map.
The request example below is for a map image centered at 6. Sokak, Ehlibeyt, Çankaya, Ankara. The values
for the map center and the viewport were determined using Yandex.Maps (the query "6. Sokak, Ehlibeyt,
Çankaya, Ankara").
http://static-maps.yandex.ru/1.x/?lang=en-US&ll=32.810152,39.889847 \
&spn=0.016457,0.00619&l=map
Map size
The size of the map display is set using the size parameter, where the height and width of the map (in pixels)
are separated by a comma. The maximum size allowed for the map display is 650x450 pixels.
The examples below show requests for maps sized 450x150 and 200x200 pixels, centered on Istanbul with
a zoom level of z=9:
http://static-maps.yandex.ru/1.x/?lang=en-US&ll=28.98824,41.043451&z=9&l=map \
&size=450,150
Yandex.Maps Static API
Developer's guide
6
Developer's guide
http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98824,41.043451&z=9&l=map \
&size=200,200
Viewport
The viewport is the minimal area shown surrounding the map center. The viewport is set using the spn
parameter, using a comma to set off its range, which is specified by longitude and latitude (in degrees).
The Static API selects the appropriate zoom level so that the entire specified area is visible on the image.
Attention!
If the spn parameter is not set, and the zoom level is not set explicitly, the Static API attempts to set the omitted
parameters automatically.
Examples
The examples below show map image requests that differ from each other only by the viewport size (0.02x0.02,
0.3x0.3 and 10x10 degrees). The requested map fragment is centered on Taksim Meydanı in Istanbul, and the
map size is 300x300 pixels.
Viewport of 0.02x0.02 degrees:
http://static-maps.yandex.ru/1.x/?lang=enUS&ll=28.98513,41.036943&spn=0.002,0.002 \
&size=300,300&l=map
Viewport of 0.3x0.3 degrees:
Yandex.Maps Static API
Developer's guide
7
Developer's guide
http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98513,41.036943&spn=0.3,0.3
\
&size=300,300&l=map
Viewport of 10x10 degrees:
http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98513,41.036943&spn=10,10 \
&size=300,300&l=map
Zoom level
The zoom level determines the current resolution of the image from the map. In the Static API, the zoom level
is set by the z parameter, which can take whole values from 0 to 17. At the zero zoom level, the map shows
the entire world, while at the maximum zoom level, it shows a single building.
When the zoom level is increased by a single level, the image resolution doubles; for more information,
see Coordinates and projections.
Note:
If the request specifies a viewport (the spn parameter), the zoom level is ignored.
Attention!
Not all zoom levels are available in all areas of the map. If the requested zoom level is not available for the
selected area, the map will not be returned.
The example below is a request for a map image with zoom level 12, centered on Sultanahmet Camii:
http://static-maps.yandex.ru/1.x/?lang=en-US&ll=28.97709,41.005233&z=12 \
&size=450,450&l=map
Yandex.Maps Static API
Developer's guide
8
Developer's guide
The following example is a request for the same map, but with the maximum zoom level (17):
http://static-maps.yandex.ru/1.x/?lang=enUS&ll=28.97709,41.005233&z=17&size=450,450&l=map
Map layers and types
The map image consists of one or more layers overlaid on each other. The list of layers is set in the "l" parameter
(the bottom layer should be listed first).
Layer
Image format
Description
map
PNG
Map of an area with names
of geographical objects.
sat
JPG
A satellite photo of the area.
skl
PNG
Names of geographical objects.
trf
PNG
Traffic jams layer.
Yandex.Maps Static API
Developer's guide
9
Developer's guide
Layers can be combined. The available map types ("Roadmap," "Satellite" or "Hybrid") each correspond to a
layer or specific combination of layers:
•
map — "Roadmap" map type.
•
sat — "Satellite" map type.
•
sat, skl — "Hybrid" map type.
Examples for each map type are provided below:
Roadmap (l=map)
Map of the center of Istanbul:
http://static-maps.yandex.ru/1.x/?lang=en-US&ll=28.98824,41.043451 \
&spn=0.1,0.1&l=map
Roadmap showing traffic (l=map,trf,skl)
Roadmap of the center of Istanbul showing traffic:
http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98824,41.043451 \
&spn=0.1,0.1&l=map,trf,skl
Yandex.Maps Static API
Developer's guide
10
Developer's guide
Satellite (l=sat)
Satellite map of the center of Istanbul:
http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98824,41.043451 \
&spn=0.1,0.1&l=sat
Hybrid (l=sat,skl)
Hybrid map of the center of Istanbul (the map framework is on the "satellite" layer):
http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98824,41.043451 \
&spn=0.1,0.1&l=sat,skl
Hybrid map showing traffic (l=sat,trf,skl)
Hybrid map of the center of Istanbul showing traffic:
http://static-maps.yandex.ru/1.x/lang=en-US&?ll=28.98824,41.043451 \
&spn=0.1,0.1&l=sat,trf,skl
Yandex.Maps Static API
Developer's guide
11
Developer's guide
Traffic
In addition to the standard map types, you can add an additional traffic layer to a map to show traffic levels in a
city.
To display the traffic layer, specify trf in the list of layers in the l parameter.
Example roadmap of the center of Ankara with a traffic layer:
http://static-maps.yandex.ru/1.x/?lang=en-US&ll=32.84243,39.948244 \
&spn=0.1,0.1&l=map,trf
Placemarks
The pt parameter is for displaying one or more placemarks (up to 100) on the map image:
pt=PlacemarkDefinition1~PlacemarkDefinition2~PlacemarkDefinition3...
Yandex.Maps Static API
Developer's guide
12
Developer's guide
Each placemark definition contains its coordinates (longitude and latitude) along with information on its
appearance (including style, color, size and content of the placemark). The placemark definition uses
the following pattern:
{longitude},{latitude},{style}{color}{size}{content}
Rules for designating placemarks:
Style
Color
pm
Description
Size:
wt — white
do — dark orange
•
s — small
•
m — medium
•
l — large
Content:
db — dark blue
bl — blue
•
For the sizes s and m, a number from
1 to 99.
•
For the l size, a number from 1 to
100.
gn — green
gr — grey
lb — light blue
nt — night
or- orange
pn — pink
rd — red
vv — violet
yw — yellow
a — with the letter "A" (without specifying content or size)
b — with the letter "B" (without specifying content or size)
Yandex.Maps Static API
Developer's guide
13
Developer's guide
Style
Color
Description
Size:
pm2
wt — white
•
m — medium
•
l — large
Content:
do — dark orange
Number from 1 to 99.
db — dark blue
bl — blue
gn — green
dg — dark green
gr — grey
lb — light blue
nt — night
or- orange
pn — pink
rd — red
vv — violet
yw — yellow
a — with the letter "A" (without specifying content)
Yandex.Maps Static API
Developer's guide
14
Developer's guide
Style
Color
Description
b — with the letter "B" (without specifying content)
org — blue (without specifying content)
dir — violet (without specifying content)
blyw — blue with a yellow dot
flag
— flag.
vk
Size:
m — medium
bk- black button
Content is not specified.
gr — grey button
Note:
By
(
default,
a
white
medium-sized
placemark
is
used
pmwtm
).
Example
The request example below is for an image of a map fragment with placemarks of various styles, colors and sizes:
http://static-maps.yandex.ru/1.x/?lang=en-US&l=map& \
pt=28.98624,41.043451~28.95624,41.043451,78~28.94114,41.043451, \
pmgrs~28.98124,41.043451,pm2rdm~28.97624,41.043451, \
pmntl100~28.965573,41.04311,pmors23~28.950111,41.043451, \
flag~28.969573,41.04311,pm2ywl99
Yandex.Maps Static API
Developer's guide
15
Developer's guide
If the placemark coordinates fall outside of the specified viewport, the placemark is not shown on the map.
The placemark will also not be shown if the text has invalid symbols (anything other than numbers from 1 to
99).
See also
Automatic map positioning
Lines and polygons
Polylines and polygons can be used on a static map to mark a route or the boundaries of an object.
A polyline consists of a set of points connected by straight line segments. A polyline can cross itself. If the
coordinates of the first and last points are the same, the polyline is called a closed polyline.
A polygon is set using one or more closed polylines.
Restriction:
The Static API allows displaying no more than 5 polylines and polygons on a map at once, and the total number
of points on figures cannot be more than 100.
The outward appearance of a geometric figure is set using a special definition. The polyline definition contains
information about the thickness and color of lines, while the polygon definition contains information about
the thickness and color of the outline and the fill color (see below).
The points on all figures are assigned geographical coordinates.
The point coordinates and the outward appearance of polylines and polygons are set using the pl parameter.
This parameter contains definitions for all the figures displayed on the map. Figure definitions are separated
by a tilda (~):
pl = FigureDefinition1~FigureDefinition2~FigureDefinition3
The polyline definition has the following format:
c:{line color},w:{thickness},{points}
The polygon definition can additionally contain the fill color (the f parameter):
Yandex.Maps Static API
Developer's guide
16
Developer's guide
c:{line color},f:{fill color},w:{thickness},{points}
Line color
An RGBA hex string (0xFFFFFFFF format) represents the line color. The first 6 symbols set the RGB color,
and the next two set the line transparency. The transparency value has a range from 00 (transparent) to FF
(opaque).
For example:
c:8822DDC0
Polygon fill color
Uses the same format as the polyline color (see above). For example:
f:00FF00A0
The even-odd rule is used for filling a polygon. This means that a point is filled in if a ray drawn from that point
to infinity has an odd number of intersections with the edges of the polygon.
An area where several polygons intersect is always filled in.
Thickness
Line thickness (in pixels).
w:8
Note:
If color and thickness are not set, a light violet semitransparent line with a thickness of 5 pixels is used
(8822DDC0).
Points
The
point
coordinates
of
a
polyline
are
set
Longitude1,Latitude2,...,LongitudeN,LatitudeN.
in
the
following
way:
The point coordinates of a polygon created by a single closed polyline are set in the same way.
To define a polygon using a set of closed polylines, a semicolon must be used to separate the sequence of points
for each polyline: PolylinePointCoordinates1;...PolylinePointCoordinates2.
Examples
•
Polyline
•
Polygon defined by a single polyline
•
Polygon defined by a set of polylines
•
Intersecting polygons
Polyline
The request example below is for a map fragment of Izmir with an image of the pedestrian route from
the "Çankaya" metro station to the Turkiye Tarim Kredi Kooperatifleri building. The polyline points are set by a
list of point coordinates, and the default color and thickness are used:
Yandex.Maps Static API
Developer's guide
17
Developer's guide
http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \
&pl=27.135483,38.422478,27.137685,38.422469,27.137736,38.422564,27.137789,38.424
045,27.138519,38.423975,27.141899,38.423802, \
27.142215,38.423756,27.142333,38.423697,27.142376,38.423549, \
27.142596,38.423368,27.142971,38.423347,27.143285,38.423625, \
27.143245,38.423912,27.143015,38.424102,27.142795,38.424128, \
27.142795,38.424128,27.142387,38.423918,27.141909,38.423918, \
27.138275,38.42422
Polygon defined by a single polyline
The request example below is for a map fragment of Izmir with the walls of the "İzmir Fuarı" marked on it.
It uses a polygon with a red outline and light green semitransparent fill to define the boundaries of the fortress:
http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \
&pl=c:ec473fFF,f:00FF00A0,w:7,27.14325,38.43178, \
27.14855,38.430419,27.149794,38.428225,27.147327,38.425693, \
27.147305,38.424562,27.143142,38.424089,27.141426,38.427853, \
27.14325,38.43178
Yandex.Maps Static API
Developer's guide
18
Developer's guide
Polygon defined by a set of polylines
The example below is for a map that displays a polygon defined by a set of polylines. The polyline point
coordinates are separated by a semicolon.
http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \
&pl=f:30d5c844,w:7,29.085258,41.018105,29.100278, \
41.016024,29.097618,41.007508,29.086545,41.009978, \
29.085258,41.018105;29.089893,41.014724,29.096759, \
41.013814,29.096158,41.010303,29.091009,41.011669, \
29.089893,41.014724
Intersecting polygons
The example below is for a map that displays two intersecting polygons. The set of parameters for each polygon
is separated by a tilda (~).
The area where the polygons intersect is filled in.
http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \
&pl=f:2222DDC0,c:003399,29.088504,41.052278,29.097001,\
41.042141,29.08756,41.044935,29.088504,41.052278~ \
c:00ff0055,f:3caa3c77,29.100434,41.048444,29.086187, \
41.04643,29.089791,41.042076,29.100434,41.048444
Yandex.Maps Static API
Developer's guide
19
Developer's guide
See also
Automatic map positioning
Automatic map positioning
If the map image has at least one placemark or geometric figure (polyline or polygon), the viewport can be
automatically selected, even if the URL does not specify values for the map center (ll parameter), the viewport
(spn parameter), or the zoom level (z parameter). The Static API selects values for the omitted parameters
so that all placemarks, polylines and polygons are visible on the map.
If there is only one placemark set, it will be the center of the map; if a single polyline or polygon is set, the map
center will be the geometric center of the area that is formed by the points of this polyline or polygon.
The example below shows a request for a map fragment of Ankara that has a pedestrian path drawn on it from
from the "Çankaya" metro station to the Turkiye Tarim Kredi Kooperatifleri building (there are placemarks
at the beginning and end of the route). The request does not specify the ll, z or spn parameters:
http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \
&pt=27.135483,38.422478,pm2am~27.138275,38.42422, \
pm2bm&pl=27.135483,38.422478,27.137685,38.422469, \
27.137736,38.422564,27.137789,38.424045,27.138519, \
38.423975,27.141899,38.423802,27.142215,38.423756, \
27.142333,38.423697,27.142376,38.423549,27.142596, \
38.423368,27.142971,38.423347,27.143285,38.423625, \
27.143245,38.423912,27.143015,38.424102,27.142795, \
38.424128,27.142795,38.424128,27.142387,38.423918, \
27.141909,38.423918,27.138275,38.42422
Yandex.Maps Static API
Developer's guide
20
Developer's guide
If we add another placemark to the map, for example, at the Kadifekale a different map center and zoom level
will be selected:
http://static-maps.yandex.ru/1.x/?lang=en-US&l=map \
&pt=27.135483,38.422478,pm2am~27.138275,38.42422, \
pm2bm~27.14316,38.416435,pm2vvl&pl=27.135483,38.422478, \
27.137685,38.422469,27.137736,38.422564,27.137789, \
38.424045,27.138519,38.423975,27.141899,38.423802, \
27.142215,38.423756,27.142333,38.423697,27.142376, \
38.423549,27.142596,38.423368,27.142971,38.423347, \
27.143285,38.423625,27.143245,38.423912,27.143015, \
38.424102,27.142795,38.424128,27.142795,38.424128, \
27.142387,38.423918,27.141909,38.423918,27.138275,38.42422
See also
Placemarks
Lines and polygons
Yandex.Maps Static API
Developer's guide
21
Developer's guide
Map localization
The Static.API lets you make localized map images with labels in different languages. To set the language
for geo object names on a map, you need to pass the locale in the HTTP request.
The locale is set in RFC-3066 format using the lang parameter:
lang=language-region
•
language — Two-letter language code. Specified in ISO 639-1 format.
•
region — Two-letter country code. Specified in ISO 3166-1 format.
The following locales are currently supported:
•
lang=ru-RU
•
lang=tr-TR
•
lang=en-US
Note:
Turkish on geo object labels is currently supported only for maps of Turkey.
The example below is for a map of Moscow with labels in Russian:
http://static-maps.yandex.ru/1.x/?lang=ru-RU&l=map&ll=37.620070,55.753630&z=10
Yandex.Maps Static API
Developer's guide
22
Index
map center 5
map layer 12
map layers 9
map size 6
map type 9
Roadmap
placemark color 12
placemark size 12
placemark style 12
placemark text 12
placemarks 12
style
polygon fill color 16
polygon outline color 16
polygon outline thickness 16
polygons 16
fill color
polyline color 16
polyline thickness 16
polylines 16
color
traffic 12
URL parameters 4–9, 12, 16
key
viewport 7
zoom level 8
Yandex.Maps Static API
Developer's guide
Yandex.Maps Static API
Developer's guide
15.05.2015