Skip to content

Custom Places

Introduction

It is possible to import and use your own POIs (called Places). There are two ways how to import Places:

  • as a JSON file that has a specific structure.
  • by uploading them via Custom Places API and downloading them at any point in the app using MapsSDK

In this article, we will cover both aforementioned ways of importing Places.

Datasets

Since SDK 24.0, it is possible to have multiple datasets of custom places and switch between them. If you have already had custom places in your app, they will be automatically assigned to the default dataset. The ID of the default dataset is "bf19e514-487b-43c4-b0df-9073b2397dd1".

Import as a JSON

There is a possibility of importing places as a JSON file.

Warning

Please note that after importing, the places are indexed and stored in the app's database. This may take some time during which the places may not be available for search.

Information on how to import the JSON for each platform can be found here:

Uploading to API

Alternatively, you can upload the Custom Places to our API and then download them in the application via the SDK. This can be summed up in a few steps:

  1. Prepare your Custom Places JSON
  2. Request a token from our Authentication API
  3. Send the places as a body to the Custom Places API
  4. Download the places in your app
  5. Enjoy

Please find more info here: Custom Places API.

Installing by downloading from server

We have separated this for each platform. Please follow the instructions for your platform:

Searching and indexing

You can define search indexes and refinement tokens for each display name's language.

Index holds all search tokens by which you would like to find the specific Place.

Then, the refinement tokens are used for entry refinement index. Refinement alone does not suffice for result to be found but acts as addition to index. For example: index: "Slovnaft", refinement: "bathroom": when searching for "Slovnaft" result is found. When searching only for "bathroom", the result is not found. When searching for "Slovnaft bathroom" result is found and refined (other "Slovnaft" matching results are discarded).

Therefore, we recommend to not put "general" tokens into the index field. For example, it is wise to put postal codes or city names into refinement. That way if you search for a postal code or for a city name, no Places will pop up.

Custom Place Categories

You can also define your own categories for your Custom Places. Even if this is not necessary for the Custom Places to work, after defining the categories you can search for them using the searchPlaces method. Having place categories also lets you filter out your categories from being shown on the map (using the PlacesManager's setVisibleCategories() method).

Flowchart for Places stored on the server

graph LR
A[Custom Places JSON] --> |Add or update| B[Online Custom Places API]
A --> |Remove| B
B --> |Install| C[Local Storage]
B --> |Remove| C
B --> |Update| C
C --> D[Search]
C --> E[Show on map]

Flowchart for Places sideloaded via JSON

graph LR
A[Custom Places JSON] --> |Add or update| B[Local storage]
A --> |Remove| B
B --> C[Search]
B --> D[Show on map]

Sample custom place JSON

Note

If a new unique id is provided, the place is added. If the id already exists, the place is updated.

{
  "add_or_update": [
    {
      "id": "3047426d-849b-de0b-e82a-24c699c0b9a4",
      "iso": "sk",
      "dataset": "dataset-name",
      "location": "48.35264518441125, 18.721255079098444",
      "entry_location": "48.35264518441125, 18.721255079098444",
      "category": "custom_hotel_category",
      "search_priority": 15,
      "display_name": [
        {
          "title": "Pukanec De Luxe Hotel",
          "subtitle": "Bratská, Petržalka 85104, Slovensko",
          "lng": "sk",
          "search_tokens": [
            {
              "index": "hotel",
              "refinement": "hotel de luxe pukanec"
            }
          ]
        },
        {
          "title": "l'hotel de pukanec",
          "subtitle": "Hotel motel francais de luxe",
          "lng": "fr",
          "search_tokens": [
            {
              "index": "pukanec hotel",
              "refinement": "hotel de luxe"
            }
          ]
        }
      ]
    }
  ],
  "to_remove": [
    "UUID"
  ]
}