API Reference | Static API | 2GIS Documentation

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.

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

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

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.

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
    

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
    

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
    

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

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
    

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
    

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
    

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.

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 ]
            ]
        }]
    }
    

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.

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"
        }
    }]
}