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.
The version is valid for SDK29.
Hereby attached is a JSON schema of what the file itself should look like:
{
"$schema": "https://json-schema.org/draft-07/schema",
"id": "CustomPlacesV2_1",
"title": "Custom Places Import Format",
"type": "object",
"properties": {
"add_or_update": {
"type": "array",
"description": "An array of Places, which should be added or updated",
"items": {
"$ref": "#/$defs/place"
}
}
},
"$defs": {
"place": {
"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)."
},
"dataset": {
"type": "string",
"description": "Unique identifier of dataset. Default dataset for older, already installed places is bf19e514-487b-43c4-b0df-9073b2397dd1."
},
"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"
]
}
},
"ev_charger": {
"$ref": "#/$defs/extensions/ev_charger"
},
"opening_hours": {
"$ref": "#/$defs/extensions/opening_hours"
},
"vehicle_restriction": {
"$ref": "#/$defs/extensions/vehicle_restriction"
},
"available_payment_methods": {
"$ref": "#/$defs/extensions/payment_method"
},
"service_providers": {
"type": "array",
"description": "Labels of Service Provider, which provide services at this Place.",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"dataset",
"iso",
"location",
"category",
"search_priority",
"display_name"
]
},
"extensions": {
"ev_charger": {
"type": "object",
"description": "Definition of EV Charging Station",
"properties": {
"is_public": {
"description": "Defines whether the charging station is publicly available or not.",
"type": "boolean"
},
"is_free_of_charge": {
"description": "Defines whether the charging station can be used free of charge.",
"type": "boolean"
},
"operator": {
"description": "Name or Identifier of the charging station operator.",
"type": "string"
},
"external_id": {
"description": "ID which can be used to identify this charging station in Third Party Services.",
"type": "string"
},
"evse": {
"description": "Electric Vehicle Supply Equipments (or charging \"spots\") avaialble for this charging station.",
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/electric_vehicle/evse"
}
}
},
"required": [
"evse"
]
},
"opening_hours": {
"type": "object",
"description": "Information about opening hours of this place.",
"properties": {
"nonstop": {
"description": "Indicates that this place is open 24/7.",
"type": "boolean"
}
}
},
"vehicle_restriction": {
"type": "object",
"description": "Information about vehicle restrictions applicable when entering this place.",
"properties": {
"total_weight": {
"description": "Total vehicle weight in kilograms (kg)",
"$ref": "#/$defs/value_range"
},
"total_width": {
"description": "Total vehicle width in meters (m)",
"$ref": "#/$defs/value_range"
},
"total_length": {
"description": "Total vehicle length in meters (m)",
"$ref": "#/$defs/value_range"
},
"total_height": {
"description": "Total vehicle height in meters (m)",
"$ref": "#/$defs/value_range"
}
}
},
"payment_method": {
"description": "Information about payment methods which can be used at this place.",
"type": "array",
"uniqueItems": true,
"items": {
"enum": [
"cash",
"exact_cash",
"checque",
"wire_transfer",
"electronic_purse",
"debit_card",
"credit_card",
"fuel_card",
"payment_via_phone",
"public_transport",
"road_toll",
"cryptocurrency",
"digital_wallet",
"government_assistance_program",
"paypal"
]
}
}
},
"value_range": {
"type": "object",
"properties": {
"min": {
"type": "number",
"minimum": 0.0
},
"max": {
"type": "number",
"minimum": 0.0
}
},
"anyOf": [
{
"required": [ "min" ]
},
{
"required": [ "max" ]
}
]
},
"electric_vehicle": {
"evse": {
"type": "object",
"properties": {
"authorization_support": {
"type": "array",
"uniqueItems": true,
"items": {
"enum": [
"rfid_chip",
"mobile_application"
],
"$comment": "ToDo: more authorization methods?"
}
},
"charging_connector": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"maximal_power": {
"description": "Maximal charging power through this connector, in Watts (W)",
"type": "integer",
"exclusiveMinimum": 0
},
"voltage": {
"description": "Charging voltage provided by this connector, in Vols (V).",
"type": "integer",
"exclusiveMinimum": 0
},
"external_id": {
"description": "ID which can be used to identify this charging connector in Third Party Services.",
"type": "string"
},
"connector_type": {
"$ref": "#/$defs/electric_vehicle/charging_connector_type"
},
"connector_format": {
"$ref": "#/$defs/electric_vehicle/charging_connector_format"
},
"charging_current": {
"$ref": "#/$defs/electric_vehicle/electrical_current_type"
}
},
"required": [
"maximal_power",
"connector_type",
"connector_format"
]
}
}
},
"required": [
"charging_connector"
]
},
"charging_connector_type": {
"description": "Type of the Charging Connector.",
"enum": [
"type1",
"type2",
"type3",
"ccs1",
"ccs2",
"chademo",
"tesla",
"household_any",
"household_type_e",
"household_type_f",
"household_type_j",
"household_type_g",
"cee_blue",
"cee_red",
"cee_plus",
"nema5",
"nema14",
"chinagb2",
"chinagb3"
]
},
"charging_connector_format": {
"description": "Describes whether we are dealing with charging socket (lower power chargers, such as electrical outlet at home) or a cable",
"enum": [
"unknown",
"socket",
"cable"
]
},
"electrical_current_type": {
"description": "Type of electrical current. Either Direct or Alternating.",
"enum": [
"ac",
"dc"
]
}
}
}
}