API Reference Static API

Current API version: 1.0.

Entry point: static.maps.2gis.com.

All parameters are specified in the query string. General view of the request:

GET /1.0?s={size}&c={center}&z={zoom}&g={geojson}&pt={points}&ls={linestrings}&pn={polygons}

Request returns a PNG image or an error describing the problem.

General information

In the examples below, required parameters are shown in curly braces, optional parameters are shown in square brackets.

Coordinates

Latitude and longitude coordinates of points are specified in degrees in ISO 6709 format.

The plus sign + for positive coordinates can be omitted. If you use the plus sign, encode it to URL-encoded format: %2B.

Colors

Colors of lines and polygons are specified in hexadecimal format RRGGBB[AA], where red, green, blue components, and transparency (optional) are specified in sequence.

The prefixes # and 0x for colors can be omitted. If you use the # prefix, encode it to URL-encoded format: %23.

Map

To display a simple map without additional objects, specify its size, center, and zoom level.

If there are additional objects on the map, you can omit the center and zoom level, the map will be adjusted automatically.

Size

Required parameter.

s={width}x{height}[@{scale}]

Sets the size of the map in pixels and a size modifier for different screens.

The @2x modifier enables HD mode for Retina and other HiDPI screens. In this case, the actual size of the map will be twice the requested size.

Values:

width - width of the map, 120 to 1280 pixels
height - height of the map, 90 to 1280 pixels
scale - size modifier (1x - default; 2x - HiDPI)

Examples:

SD map in landscape view:
```
s=600x400
```
Equivalent of the previous example:
```
s=600x400@1x
```
HD map in portrait view:
```
s=200x300@2x
```

Center

Required parameter if there are no additional objects on the map.

c={lat},{lon}

Sets the coordinates of the center of the map.

Values:

lat - latitude in degrees
lon - longitude in degrees

Examples:

Coordinates of the Tretyakov Gallery:
```
c=55.7414,37.6209
```

Zoom level

Required parameter if there are no additional objects on the map.

z={zoom}

Sets the zoom level of the map.

Values:

zoom - zoom level, 1 to 18

Examples:

Zoom level 2:
```
z=2
```
Zoom level 10:
```
z=10
```

Objects

You can add markers, lines, and polygons in a variety of styles to your map. The description format is very similar to GeoJSON (RFC 7946).

Markers (Point & MultiPoint)

You can add markers to the map in the shape of circles, pins, or using a custom image. You can specify the color, size and add numbering for circles and pins.

Standard marker

pt={lat},{lon}[~k:{kind}][~c:{color}][~s:{size}]

The parameter sets the coordinates, shape, color and size of the marker.

Values:

lat - latitude in degrees
lon - longitude in degrees
kind - marker shape
- p - pin (default)
- c - circle
color - marker color:
- be - blue (default)
- rd - red
- oe - orange
- yw - yellow
- gn - green
- pe - purple
- pk - pink
- gy - gray
- bk - black
size - marker size:
- s - small (default)
- l - large

Examples:

Small blue pin (default):
```
pt=55.7368,37.6326
```
Small blue circle:
```
pt=55.7368,37.6326~k:c
```
Small green pin:
```
pt=55.7368,37.6326~c:gn
```
Large blue pin:
```
pt=55.7368,37.6326~s:l
```
Large green circle:
```
pt=55.7368,37.6326~k:c~c:gn~s:l
```

Numbered marker

pt={lat},{lon}~n:{number}[~k:{kind}]

The parameter sets the coordinates, number and shape of the numbered marker.

Values:

lat - latitude in degrees
lon - longitude in degrees
number - marker number, 1 to 99
kind - marker shape:
- p - pin (default)
- c - circle

Examples:

Pin (default) with number 1:
```
pt=55.7368,37.6326~n:1
```
Circle with number 2:
```
pt=55.7368,37.6326~n:2~k:c
```

Custom marker (URL)

pt={lat},{lon}~u:{url}[~a:{x},{y}]

The parameter sets the coordinates, image URL, and an anchor point for the custom marker.

The timeout for downloading an image for the marker is 2 seconds. The maximum image size is 16 KB (16 384 for the Content-Length response header). The resulting image is cached for 2 hours.

Custom markers are not automatically scaled in HD mode. You have to manually change the image you use when you change the map size modifier.

Values:

lat - latitude in degrees
lon - longitude in degrees
url - image URL
x - horizontal anchor point coordinate relative to the top left corner:
- 0 to 1 - relative value, 0.5 (default) is the horizontal center
- greater than 1 - absolute value in pixels
y - vertical anchor point coordinate relative to the top left corner:
- 0 to 1 - relative value, 0.5 (default) is the vertical center
- greater than 1 - absolute value in pixels

Examples:

Custom marker with the anchor point in the center:

pt=55.7368,37.6326~u:http://example.com/image.png

Custom marker with the anchor point at the bottom center (like the tip of a pin):
```
pt=55.7368,37.6326~u:http://example.com/image.png~a:0.5,1
```

Custom marker with the anchor point at 12,16 pixels:

pt=55.7368,37.6326~u:http://example.com/image.png~a:12,16

Custom marker (Base64)

pt={lat},{lon}~b:{base64}[~a:{x},{y}]

The parameter sets the coordinates, image in Base64 format, and anchor point for the custom marker.

Custom markers are not automatically scaled in HD mode. You have to manually change the image you use when you change the map size modifier.

Values:

lat - latitude in degrees
lon - longitude in degrees
base64 - image in Base64 format (URL encoded)
x - horizontal anchor point coordinate relative to the top left corner:
- 0 to 1 - relative value, 0.5 (default) is the horizontal center
- greater than 1 - absolute value in pixels
y - vertical anchor point coordinate relative to the top left corner:
- 0 to 1 - relative value, 0.5 (default) is the vertical center
- greater than 1 - absolute value in pixels

Examples:

Custom marker with the anchor point in the center:
```
pt=55.7368,37.6326~b:base64string
```
Custom marker with the anchor point at the bottom center (like the tip of a pin):
```
pt=55.7368,37.6326~b:base64string~a:0.5,1
```
Custom marker with the anchor point at 12,16 pixels:
```
pt=55.7368,37.6326~b:base64string~a:12,16
```

Set of markers

pt={lat1},{lon1}~{lat2},{lon2}[~{lat3},{lon3}...]

Style settings can be applied to several markers at once.

Examples:

Three small blue pins (default style):

pt=55.7368,37.6326~55.7468,37.6226~55.7568,37.6126

Equivalent of the previous example:

pt=55.7368,37.6326&pt=55.7468,37.6226&pt=55.7568,37.6126

Two large green circles:

pt=55.7368,37.6326~55.7468,37.6226~k:c~c:gn~s:l

Two custom markers (URL):

pt=55.7368,37.6326~55.7468,37.6226~u:http%3A%2F%2Fexample.com%2Fimage.png

Two custom markers (Base64):

pt=55.7368,37.6326~55.7468,37.6226~b:base64string

Lines (LineString & MultiLineString)

You can add polylines with the specified color and width to the map.

Line

ls={lat1},{lon1},{lat2},{lon2}...[~w:{weight}][~c:{color}]

The parameter sets the coordinates of the polyline vertices, its width and color:

Values:

lat - latitude in degrees
lon - longitude in degrees
weight - line width in pixels
color - line color

Examples:

Blue line (default style):
```
ls=55.736,37.632,55.746,37.632
```
Line with a width of 7 pixels:
```
ls=55.736,37.632,55.746,37.632~w:7
```

Red line:

ls=55.736,37.632,55.746,37.632~c:ff0000

Green line with a width of 6 pixels:

ls=55.736,37.632,55.746,37.632~w:6~c:00ff00

Set of lines

ls={lat1},{lon1},{lat2},{lon2}...~{lat1},{lon1},{lat2},{lon2}...[~{lat1},{lon1},{lat2},{lon2}...]

Style settings can be applied to several lines at once.

Examples:

Two blue lines (default style):

ls=55.736,37.632,55.746,37.632~55.836,37.632,55.846,37.632

Equivalent of the previous example:

ls=55.736,37.632,55.746,37.632&ls=55.836,37.632,55.846,37.632

Two green lines 6 pixels thick:

ls=55.736,37.632,55.746,37.632~55.836,37.632,55.846,37.632~w:6~c:00ff00

Polygons (Polygon & MultiPolygon)

You can add polygons (without cutouts) to the map with the specified color and width of the outline, as well as the fill color.

Polygon

pn={lat1},{lon1},{lat2},{lon2},{lat3},{lon3}...[~w:{weight}][~c:{color}][~f:{fill}]

The parameter sets the coordinates of the vertices of the polygon, the width and color of the outline, and the fill color:

Values:

lat - latitude in degrees
lon - longitude in degrees
weight - outline width in pixels
color - outline color
fill - fill color

Examples:

Polygon with a semi-transparent blue fill (default):
```
pn=55.736,37.632,55.746,37.632,55.746,37.642
```

Polygon with a 7 pixels thick outline:

pn=55.736,37.632,55.746,37.632,55.746,37.642~w:7

Polygon with a red outline:

pn=55.736,37.632,55.746,37.632,55.746,37.642~c:ff0000

Polygon with a solid red fill:

pn=55.736,37.632,55.746,37.632,55.746,37.642~f:ff0000

Polygon with a semi-transparent red fill:

pn=55.736,37.632,55.746,37.632,55.746,37.642~f:ff0000a2

Polygon with a 6 pixels thick green outline and a semi-transparent yellow fill:
```
pn=55.736,37.632,55.746,37.632,55.746,37.642~w:6~c:00ff00~f:ffff00aa
```

Set of polygons

pn={lat1},{lon1},{lat2},{lon2},{lat3},{lon3}...~{lat1},{lon1},{lat2},{lon2},{lat3},{lon3}...[~{lat1},{lon1},{lat2},{lon2},{lat3},{lon3}...]

Style settings can be applied to several polygons at once.

Examples:

Two polygons with a semi-transparent blue fill (default):

pn=55.736,37.632,55.746,37.632,55.746,37.642~55.836,37.632,55.846,37.632,55.846,37.642

Equivalent of the previous example:

pn=55.736,37.632,55.746,37.632,55.746,37.642&pn=55.836,37.632,55.846,37.632,55.846,37.642

Two polygons with a green outline 6 pixels thick and a semi-transparent yellow fill:

pn=55.736,37.632,55.746,37.632,55.746,37.642~55.836,37.632,55.846,37.632,55.846,37.642~w:6~c:00ff00~f:ffff00aa

GeoJSON

You can add any objects to the map according to the GeoJSON (RFC 7946) specification and set their style in the properties fields similar to the parameters in the URL.

Objects are specified as the g parameter and must be URL encoded.

Geometry

RFC 7946, Section 3.1, Geometry Object

All types of geometry objects are supported: Point, MultiPoint, LineString, MultiLineString, Polygon (no cutouts), MultiPolygon (no cutouts), and GeometryCollection.

These objects are displayed using the default styles.

Examples:

Marker:

{
    "type": "Point",
    "coordinates": [ 82.91871, 55.03652 ]
}

Line:

{
    "type": "LineString",
    "coordinates": [
        [ 82.91871, 55.03652 ],
        [ 82.92131, 55.02711 ],
        [ 82.92698, 55.02470 ]
    ]
}

Collection of a marker and a line:

{
    "type": "GeometryCollection",
    "geometries": [{
        "type": "Point",
        "coordinates": [ 82.91871, 55.03652 ]
    }, {
        "type": "LineString",
        "coordinates": [
            [ 82.91871, 55.03652 ],
            [ 82.92131, 55.02711 ],
            [ 82.92698, 55.02470 ]
        ]
    }]
}

Feature

RFC 7946, Section 3.2, Feature Object

Feature objects let you customize geometry styles.

Marker (Point & MultiPoint)

You can set the shape, color, and size for a standard marker.

Properties:

{
    "k": "{kind}",
    "c": "{color}",
    "s": "{size}"
}

kind - marker shape:
- p - pin (default)
- c - circle
color - marker color:
- be - blue (default)
- rd - red
- oe - orange
- yw - yellow
- gn - green
- pe - purple
- pk - pink
- gy - gray
- bk - black
size - marker size:
- s - small (default)
- l - large

Example:

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [ 82.89827, 55.03687 ]
    },
    "properties": {
        "k": "c",
        "c": "gn",
        "s": "l"
    }
}

Numbered marker

You can specify the shape and number for a numbered marker.

Properties

{
    "k": "{kind}",
    "n": {number}
}

kind - marker shape
- p - pin (default)
- c - circle
number - marker number, 1 to 99

Example:

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [ 82.89827, 55.03687 ]
    },
    "properties": {
        "k": "c",
        "n": 1
    }
}

Custom marker (URL)

You can set the image URL and anchor point for a custom marker.

Properties:

{
    "u": "{url}",
    "a": "{x},{y}"
}

url - image URL
x - horizontal anchor point coordinate relative to the top left corner:
- 0 to 1 - relative value, 0.5 (default) is the horizontal center
- greater than 1 - absolute value in pixels
y - vertical anchor point coordinate relative to the top left corner:
- 0 to 1 - relative value, 0.5 (default) is the vertical center
- greater than 1 - absolute value in pixels

Example:

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [ 82.89827, 55.03687 ]
    },
    "properties": {
        "u": "https://example.org/img.png",
        "a": "0.5,1"
    }
}

Custom marker (Base64)

You can specify an image in Base64 format and an anchor point for a custom marker.

Properties:

base64 - image in Base64 format (URL encoded)
x - horizontal anchor point coordinate relative to the top left corner:
- 0 to 1 - relative value, 0.5 (default) is the horizontal center
- greater than 1 - absolute value in pixels
y - vertical anchor point coordinate relative to the top left corner:
- 0 to 1 - relative value, 0.5 (default) is the vertical center
- greater than 1 - absolute value in pixels

Example:

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [ 82.89827, 55.03687 ]
    },
    "properties": {
        "b": "base64string",
        "a": "0.5,1"
    }
}

Line (LineString & MultiLineString)

For the line, you can set the width and color.

Properties:

{
    "w": {weight},
    "c": "{color}"
}

weight - line width in pixels
color - line color

Example:

{
    "type": "Feature",
    "geometry": {
        "type": "LineString",
        "coordinates": [
            [ 82.89827, 55.03687 ],
            [ 82.90021, 55.03489 ],
            [ 82.91062, 55.03264 ]
        ]
    },
    "properties": {
        "w": 3,
        "c": "03ee10"
    }
}

Polygon (Polygon & MultiPolygon)

For the polygon, you can specify the width and color of the outline, and the fill color.

Properties

{
    "w": {weight},
    "c": "{color}",
    "f": "{fill}"
}

weight - outline width in pixels
color - outline color
fill - fill color

Example:

{
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": [[
            [ 82.89827, 55.03687 ],
            [ 82.90021, 55.03489 ],
            [ 82.91062, 55.03264 ],
            [ 82.91355, 55.03636 ],
            [ 82.90925, 55.04067 ],
            [ 82.89827, 55.03687 ]
        ]]
    },
    "properties": {
        "w": 3,
        "c": "03ee10",
        "f": "03ee10a0"
    }
}

GeometryCollection

Placing a GeometryCollection inside a Feature object will work, but you won't be able to stylize the objects because the collection may consist of different types of geometry objects. Instead, use individual Feature objects or a FeatureCollection object.

FeatureCollection

RFC 7946, Section 3.3, FeatureCollection Object

FeatureCollection allows you to combine multiple Feature objects.

Example:

{
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "geometry": {
            "type": "LineString",
            "coordinates": [
                [ 82.91871, 55.03652 ],
                [ 82.92131, 55.02711 ],
                [ 82.92698, 55.02470 ]
            ]
        },
        "properties": {
            "w": 5
        }
    }, {
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [ 82.92698, 55.02470 ]
        },
        "properties": {
            "k": "c",
            "n": 1
        }
    }, {
        "type": "Feature",
        "geometry": {
            "type": "Polygon",
            "coordinates": [[
                [ 82.89827, 55.03687 ],
                [ 82.90021, 55.03489 ],
                [ 82.91062, 55.03264 ],
                [ 82.91355, 55.03636 ],
                [ 82.90925, 55.04067 ],
                [ 82.89827, 55.03687 ]
            ]]
        },
        "properties": {
            "c": "03ee10",
            "f": "03ee10a0"
        }
    }]
}