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}, bc{outline color},bw{outline thickness},{points}

The polygon definition can additionally contain the fill color (the f parameter) or stroke outline:

Line color

Hexadecimal representation of the line color in RGBA format (such as 0xFFFFFFFF). The first 6 characters set the RGB color, and the last two set the transparency of the line. The transparency value is in the 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).

Outline thickness

Outline thickness (in pixels). By default, 0 pixels.

bw:8 

Outline stroke color

Hexadecimal representation of the outline color in RGBA format (such as 0xFFFFFFFF). The first 6 characters set the RGB color, and the last two set the transparency of the line. The transparency value is in the range from 00 (transparent) to FF (opaque). By default, a white outline is used.

For example:

bc:8822DDC0

Points

The point coordinates of a polyline are set as follows:
  • Longitude1,Latitude2,...,LongitudeN,LatitudeN.
  • A Base64-encoded string.
    An example of encoding coordinates in the Base64 format
    1. Write the coordinates of the polyline points one under the other, one point per line.

      37.593578 55.735094
      37.592159 55.732469
      37.589374 55.734162
    2. Multiply each coordinate by 1,000,000.

      37593578 55735094
      37592159 55732469
      37589374 55734162
    3. Calculate the offsets for the second and subsequent polyline points.

      37593578 55735094
      -1419 -2625
      -2785 1693
    4. Translate each of the resulting numbers into binary. Add missing zeros to the left to fill 4 bytes (32 bits).

      As a result, the sequence of numbers will look like this (one coordinate per line):

      00000010001111011010000111101010
      00000011010100100111001100110110
      11111111111111111111101001110101
      11111111111111111111010110111111
      11111111111111111111010100011111
      00000000000000000000011010011101
    5. Encode in sequences of four bytes. Convert every six bits to the decimal system — this will be the number of the character in the string that is used for encoding.

      The string used for encoding looks like this:

      ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_=
      Note. This string is different from the string that is used for Base64 encoding. This is because the string with encoded points must be passed as a URL parameter without restrictions, and the "+" and "/" symbols in the URL are special characters.

      For example, the encoding algorithm for the first set of 4 bytes is provided below:

      1. Reverse the byte order.

        Straight order:

        00000010 00111101 10100001 11101010

        Reverse order:

        11101010 10100001 00111101 00000010
      2. Sequentially read six-bit sequences to get the number of characters:

        111010 -> symbol № 58 -> symbol "6"
        101010 -> symbol № 42 -> symbol "q"
        000100 -> symbol № 04 -> symbol "E"
        111101 -> symbol № 61 -> symbol "9"
        000000 -> symbol № 00 -> symbol "A"
        10

        The missing bits for the last character are taken from the following four-byte sequence.

        Note. After processing all bytes, there may be a situation when there are either two or four bits remaining that are not enough to get the number of the character. In this case every two missing bits are replaced with the equal sign (=).
      3. Generic Base64-encoded string:

        6qE9AjZzUgN1-v__v_X__x_1__-dBgAA

The point coordinates of a polygon formed by a single closed polyline (where the first and last point coincide) 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: CoordinatesOfPolyline1Vertices;...CoordinatesOfPolyline2Vertices.

Examples

Polyline

The following example requests a section of the map of Izmir showing the route from the Çankaya metro station to the building of Turkiye Tarim Kredi Kooperatifleri. The polyline points are set by a list of point coordinates, and the default color and thickness are used:

https://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.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

Polygon defined by a single polyline

The example below shows a request for part of the map of Izmir showing the boundaries of the walls of İzmir Fuarı. It uses a polygon with a red outline and light green semitransparent fill to define the boundaries of the fortress:

https://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

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.

https://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 always filled in.
https://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