Optima Smart Display API

Request

GET <vms_hostname>[:port]/vms/

Request parameters

You need to have one of the two following tuples of parameters in the request. They are used to geographically locate the messages provided by Optima.

• (id, fromnode)
• (slon, slat, sdir)

Important:   Do not use both tuples in the same request.

Parameter	Required	Description
treq	YES	Request type. Required. Must be findMessageList.
id	YES	ID of the strt element of the TDE data model. Optional. Must be used in conjunction within fromnode. In case of multiple requests, you can specify different IDs separated by commas. The number of IDs must be equal to the number of nodes in the fromnode parameter.
fromnode	YES	ID of the From node of the strt element of the TDE data model. Optional. Must be used in conjunction with id. In case of multiple requests, you can specify different nodes separated by commas.
slon	YES	WGS84 point longitude. Optional. If used, must be used in conjunction with slat and sdir. Can be expressed in geographic or projected coordinates, depending on the value of GEOC in the data source DS_OPT: If GEOC = 1, coordinates must be geographic If GEOC = 0, coordinates must be projected In case of multiple requests, you can specify different longitudes separated by commas. The number of longitudes must be the same as in slat and in sdir.
slat	YES	WGS84 point latitude. Optional. If used, must be used in conjunction with slon and sdir. Can be expressed in geographic or projected coordinates, depending on the value of GEOC in the data source DS_OPT: If GEOC = 1, coordinates must be geographic If GEOC = 0, coordinates must be projected In case of multiple requests, you can specify different latitudes separated by commas. The number of latitudes must be the same as in slon and in sdir.
sdir	YES	Angle in radiant with respect to the North. Optional. If used, must be used in conjunction with slon and slat. In case of multiple requests, you can specify different values separated by commas. The number of values must be the same as in slon and in slat.

Request content-type

N/A

Request entity

N/A

Response status

HTTP status	Description
102	Unknown request
200	OK / solved

Response content-type

application/xml

Response entity

The VMS output is an XML message compliant with the format defined in the XSD scheme VMS_multiple_response.xsd. The VMS output is printed at the same request address.

The main node has the name <VMS_multiple_response>. It has the following attributes:

• status: Reports the request status
• number_of_response: Reports the number of requests performed.

The main node <VMS_multiple_response> contains one or more subnodes <VMS_response>, which each have the following attributes:

• status: Reports the response status. Can be solved or error (or notReady if the software is still in the loading process of the network).
• number_of_event: Number of active messages on the network.
• street_id: Input street ID (or the street computed from the input coordinates).
• street_fromnode: From node of the input street (or the street computed from the input coordinates).
• lat: Point latitude. This value is provided if the input link in the request is expressed in geographic coordinates.
• lng: Point longitude. This value is provided if the input link in the request is expressed in geographic coordinates.
• dir: Angle expressed in radiants between the point and the North. This value is provided if the input link in the request is expressed in geographic coordinates.

The node <VMS_response> has n sibling nodes <VMS_message>, depending on the number of events. These sibling nodes each have the following attributes:

• event_id: ID of the event (string).
• event_code: Code of the event (integer).
• situation_id: Situation of the event (string).
• priority: Priority of the event (double).
• norm_prio: Normalized priority of the event (double [0, 1]).
• pass: Absolute priority of the event (double).
• eProb: Relative priority of the event (double).
• timeDistance: Minimum time in seconds to reach the event (double).

Request

http://hostname:1800/vms/?treq=findMessageList&id=55224168&fromnode=65183887

Response status

200

Response output

<VMS_multiple_response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" status="solved"> 
    <VMS_response status="solved" number_of_event="2" street_id="55223893" street_fromnode="65175012"> 
        <VMS_message event_id="evento_1" event_code="1" situation_id="manifestazione" priority="3.23298856717326E-06" pass="100" eProb="3.23298856717326E-08" timeDistance="1234"/> 
        <VMS_message event_id="evento_2" event_code="2" situation_id="incidente" priority="1.15768362294338E-06" pass="100" eProb="1.15768362294338E-08" timeDistance="1357"/> 
    </VMS_response> 
</VMS_multiple_response>

Request

http://hostname:1800/vms/?treq=findMessageList&id=55224168&fromnode=65183887

Response status

200

Response output with status = “solved”

<VMS_multiple_response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" status="solved">
   <VMS_response status="solved" number_of_event="0"/>
</VMS_multiple_response>

Response output with status = “error”

Output with status=”error”
<VMS_multiple_response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" status=" error ">
   <VMS_response status="error">
      <VMS_err code="105" errt="ErrorWrongOriginInfo"/>
   </VMS_response>
</VMS_multiple_response>

Request

http://hostname:1800/vms/?treq=findMessageList&id=55224168,55224169&fromnode=65183887,65183888

Response status

200

Response output

<VMS_multiple_response status="solved" number_of_response="2">
   <VMS_response status="solved" number_of_event="69" street_id="55222396" street_fromnode="65175284" lat="0" lng="0" dir="0">
   </VMS_response>
   <VMS_response status="solved" number_of_event="69" street_id="55222396" street_fromnode="65175284" lat="0" lng="0" dir="0">
   </VMS_response>
</VMS_multiple_response>