Lines and polygons

Polylines and polygons can be used on a static map to mark a route or boundaries of an object.

A polyline consists of a set of points connected by straight lines. A polyline can cross itself. If the first and last points of a polyline have the same coordinates, it's called a closed polyline.

A polygon is set using one or more closed polylines.

Alert

The Static API allows displaying no more than 5 polylines and polygons on a map at once, and the total number of points on the figures cannot be more than 100.

A special description is used to set the appearance of a geometric figure. The polyline description contains information about the thickness and color of lines, and the polygon description contains information about the thickness and color of the outline and the fill color (see below).

Points on all figures are linked to geographical coordinates.

The point coordinates and the appearance of polylines and polygons are set using the pl parameter. This parameter contains definitions for all the figures displayed on the map. Figure descriptions are separated by a tilde (~):

pl = FigureDefinition1~FigureDefinition2~FigureDefinition3

The polyline description has the following format:

c:{line color}, w:{thickness}, bc:{outline color},bw:{outline thickness},{points}

c:{line color},f:{fill color},w:{thickness},{points}

c:{line color}, w:{thickness}, bc:{outline color},bw:{outline thickness},{points}

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).

For example: w:8

Note

If the 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, the thickness value is 0 pixels.

For example: bw:8

Outline 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,Latitude1,...,LongitudeN,LatitudeN.
  • A Base64-encoded string.
An example of encoding coordinates in 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:

  6. Reverse the byte order.

    Straight order:

    00000010 00111101 10100001 11101010

    Reverse order:

    11101010 10100001 00111101 00000010

  7. Sequentially read six-bit sequences to get the number of characters:

    111010 -> symbol No. 58 -> symbol "6"
101010 -> symbol No. 42 -> symbol "q"
000100 -> symbol No. 04 -> symbol "E"
111101 -> symbol No. 61 -> symbol "9"
000000 -> symbol No. 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 where 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 (=).

  8. Generic Base64-encoded string:

    6qE9AjZzUgN1-v__v_X__x_1__-dBgAA

The point coordinates of a polygon formed by a single closed polyline (with its first and last points coinciding) are set in the same way.

To define a polygon using a set of closed polylines, use a semicolon to separate the sequence of points for each polyline: CoordinatesOfPolyline1Point;...CoordinatesOfPolyline2Point.

Examples

Polyline

The following example shows a request for a map fragment of Izmir with a route from the Çankaya metro station to the Turkiye Tarim Kredi Kooperatifleri building. The polyline points are set by a list of point coordinates. The default color and thickness are used:

https://static.api.mappable.world/v1?lang=en_US&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&apikey=YOUR_API_KEY

Polygon defined by a single polyline

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

https://static.api.mappable.world/v1?lang=en_US&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&apikey=YOUR_API_KEY

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.api.mappable.world/v1?lang=en_US&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&apikey=YOUR_API_KEY

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 tilde (~).

The area where the polygons intersect is always filled in.

https://static.api.mappable.world/v1?lang=en_US&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&apikey=YOUR_API_KEY

Previous
Placemarks
Next
Automatic map positioning