Skip to content

Online and Offline maps

Online maps

The fastest and most easy way to display a map is to turn on the online maps. They are downloaded dynamically depending on the camera position and are cached once downloaded. There are several ways on how to enable online maps. If you want to use online maps directly after the initialization, enable it through the JSON configuration.

val config = SygicEngine.JsonConfigBuilder()
config.mapReaderSettings().startupOnlineMapsEnabled(true)

To turn the online maps on and off dynamically, use the OnlineManager's enableOnlineMapStreaming().

OnlineManagerProvider.getInstance().get().enableOnlineMapStreaming(object : OnlineManager.MapStreamingListener {
    override fun onSuccess() {
    }

    override fun onError(errorCode: OnlineManager.MapStreamingError?) {
    }
})
OnlineManagerProvider.getInstance().get().disableOnlineMapStreaming(object : OnlineManager.MapStreamingListener {
    override fun onSuccess() {
    }

    override fun onError(errorCode: OnlineManager.MapStreamingError?) {
    }
})

Note

Please note that offline routing can not be executed on cached online maps. Downloaded offline maps are necessary.

If you download an offline map of a country and load it, the online map of that country won't be downloaded.

Offline Maps

Applications developed with the Sygic Maps SDK for Android have the ability to pre-load map data, allowing the use of maps, search, routing, and other features without an active data connection. Let's dive right in.

We will work with an instance of MapLoader.

You can get the MapLoader just like any other instance - via the MapLoaderProvider.

The available maps are now requested using one call, only (no more Regions -> Countries). The first parameter signifies whether you want to get the maps that are installed in your device already or the ones that are available online. false - online request, true - downloaded maps. The response is cached for 2 hours after the first available maps request and the next requests are therefore almost instantaneous.

If you would like to get the CountryDetails (such as continentName - using which you can sort the countries into continents, name, regions - if it's a country split map, it will have regions which can be downloaded separately according to their ISO codes, totalSize), the usage is shown in the brief sample below. Again, you can choose whether you would like to explore an online or an already downloaded country.

Attention

Remember, that each map needs to be loaded after being downloaded.

Please always use the ISO codes that you get from the MapLoader as it's not guaranteed that the MapLoader always operates with the ISO 3166 alpha-2 standard.

MapLoader mMapLoader;
MapLoaderProvider.getInstance(new CoreInitCallback<MapLoader>() {
    @Override
    public void onInstance(@NonNull MapLoader mapLoader) {
      mMapLoader = mapLoader;
    }

    @Override
    public void onError(@NonNull CoreInitException e) {
    }
});

MapResultListener mapResultListener = new MapResultListener() {
    @Override
    public void onMapResult(@NotNull String s, @NotNull MapLoader.LoadResult loadResult) {
        //load the map (mMapLoader.loadMap(s))
    }
};

mMapLoader.getAvailableCountries(false, new MapListResultListener() {
    @Override
    public void onMapListResult(@NotNull List<String> list, @NotNull MapLoader.LoadResult loadResult) {
        if (loadResult.equals(MapLoader.LoadResult.Success)) {
            mMapLoader.getCountryDetails(list.get(0), false, new MapCountryDetailsListener() {
            @Override
            public void onCountryDetails(@NotNull CountryDetails countryDetails) {
                mCountryDetails = countryDetails;
            }
            @Override
            public void onCountryDetailsError(@NotNull MapLoader.LoadResult loadResult) {
            }
        });
        mMapLoader.installMap(list.get(0), mapResultListener);
        }
        else {
            //error
        }
    }
});

Since the version 17, there's a new functionality - you can now detect a country of where you're located using your IP address and get its ISO code by passing an empty string. If you pass it a region ISO code, you will get the ISO code of the country.

mMapLoader.detectCurrentCountry("", object : MapResultListener {
    override fun onMapResult(mapIso: String, result: MapInstaller.LoadResult) {
        //here you can just call the mMapLoader.installMap(mapIso) to install it directly
    }
})
mMapLoader.detectCurrentCountry("", new MapResultListener() {
    @Override
    public void onMapResult(@NotNull String mapIso, @NotNull MapLoader.LoadResult loadResult) {
        //here you can just call the mMapLoader.installMap(mapIso) to install it directly
    }
});

You can add an install progress listener or resume the pending installations like this:

mMapLoader.addMapProgressInstallListener(new MapInstallProgressListener() {
    @Override
    public void onMapInstallProgress(String s, long l, long l1) {
    }
});
mMapLoader.resumePendingInstallations(new MapLoaderResumeInfoListener() {
    @Override
    public void onInfoProvided(@NotNull List<ResumedMapLoaderOperation> list, 
                               @NotNull List<ResumedMapLoaderOperation> list1,
                               @NotNull MapLoader.LoadResult loadResult) {
    }
});

Do not forget to remove the listener once you don't need it anymore.

How to cancel a download

The installMap operation is a MapLoader's task, therefore:

MapLoader.Task task = mMapLoader.installMap("iso", mapResultListener);
task.cancel();

How to check for updates and update the maps

Here's an example of how to check for updates and update the map. Please bear in mind that it serves just as an example and will probably be much more complex in your app.

mMapLoader.checkForUpdates(object : MapListResultListener {
  override fun onMapListResult(
      mapIsos: List<String>,
      result: MapInstaller.LoadResult
  ) {
      if (result == MapInstaller.LoadResult.Success) {
          for (mapIso in mapIsos) {
              // if the map is a split map, you will get all of the regions along with the
              // base map e.g. "de", "de-02", "de-04" - it is enough to call the
              // update for "de" and it will update all of the installed regions
              mMapLoader.updateMap(mapIso, object: MapResultListener{
                  override fun onMapResult(
                      mapIso: String,
                      result: MapInstaller.LoadResult
                  ) {
                      if (result == MapInstaller.LoadResult.Success) {
                          mMapLoader.loadMap(mapIso, object: MapResultListener{
                              override fun onMapResult(
                                  mapIso: String,
                                  result: MapInstaller.LoadResult
                              ) {

                              }
                          })
                      }
                  }
              })
          }
      }
  }
})

Clearing the cache

If you would need to clear the cache of mapLoader for any reason, you can do it like this :

 mMapLoader.clearCache(object: ResultListener {
    override fun onResult(result: MapInstaller.LoadResult) {
        // your code
    }
})

Changing the language of the names received via getCountryDetails

To avoid the necessity of translating the names of countries received via the getCountryDetails() call, you can set the locale of the MapLoader first. Note that this creates a new request just like requesting all of the available maps - the whole map list gets cached in the language that is set. The language tag has to be in the BCP 47 format.

mMapLoader.setLocale("en-US", object: ResultListener {
    override fun onResult(result: MapInstaller.LoadResult) {
        // your code
    }
})