Skip to content

Custom Places

It is possible to add custom Points of Interest (POIs). We call them Places. Places can be used for example to show the user's favorite places or places that are not available in the Sygic database. To be able to show custom places on the map, it is necessary to inject a skin definition for them.

In the next chapters, we will see how to import custom places from a JSON file, how to install them from the server or how to use them without downloading them.

Enabling Custom Places and modes

To enable custom places at startup, it is necessary to set Custom Places as the startupPoiProvider in the JSON Config:

"MapReaderSettings": {
    "startup_poi_provider": "CustomPlaces",
}

By setting the Custom Places POI provider at startup, both map places and custom places will be visible in the map.

Setting the mode

There are two modes in which custom places can be used:

  • Offline
  • Online

Online mode means that the places are downloaded from the server while browsing the map or along the calculated route. This mode is suitable for places that are frequently updated. This is automatically managed by the SDK.

Offline mode means that the places are downloaded using the methods described below and stored in the app's database. They are not continually downloaded from the server.

Important

Before using the online or offline mode, it is necessary to set it like this: SYCustomPlacesManager.shared()?.mode = .offline

Tip

Depending on your preferences, it might be a good idea to download the offline places upon downloading a map as the places are tied to iso codes (and you get them via SYMapInstaller). Then, you can update them according to your needs.

Injecting a skin for Custom Places

To be able to see custom places on the map, you need to inject a skin definition for them. The skin definition is defined by a JSON that contains the style of the custom places, basically for groups and categories. Below is a sample of importing the skin definition:

Important

If not defined in the skin_default.xml file, it will be necessary to inject the skin at each mapView creation.

let skinDefinitionToInject = """
    {
      "skin": {
        "poi_categories": {
          "custom": {
            "groups": {

              "SYPotato": {
                "enabled": true,
                "color": "0xb38c00ff",
                "icon": "0xe335",
                "priority": 24,
                "showWithoutText": true,
                "zoomLevel": 17.9
              }
            },
            "categories": {
              "new_custom_category": {
                "groupId": "SYPotato"
              },
              "anotherCategory": {
                "groupId": "SYPotato"
              }
            }
          }
        }
      }
    }
    """

mapView.injectSkinDefinition( skinDefinitionToInject ) { result in
    print("skin injected with result: \(result)")
}

Importing Custom Places from a JSON file

After having a JSON file with custom places ready, it is possible to import it using the following code:

SYCustomPlacesManager.shared()?.installOfflinePlaces(fromJson: "as_a_string") { error in
    // do something
}

If you do not define a "dataset", the places wil be imported into the default dataset. The ID of the default dataset is "bf19e514-487b-43c4-b0df-9073b2397dd1".

Deleting Custom Places using a JSON file

It is also possible to delete custom places using a JSON file. For example, if you want to remove the custom place from custom places article, your JSON file would look like this:

{
  "to_remove": [
    "3047426d-849b-de0b-e82a-24c699c0b9a4"
  ]
}

Then, just call the same method as above to install the places. The place will be removed from the database. Removing is specified by the "to_remove" key in the JSON file. You can add/update and remove places in the same JSON file.

Installing custom places from server

After having the custom places uploaded to the server, it is possible to install them in your app. For further information about uploading the places to the server, please see the Custom Places API and the the Custom Places article

Installing

To install custom places from the server, you need to call the following method:

SYCustomPlacesManager.shared()?.installOfflinePlaces(fromDatasets: ["dataset_name"], forCountry: "iso", progress: { progress in
    print("progress: " + String(progress.loadedRecords) + "/" + String(progress.totalRecords))
}, completion: { error in
    print("finished " + error.debugDescription)
})

The method above installs places of the specified dataset for the specified country iso. Alternatively, you can install all datasets of a specific country:

SYCustomPlacesManager.shared()?.installOfflinePlaces(fromDatasets: [], forCountry: "iso", progress: { progress in
    print("progress: " + String(progress.loadedRecords) + "/" + String(progress.totalRecords))
}, completion: { error in
    print("finished " + error.debugDescription)
})

Or, you can install one dataset for all countries:

SYCustomPlacesManager.shared()?.installOfflinePlaces(fromDatasets: ["dataset_name"], forCountry: nil, progress: { progress in
    print("progress: " + String(progress.loadedRecords) + "/" + String(progress.totalRecords))
}, completion: { error in
    print("finished " + error.debugDescription)
})

Uninstalling

To uninstall custom places from the server, you need to call one of the following methods:

// this one uninstalls the specific dataset of the specific country
SYCustomPlacesManager.shared()?.uninstallOfflinePlaces(fromDatasets: ["dataset_name"], forCountry: "iso", completion: { error in
    print("uninstalled with status: " + error.debugDescription )
})

// and using this method, you can uninstall all datasets of the specific country
SYCustomPlacesManager.shared()?.uninstallOfflinePlaces(forCountry: "iso", completion: { error in
    print("uninstalled with status: " + error.debugDescription )
})

Updating

To update custom places from the server, you need to call the following method:

Note

Please note that this method updates all of the installed places, not just the ones from the specified country.

SYCustomPlacesManager.shared()?.updateInstalledPlaces(progress: { progress in
    print("progress: " + String(progress.loadedRecords) + "/" + String(progress.totalRecords))
}, completion: { error in
    print("finished " + error.debugDescription)
})

You can read more about the Custom Places Search in the Custom Places Search article.