Skip to content

Custom Places JSON Schema

Since the SDK21, the integrator can add their own Custom POIs that we call Custom Places. One of the options how to add them is to import a JSON file that contains the information.

Hereby attached is a JSON schema of what the file itself should look like:

{
  "id": "CustomPlacesImport",
  "title": "Custom Places Import Format",
  "type": "object",
  "properties": {
    "add_or_update": {
      "description": "An array of Places, which should be added or updated",
      "type": "array",
      "items": {
        "type": "object",
        "description": "Custom Place",
        "properties": {
          "id": {
            "type": "string",
            "description": "Integrator maintained id. Used for further updates/deletes on the Places."
          },
          "iso": {
            "type": "string",
            "description": "Country ISO 3166-2 code."
          },
          "location": {
            "type": "string",
            "description": "Location of POI. Determines where pin on map will be placed. Format: {lat,lon}"
          },
          "entry_location": {
            "type": "string",
            "description": "Entry location of POI. Determines where routing will navigate (e.g. gate of industrial area)."
          },
          "category": {
            "type": "string",
            "description": "Whatever value provided by integrator in Category.Id. Used for visualization purposes."
          },
          "search_priority": {
            "type": "integer",
            "description": "The larger the higher rank in fulltext search (if same name/distance from other POI). Values 1-15.",
            "minimum": 1,
            "maximum": 15
          },
          "display_name": {
            "type": "array",
            "description": "Used for displaying autocomplete call results.",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "subtitle": {
                  "type": "string"
                },
                "lng": {
                  "type": "string",
                  "description": "BCP47 Language Tag"
                },
                "search_tokens": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "index": {
                        "type": "string",
                        "description": "Value will be used for record category indexing. At least one value must be matched in order to find a result."
                      },
                      "refinement": {
                        "type": "string",
                        "description": "Value will be used for record 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\" result is not found. When searching for \"Slovnaft bathroom\" result is found 
                        and refined (other \"Slovnaft\" matching results are discarded)."
                      }
                    },
                    "required": [
                      "index"
                    ]
                  }
                }
              },
              "required": [
                "title"
              ]
            }
          },
          "place_data": {
            "type": "array",
            "description": "Custom data. SDK doesn't interpret these, this just serves upon request to integrator's app.",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "values": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "key",
                "values"
              ]
            }
          }
        },
        "required": [
          "id",
          "iso",
          "location",
          "category",
          "display_name"
        ]
      }
    },
    "to_remove": {
      "description": "An array of Place Object IDs, which should be removed",
      "type": "array",
      "items": {
        "type": "string",
        "description": "Integrator maintained ID"
      }
    }
  }
}