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": "Set of Places, which should be added or updated.",
      "type": "array",
      "items": {
        "type": "object",
        "description": "Custom Place Definition",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique, integrator mainained ID. Used for further updates/deletes on the Place. Must follow RFC 4122 GUID standard (see https://www.ietf.org/rfc/rfc4122.txt)."
          },
          "iso": {
            "type": "string",
            "description": "ISO 3166-1 Alpha-2/ISO 3166-2 code of the country/region, in which the Place is located."
          },
          "location": {
            "type": "string",
            "description": "Location of the Place, in the form of geographic coordinates in decimal degrees, separated by a comma, latitude being followed by longitude",
            "pattern":"^-?((90(\\.0+)?)|(([1-8]?\\d)(\\.\\d+)?)),\\s*-?((180(\\.0+)?)|((([1-9]?\\d)|(1[0-7]\\d))(\\.\\d+)?))$"
          },
          "entry_location": {
            "type": "string",
            "description": "Entry Location of the Place (e.g. gate of an industrial area), in the form of geographic coordinates in decimal degrees, separated
            by a comma, latitude being followed by longitude",
            "pattern":"^-?((90(\\.0+)?)|(([1-8]?\\d)(\\.\\d+)?)),\\s*-?((180(\\.0+)?)|((([1-9]?\\d)|(1[0-7]\\d))(\\.\\d+)?))$"
          },
          "category": {
            "type": "string",
            "description": "ID of a Custom, or Sygic, Place Category."
          },
          "search_priority": {
            "type": "integer",
            "description": "Search Priority of the Place. Priorities are represented by the following table:
            15 - internationally known place with higher importance
            14 - internationally known place
            13 - internationally known place with lower importance
            12 - nationally known place with higher importance
            11 - nationally known place
            10 - nationally known place with lower importance
            9 - regionally known place with higher importance
            8 - regionally known place
            7 - regionally known place with lower importance
            6 - place known within municipality with higher importance
            5 - place known within municipality
            4 - place known within municipality with lower importance
            3 - place known within city district with higher importance
            2 - place known within city district
            1 - place known within city district with lower importance",
            "minimum": 1,
            "maximum": 15
          },
          "display_name": {
            "type": "array",
            "description": "A set of display names (human readable texts), in various languages, for the Place. Intended for user interaction.",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string",
                  "description": "Title of the Place."
                },
                "subtitle": {
                  "type": "string",
                  "description": "Subtitle of the place."
                },
                "lng": {
                  "type": "string",
                  "description": "BCP47 Language Tag specifying the language of the display_name entry."
                },
                "search_tokens": {
                  "type": "array",
                  "description": "Set of search tokens for the display_name entry, in the same language specified by the 'lng' field.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "index": {
                        "type": "string",
                        "description": "Space-separated search tokens, used for entry indexing."
                      },
                      "refinement": {
                        "type": "string",
                        "description": "Space-separated search refinement tokens, 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\" 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 for the Place. Sygic services don't modify, nor read these data. Instead, they are passed to the integrator,
            where they can be read as needed.",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "values": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "key",
                "values"
              ]
            }
          }
        },,
        "dataset": {
          "type": "string",
          "description": "Unique identifier of dataset. Default dataset for older, already installed places is bf19e514-487b-43c4-b0df-9073b2397dd1."
        },
        "required": [
          "id",
          "iso",
          "location",
          "category",
          "display_name"
        ]
      }
    },
    "to_remove": {
      "description": "Set of Place Object IDs, which should be removed.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "Integrator maintained ID of the Place."
      }
    }
  }
}