Skip to main content

Overview of 2GIS map APIs

Use the 2GIS map APIs to integrate vector and raster maps into your web applications, mobile applications, and websites.

MapGL JS API allows you to add a detailed three-dimensional map of 2GIS to your web application or website and display any data on it, from markers and interactive 3D models to heatmaps. This JavaScript library provides access to map vector tiles and tools for working with them. Choose a vector map if you want to use immersive capabilities or customize the map appearance for your tasks (for example, branding).

Try moving the center of the map below, changing the zoom and scale to experience the immersive graphics mode of the MapGL JS API:

To display a two-dimensional raster map, use the Raster Tiles API. You can obtain raster tiles directly through API requests or by using the JavaScript library RasterJS API. Use a raster map if you want to get a precise interactive map with minimal device resource consumption.

Example of integrating a raster map using RasterJS API:

Static API allows you to get a current static image of the map at the required point and with the required zoom level. Use static images to add map snapshots to documents, emails, messages, and other materials where interactivity is not required.

Try changing the image size, map center coordinates, and its zoom level to get the desired map fragment and a ready-made request to Static API:

Additional tools:

  • Style Editor for customizing the appearance of vector maps according to your goals or your project branding.
  • FloorsJS for creating a convenient floor navigation widget within buildings.

FAQ​

How to get started with map APIs?​

To work with the API, you need to get an access key:

  1. Sign in to the Platform Manager.
  2. Create a demo key or purchase a subscription to use the APIs.
  3. Study the examples of requests and responses in the documentation for the required API.

How is API usage cost calculated?​

  • The cost of using MapGL JS API is fixed for the selected subscription period and does not depend on the number of API requests during that period. To obtain tiles, the library uses the Tiles API, which is included in the cost of using MapGL JS API.
  • The cost of using Raster Tiles API and Static API is calculated based on the number of API requests. For more details on the calculation method, see the Tariffs section on each API page.
  • The Style Editor and FloorsJS are provided free of charge.

Can I use map APIs for free?​

You can get a demo access key to test map APIs for one month with a limited number of requests.

How to track actual API resource usage?​

You can track the progress of limit consumption by services and request distribution statistics in the Platform Manager. For more details, see the Statistics section.

How to manage API resource consumption?​

To avoid premature exhaustion of limits, you can restrict the use of API resources by your applications. In the Platform Manager personal account, several ways to configure restrictions are available:

  • Set limits on requests to specific services for all API keys in the subscription or for individual keys. Exceeding the limits will block product usage: API requests will return an error.
  • Configure notifications to be sent when approaching limits.

For more details, see the Access key management section.

What is a tile?​

A tile is a square image corresponding to a section of the map. Using tiles helps save device resources and display only the visible part of the map, loading the necessary fragments when moving across the map or changing the map scale.

What is the difference between raster tiles and vector tiles?​

Raster tiles are images of map fragments in PNG format, which are rendered on the server side and sent to your device in a ready-made form. Displaying a raster map requires fewer device resources but does not allow you to customize the map appearance and behavior flexibly. To work with a raster map, use the Raster Tiles API or Static API.

Vector tiles are data that your device receives and renders independently, according to the specified style (rendering rule). Vector tiles allow you to change the appearance of the map in real time, create interactive objects and animations, and provide smoother scaling and movement across the map. To work with a vector map, use the MapGL JS API.

Can I use third-party libraries to work with tiles?​

  • Vector tiles: you can use only the MapGL JS API library.
  • Raster tiles: it is recommended to use the RasterJS API library. You can also use third-party libraries, but their compatibility with 2GIS raster maps is not guaranteed and may be disrupted at any time without notice.

For more details, see the Services Use Agreement.

Can I directly access map tiles?​

If you need to obtain vector tiles directly for integrating them into a GIS system that does not support the use of the MapGL JS API, you can install the 2GIS API Platform in a private environment (On-Premise) and export vector tiles in the Mapbox Vector Tiles (MVT) format. Raster tiles can be obtained directly through the Raster Tiles API and Static API.

What are the technical limitations?​

The MapGL JS API is optimized for use in modern web browsers; see the complete list of supported browsers and their versions in the Browser support section. If you plan to add 3D objects to the map, review the Requirements and recommendations for 3D models.

What map customization options are available?​

When working with 2GIS vector maps through the MapGL JS API, you can:

  • Configure the map center, zoom level, map controls, graphic mode, event handling, etc.
  • Change the appearance of the map (colors, lighting, level of detail, visibility of objects and labels, and much more) using the Style Editor.
  • Add your own data to the map: objects of varying complexity (icons, animated markers, 3D models) or sources of vector and raster geodata.

When working with 2GIS raster maps through the Raster Tiles API and Static API, you can:

  • Configure the map center, zoom level, map controls, event handling, etc.
  • Add your own data to the map: objects (markers, geometric shapes, labels) or geodata in GeoJSON format.

Can I install map services in my own infrastructure?​

Yes, you can install the 2GIS API Platform in a closed environment. For more information, see the On-Premise section.

I could not find an answer to my question​

Use the documentation search or send an email to api@2gis.ru.