apinavitelmaps/api

Navitel Webmap API Capabilities

JS API for Navitel maps is a set of JavaScript components designed to access cartographic services on web pages.

Capabilities:

  • Map display;
  • Full-text search;
  • Search for nearby objects;
  • Route building with vehicle indication.
Quick Start

1. Get an API key.

A valid API key is required to work with JS API for Navitel maps. It can be obtained via the following e-mail: ap@navitel.ru.

2. Connect the API and Leaflet libraries.

In order to connect Leaflet libraries with the API, add the following lines to the HTML page header:

<head>
 <link rel="stylesheet" href="https://unpkg.com/leaflet@1.6.0/dist/leaflet.css" />
 <script src="https://unpkg.com/leaflet@1.6.0/dist/leaflet-src.js"></script>

 <script src="http://webmapapi.navitel.ru/index.umd.js"></script>
</head>

3. Create a map container.

To create a container for map storage, add any HTML block element. The map will take all of it.

<body>
 <div id="map"></div>
</body>

4. Create a map.

To create a map with tiles, add the following lines to the body section:

<script>
 const nmapi = navitel.createWebMapApi('6e982defee3eb78ab24890068d57fff04b4f7ae5', {
  locale: navitel.LocaleCode.ru_RU
 })

 const map = L.map('map', {
  center: [55.75, 37.70],
  zoom: 9,
 })

 const navitelTile = nmapi.extension.leaflet.createTileLayer({
  locale: navitel.LocaleCode.ru_RU
 })
 navitelTile.addTo(map)
</script>

This example depicts two parameters used for the map:

  • center: coordinates of the map center in [latitude, longitude] format;
  • zoom: zoom factor that lies in range from 3 to 18, where 3 is the minimum and 18 is the maximum scale.
Manual
Basic data types
LonLat

A geographical point with a certain latitude and longitude.

Property Type Description
latitude Number Latitude in degrees, value range [-90, 90]
longitude Number Longitude in degrees, value range [-180, 180]
Viewport

Describes the field of view: a rectangular area on the map in pixel coordinates.

Property Type Description
widthPx uint32 Width in pixels
heightPx uint32 Height in pixels
zoomLevel uint32 Zoom factor in the range from 3 to 18, where 3 is the minimum and 18 is the maximum scale.
centerCoordinates LatLng Map center coordinates in [latitude, longitude] format
GeoLine

A sequence of points polyline

Property Type Description
points LonLat[] Sequence of points
TrackLimits

Describes weight and size restrictions when building a route

Property Type Description
totalWeightKg Integer Gross vehicle mass in kilograms
axleWeightKg Integer Vehicle axle load in kilograms
widthMeters Integer Vehicle width in meters
heightMeters Integer Vehicle height in meters
lengthMeters Integer Vehicle length in meters
Address

Describes the address hierarchy.

Property Type Description
country string Country
region string Region
parish string County, parish
city string City
district string District
street string Street
building string Building
MapObject

Describes an object on the map.

Property Type Description
coordinates LonLat Object coordinates
address Address Object address
label string Free-form text description, e.g. store name. Can be left blank.
ListItem

Describes an element of an address search result.

Property Type Description
id string A unique identifier used in address search at lower hierarchy levels (e.g. id form ListCountries in ListCities)
name string Name of the element from address search result. E.g. country name
coordinates LonLat Coordinates
Map

This section describes the map API, which is used to create and manage maps on web pages.

createWebMapApi
Constructor Description
createWebMapApi( <string>apikey, <options>) Creates an object that will be further accessed by the API

Attributes

Attribute Type Default value Description
locale String browser language Specifies language code used for the map

Usage sample

const nmapi = navitel.createWebMapApi('6e982defee3eb78ab24890068d57fff04b4f7ae5', {
 locale: navitel.LocaleCode.ru_RU
})
map
Constructor Description
L.map(<string> id, <Map options> options?) Initializes a map in the DOM node of the
element with a specified id and an optional set of options (described below)

Attributes

A full description of possible method parameters is available in the Leaflet 1.6.0 API library documentation here: https://leafletjs.com/reference-1.6.0.html#map-option

Usage sample

Map initialization in

with “map” id followed by map center coordinates and zoom factor.

const map = L.map('map', {
 center: [55.75, 37.70],
 zoom: 9,
})
createTileLayer
Constructor Description
createTileLayer(<options>) Creating a tile layer.

Attributes

Attribute Type Default value Description
locale String browser language Specifies language code used for the tile
tileType String t Specifies tile type: maps (“t”) or traffic jam (“j”)

Usage sample

const navitelTile = nmapi.extension.leaflet.createTileLayer({
 locale: navitel.LocaleCode.ru_RU
})
const navitelJams = nmapi.extension.leaflet.createTileLayer({
 locale: navitel.LocaleCode.ru_RU,
 tileType: navitel.TileType.Jams,
})
Route

The API allows you to automatically build a route between specified points, get route length and approximate time to destination.

A route can be built for the following vehicle types:

  • Pedestrian
  • Bicycle
  • Car
  • Taxi
  • Bus
  • Emergency service vehicle
  • Delivery
  • Truck

A route can be built from two or more points, with or without traffic jam display.

routeId

Unique route id

Constructor Description
routeId(<options>) Route key generation

Attributes

Attribute Type Default value Description
objectType Integer   Specifies vehicle type to build a route for. Possible values:
INVALID = 0;
PEDESTRIAN = 1;
BICYCLE = 2;
CAR = 3;
TAXI = 4;
BUS = 5;
EMERGENCY = 6;
DELIVERY = 7;
TRUCK = 8;
jams Boolean False Enables traffic jam tracking when building a route.
waypointsList LonLat[]   Specifies an array of points for a route.
trackLimits TrackLimits   Indicates weight and size limitations for the vehicle

Usage sample

const routeId = await nmapi.route.routeId({
 objectType: nmapi.route.ObjectType.BUS,
 waypointsList: [
  [59.938806, 30.314278], // St. Petersburg
  [55.755773, 37.617761], // Moscow
  [55.028739, 82.906928], // Novosibirsk
 ]
})
routeMetadata

Route metadata

Constructor Description Returns
routeMetadata(<RouteId>) Getting route metadata length_meters - route length in meters
duration_seconds - approximate time to destination
Or a codified error
Error code Description
NO_CODE Code not specified
INVALID_ROUTE_ID Invalid route id
BAD_REQUEST Incorrect request
UNKNOWN_API_KEY Unknown API key
EXPIRED_API_KEY Expired API key
OVER_LIMIT Too many requests
ACCESS_DENIED Operation is not permitted for this API key
INTERNAL_ERROR Other errors

Usage sample

const meta = await nmapi.route.routeMetadata({ routeId })
routeGeometry

Route geometry

Constructor Description Returns
routeGeometry(<RouteId>, viewport) Getting route geometry GeoLine[] lines - route geometry in the shape of a sequential set of polylines in space
Or a codified error
Error code Description
NO_CODE Code not specified
INVALID_ROUTE_ID Invalid route id
INVALID_VIEWPORT_WIDTH Invalid viewport width
INVALID_VIEWPORT_HEIGHT Invalid viewport height
INVALID_VIEWPORT_ZOOM Invalid viewport scale
INVALID_VIEWPORT_CENTER Invalid viewport center point
BAD_REQUEST Incorrect request
UNKNOWN_API_KEY Unknown API key
EXPIRED_API_KEY Expired API key
OVER_LIMIT Too many requests
ACCESS_DENIED Operation is not permitted for this API key
INTERNAL_ERROR Other errors

Attributes

Attribute Type Description
viewport viewport Sets the viewport area for route geometry, which will be generalized according to the scale. If the attribute is not set, the entire route geometry will be shown

Usage sample

const geom = await nmapi.route.routeGeometry({
 routeId,
 viewport: {
  widthPx: 640,
  heightPx: 480,
  zoomLevel: 9,
  centerCoordinates: {
   latitude: 55.75,
   longitude: 37.70,
  },
 },
})
Search

This section describes API for search purposes

TextSearch

Full-text search

Constructor Description Returns
TextSearchRequest (<options>) Search query [map_objects] array of objects on the map (MapObject type)
Or a codified error
Error code Description
NO_CODE Code not specified
TOO_SHORT_SEARCH_PATTERN Search pattern is shorter than three symbols
INVALID_LANGUAGE_ID Invalid language id
INVALID_PIVOT Invalid coordinates
BAD_REQUEST Incorrect request
UNKNOWN_API_KEY Unknown API key
EXPIRED_API_KEY Expired API key
OVER_LIMIT Too many requests
ACCESS_DENIED Operation is not permitted for this API key
INTERNAL_ERROR Other errors

Attributes

f
Attribute Type Description
api_key string Active API key
search_pattern string Search pattern no shorter than three symbols long
offset uint32 Element number to start outputting the result from
limit uint32 Maximum number of elements in query
pivot LonLat Location pivot for closest and most relevant search results
language_id string BCP 47 language code

Usage sample

const list = await nmapi.search.textSearch({ searchPattern, pivot: { longitude: 37.618423, latitude: 55.751244 } })
const searchPattern = query.value
 results.innerHTML = list.map(item => `
  <tr>
   <td>${item.coordinates.longitude}</td>
   <td>${item.coordinates.latitude}</td>
   <td>
    Country: ${item.address.country}
    <br />Region: ${item.address.region}
    <br />Parish: ${item.address.parish}
    <br />City: ${item.address.city}
    <br />District: ${item.address.district}
    <br />Street: ${item.address.street}
    <br />Building: ${item.address.building}
   </td>
   <td>${item.label}</td>
  </tr>
 `).join('\n')
FindNearestObject

Search for nearest object

Search for nearest object Description Returns
FindNearestObjectRequest (<options>) Search for the nearest object map_objects (MapObject type) - closest object on the map
Or a codified error
Error code Description
NO_CODE Code not specified
INVALID_LANGUAGE_ID Invalid language code
INVALID_COORDINATES Invalid coordinates
NOT_FOUND Nearest object not found
BAD_REQUEST Incorrect request
UNKNOWN_API_KEY Unknown API key
EXPIRED_API_KEY Expired API key
OVER_LIMIT Too many requests
ACCESS_DENIED Operation is not permitted for this API key
INTERNAL_ERROR Other errors

Attributes

Attribute Type Description
api_key string Active API key
coordinates LonLat Location pivot to search the closest object for
language_id string BCP 47 language code

Usage sample

const item = await nmapi.search.findNearestObject({
 coordinates: {
  latitude: latlng.lat,
  longitude: latlng.lng,
 },
 locale: navitel.LocaleCode.ru_RU, // optional
})
ListCountries

List of countries by mask

Constructor Description Returns
ListCountriesRequest(<options>) List of countries by mask. Search result depends on input language [countries (ListItem type)] – an array of countries
Or a codified error
Error code Description
BAD_REQUEST Incorrect request
UNKNOWN_API_KEY Unknown API key
EXPIRED_API_KEY Expired API key
OVER_LIMIT Too many requests
ACCESS_DENIED Operation is not permitted for this API key
INTERNAL_ERROR Other errors

Attributes

Attribute Type Description
api_key string Active API key
mask string Search mask that the country name begins with
ListCities

City list by mask and country

Constructor Description Returns
ListCitiesRequest (<options>) City list by mask and country [cities (ListItem type)] – array of cities
Or a codified error
Error code Description
NO_CODE Code not set
INVALID_COUNTRY_ID Invalid country id
BAD_REQUEST Incorrect request
UNKNOWN_API_KEY Unknown API key
EXPIRED_API_KEY Expired API key
OVER_LIMIT Too many requests
ACCESS_DENIED Operation is not permitted for this API key
INTERNAL_ERROR Other errors

Attributes

Attribute Type Description
api_key string Active API key
country_id string Country id from ListCountries query
mask string Search mask that the city name begins with
limit uint32 Maximum number of elements in the output
ListStreets

List of streets by mask and city

Constructor Description Returns
ListStreetsRequest (<options>) List of streets by mask and city [streets (ListItem type)] – array of streets
Or a codified error
Error code Description
NO_CODE Code not set
INVALID_CITY_ID Invalid city id
BAD_REQUEST Incorrect request
UNKNOWN_API_KEY Unknown API key
EXPIRED_API_KEY Expired API key
OVER_LIMIT Too many requests
ACCESS_DENIED Operation is not permitted for this API key
INTERNAL_ERROR Other errors

Attributes

Attribute Type Description
api_key string Active API key
city_id string City id from ListCities query
mask string Search mask that the street name begins with
limit uint32 Maximum number of elements in the output
ListBuildings

List of buildings by mask and street

Constructor Description Returns
ListBuildingsRequest (<options>) List of buildings by mask and street [buildings (ListItem type)] - array of buildings
Or a codified error
Error code Description
NO_CODE Code not set
INVALID_STREET_ID Invalid street id
BAD_REQUEST Incorrect request
UNKNOWN_API_KEY Unknown API key
EXPIRED_API_KEY Expired API key
OVER_LIMIT Too many requests
ACCESS_DENIED Operation is not permitted for this API key
INTERNAL_ERROR Other errors

Attributes

Attribute Type Description
api_key string Active API key
street_id string Street id from ListStreets query
mask string Search mask that the street name begins with
limit uint32 Maximum number of elements in the output
CompleteAddress

Full address for address search element

Constructor Description Returns
CompleteAddressRequest (<options>) Full address for address search element address (Address type) – full address of an object
Or a codified error
Error code Description
NO_CODE Code not set
INVALID_LIST_ITEM_ID Invalid object id
INVALID_LANGUAGE_ID Invalid language id
BAD_REQUEST Incorrect request
UNKNOWN_API_KEY Unknown API key
EXPIRED_API_KEY Expired API key
OVER_LIMIT Too many requests
ACCESS_DENIED Operation is not permitted for this API key
INTERNAL_ERROR Other errors

Attributes

Attribute Type Description
api_key string Active API key
list_item_id string Object id from List* query
language_id string BCP 47 language code

Tìm kiếm & sơ đồ trang

Chính sách bảo mật

© JSC “CNT” 2026