Skip to main content

Geodata formats

When working with geodata, you might face situations when you cannot display it on the map immediately due to the diversity, high volumes, and not always optimal representation of the data. You often need to perform preliminary calculations and transformations, for example:

  • calculate boundaries of geodata location to position a map accordingly
  • simplify geometries to get smoother outlines and increase rendering performance
  • transform a polygon into points and vice versa

2GIS map on its own does not have functionality for handling geodata. However, you can use third-party open-source libraries to fill this gap. The basic exchange format (namely, a lingua franca) between these libraries and MapGL GS API is GeoJSON.

This chapter contains primary information about main geodata formats, most common problems of geodata handling, and solutions to them.

GeoJSON​

GeoJSON format (JSON subset) is supported by the map directly. In this format, geodata is presented as Feature objects with each containing geometry in the geometry field and (optionally) metadata in the properties field.

{
   "type": "FeatureCollection",
   "features": [
      {
         "geometry": {
            "type": "LineString",
            "coordinates": [
               [37.615655, 55.768005],
               [37.625655, 55.778005]
            ],
         },
         "properties": {
            "title": "Line example"
         }
      },
   ]
}

For more information on working with this format in the map, see the GeoJSON chapter.

GeoJSON format is described by the RFC 7946 standard.

As this format is a JSON subset, it does not require any additional libraries for encoding/decoding.

Well-known text (WKT)​

Well-known text represents vector geometries as a string. The format stores geometries only, no metadata.

Example of geometries in this format:

POINT (37.615655 55.768005)
LINESTRING (37.615655 55.768005, 37.595655 55.788005, 37.645655 55.788005)
POLYGON ((37.625655 55.758005, 37.645655 55.788005, 37.615655 55.788005, 37.605655 55.768005, 37.625655 55.758005))
POLYGON ((37.620655 55.758005, 37.630655 55.793005, 37.590655 55.790005, 37.585655 55.770005, 37.620655 55.758005), (37.605655 55.778005, 37.620655 55.781005, 37.615655 55.770005, 37.605655 55.778005))

To work with this standard in the web, you can use the wellknown library.

const wktGeometries = [
   'POINT (37.615655 55.768005)',
   'LINESTRING (37.615655 55.768005, 37.595655 55.788005, 37.645655 55.788005)',
   'POLYGON ((37.625655 55.758005, 37.645655 55.788005, 37.615655 55.788005, 37.605655 55.768005, 37.625655 55.758005))',
   'POLYGON ((37.620655 55.758005, 37.630655 55.793005, 37.590655 55.790005, 37.585655 55.770005, 37.620655 55.758005), (37.605655 55.778005, 37.620655 55.781005, 37.615655 55.770005, 37.605655 55.778005))'
];

const geojsonGeometries = wktGeometries.map((wkt) => wellknown.parse(wkt));

WKT format is described by the OGC Simple Feature Access standard.

The format is widely used in 2GIS APIs: for example, Routing API and Places API (see geometry fields).

Shapefile (shp)​

Shapefile contains geodata in binary format, which enables storing data densely. The format supports storing both geometries and metadata.

let source = null;

shapefile
    .open('/geodata/mapgl/ne_110m_coastline.shp')
    .then(async (source) => {
        const features = [];
        let result = await source.read();
        while (result && !result.done) {
            features.push(result.value);
            result = await source.read();
        }
        source = new mapgl.GeoJsonSource(map, {
            data: { type: 'FeatureCollection', features },
        });
    })
    .catch((error) => console.error(error.stack));

The format is supported by the Esri company and is described by the ESRI Shapefile Technical Description standard.

To work with this standard in the web, you can use the shapefile library.

Performance note​

The map enables working with a relatively big volume of data. For working with GeoJSON, it uses the geojson-vt library. The library provides acceptable performance speed for GeoJSON with 100 MB of volume and 5.4 million points.

The example below loads and displays a roads network from the Natural Earth Data project. Data is represented as a shapefile with 15 MB of volume and around 700 thousands points.

The main limitation when working with large volumes of geodata is not the speed of processing or rendering, but network bandwidth. Transferring files of 20–100 MB can take a significant amount of time, especially when using mobile data.

To efficiently process any volume of data, it is recommended to convert it into a tiled representation: divide it into small fragments that can be downloaded individually for visualization. You can use the 2GIS Pro service for this.