Android SDK

Android SDK allows you to add an 2GIS map to your Android application. Using the SDK, you can display a map on the screen, get information about map objects, build routes, use the navigator, and so on.

See SDK usage examples in the Examples section. For a detailed description of all classes and methods, see API Reference.

Geodata complies with OGC standards.

SDK versions

Android SDK packages are available in two versions:

• Full is a full version that allows you to:
  • Add a map to the application and manage it: add markers and geometric shapes, control the camera movement, display layers (for example, traffic), work with map styles, etc.
  • Search for objects in the directory: organizations, buildings, places, and others.
  • Work with the navigator in the application in one of the three modes: free-drive, turn-by-turn, or simulated navigation.
  • Build optimal routes on ​​the map, including routes inside buildings.
  • Use offline data.
• Map is a lightweight version that allows you to:
  • Add a map to the application and manage it: add markers and geometric shapes, control the camera movement, display layers (for example, traffic), work with map styles, etc.
  • Search for objects in the directory: organizations, buildings, places, and others.

Important

You cannot use Full and Map simultaneously. It causes an assembly error.

Getting API keys

To connect to 2GIS servers, obtain geodata, and enable SDK features, you need to get an access key file:

1. To obtain the dgissdk.key key file, fill in the form at dev.2gis.com and specify:

   • ID of the application (App ID) for which the key will be used. Make sure that the App ID meets the requirements.
   • A list of APIs that require access. The list depends on the required features and the SDK version. For more details, see the API for SDK operation section.

2. Make sure that the key requirements are met.

After you receive the key, initialize the SDK.

API for SDK operation

Depending on the required features, the SDK requires access keys for the maps, search, and navigation APIs. Available features depend on the SDK version: Full or Map.

When you use a key, only access to used APIs is paid based on the number of sent requests (and, in some cases, responses). You can check the statistics of API request distribution in the Platform Manager.

Map (for Full and Map)

For more information on the available options, see the Map instruction.

Feature	APIs
Creating a map in the application (MapView class)	Tiles API Regions API
Displaying traffic jams on the map (TrafficSource class)	Regions API

Directory (for Full and Map)

For more information on the available options, see the Directory instruction.

Feature	APIs
Creating a search engine (SearchManager class)	Regions API
Getting search results (SearchManager.search() method)	Places API Markers API Access to certain information about objects is only available with additional key configuration for an extra fee: see the Object data structure section.
Searching for objects in the directory by ID (SearchManager.searchById() method)	Places API Markers API
Building search suggestions (SearchManager.suggest() method)	Suggest API

Routing (only for Full)

For more information on the available options, see the Routing instruction.

Feature	APIs
Searching for an optimal route considering traffic jams (TrafficRouter class)	Directions API - all routes except public transport Public Transport API - public transport routes Truck Directions API - truck routes
Displaying routes on the map (RouteEditorSource class)	Directions API - all routes except public transport Public Transport API - public transport routes Truck Directions API - truck routes

Navigation (only for Full)

For more information on the available options, see the Navigation instruction.

Feature	APIs
Starting the navigation (NavigationManager.start() method): in free-drive mode in turn-by-turn mode	Directions API - all routes except public transport Public Transport API - public transport routes Truck Directions API - truck routes
Searching for alternative routes (AlternativeRouteSelector class)	Directions API - all routes except public transport Public Transport API - public transport routes Truck Directions API - truck routes
Displaying road events (RoadEventSource class)	Regions API
Calculating the device geolocation based on cell towers and nearest Wi-Fi access points (using RadarApiSettings in the DefaultLocationSource)	Radar API

Requirements

Key requirements

• You can initialize the SDK only once per application. Only one key can be used for each application. Different keys are required in the following cases:
  • If the application is available for different operating systems.
  • If the application has several alternatives for a single OS (for example, one application for the driver and another for the passenger).
  • If different SDK versions are used (Full and Map).
• The App ID must match the app_id value in the key file.
• Changing the key file while the application is running is not supported.

App ID requirements

• An App ID can contain Latin letters (A-Z, a-z), numbers (0-9), periods (.) for segment separation, and hyphens (-).
• An App ID must contain at least two segments separated by periods (e.g., com.example.app). Each segment must begin with a letter.

System requirements

• Android 6.0 (Marshmallow) and later
• Supported architectures: x86_64, x86, armeabi-v7a, arm64-v8a
• OpenGL ES 3.1

Installation

To install Android SDK:

1. Declare a custom repository in your settings.gradle.kts file:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
           maven {
               url = URI("https://artifactory.2gis.dev/sdk-maven-release")
           }
       }
   }

2. Add one of the following build dependencies.

   • For the Full SDK version:

     dependencies {
         implementation 'ru.dgis.sdk:sdk-full:latest.release'
     }

   • For the Map SDK version:

     dependencies {
         implementation 'ru.dgis.sdk:sdk-map:latest.release'
     }

Demo project

You can find a demo app with the source code in the GitHub repository.

Application size

The size of your application may increase noticeably after adding the SDK to your project. See a description of the cause and possible strategies for dealing with this increase below.

Processor architectures

Modern Android devices can have different types of processors: x86-64, x86, ARMv7, and ARMv8. For code written in Java or Kotlin, this is not an issue, as it is executed in a virtual machine and abstracted from the specific hardware. However, for native code, processor type plays an important role.

Therefore, our library contains 4 versions for all ABI (Application Binary Interface) types to provide support for all these processor types.

Size optimization

To reduce the size of your application, you can use splitting APKs by ABI type. This will ensure that only the necessary libraries for a specific user device are built and loaded. See the Android documentation for instructions on building and uploading. Also, if you are using an Android App Bundle, Google Play can automatically rebuild the app for the required processor types of specific user devices.

Size check

To see the actual size of the APK that will be downloaded by the user, it is recommended to use the bundletool tool. This will help to get an APK containing only the required libraries for a particular device:

1. Build an app bundle, selecting this build option in Gradle.
2. Get APK with necessary criteria (for example, only for arm64-v8a) from the app bundle using bundletool.

The resulting APK will reflect the actual size the user gets when downloading the app from Google Play.