Pushing traffic states with ORCAv2

This endpoint enables you to handle information about speed and flow in your traffic network, according to ORCAv2 protocol (see ORCA2.xsd).

Authentication phase

Before using the endpoint, you must run the authentication phase (→ Login).

After the authentication, a session opens and a valid session token persists until:

Request

POST 

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate

The supported locations are:

  • strt : In the payload see xsi:type="StreetTraffic"

    <trafficElement xsi:type="StreetTraffic".../>

  • openlr : in the payload, see xsi:type="OpenLRTraffic"

    <trafficElement xsi:type="OpenLRTraffic".../>

  • ploc : in the payload, see xsi:type="PLOCTraffic"

    <trafficElement xsi:type="PLOCTraffic".../>

  • cloc : in the payload, see xsi:type="ClocTraffic"

    <trafficElement xsi:type="ClocTraffic".../>

  • detector : in the payload, see xsi:type="DetectorTraffic"

    <trafficElement xsi:type="DetectorTraffic".../>

For more details, please see → Basics on locations.

Request parameters

Not applicable.

Request content-type

application/xml

Request body (payload)

XML message describing a scenario as defined in orca2.xsd.

In the payload, you can set the optional parameter status as attribute of the tag <trafficElement.../>.

<trafficElement xsi:type="..." code="..." status="0".../>

Values for status:

  • status=0: OK
  • status=1: WARNING
  • status=2: KO, NOT WORKING

If the attribute status is not provided, trafficastate.status=null.

Tip:  The correct policy it is to always provide the attribute status.

Here are the attributes that you can specify in the payload:

Traffic element (complexType) Attributes associated

ClocTraffic

List of attributes:

Attribute Descrption

cloc

Data type: Integer

Required: YES

Identifier of the count location. Count locations determine the location associated with each traffic count.

status

Data type: Integer.

Required: NO (optional).

TDE status semantic.

Possible values:

  • 0 = OK

  • 1 = PARTLY_OK

  • 2 = DEFECT

flow

Data type: Double.

Required: NO (optional).

Average traffic flow (vehicles/h).

sped

Data type: Double.

Required: NO (optional).

Average traffic speed(km/h).

accu

Data type: orca2:Reliability

Required: YES.

Accuracy of the measurement/estimation. It can be used by the Harmonizer to discard unreliable data from the simulation.

startTime

Data type: dateTime (string formatted as ISO 8601, with or without timezone).

Required: NO (optional).

Starting instant when a traffic element starts to be valid.

endTime

Data type: dateTime (string formatted as ISO 8601, with or without timezone).

Required: NO (optional).

Ending instant when a traffic element stops being valid.

tsys

In an Optima model, the transport systems (tsys) are all the available ways to transport persons and goods.

Every model can have its different list of transportation systems: car, bus, train, etc.

Required: NO (optional)

Example: tsys="CAR"

DetectorTraffic

List of attributes:

Attribute Descrption

code

  • Data type: String
  • Required: YES
  • Language: en-US> Name of the detector

status

Data type: Integer.

Required: NO (optional).

TDE status semantic.

Possible values:

  • 0 = OK

  • 1 = PARTLY_OK

  • 2 = DEFECT

flow

Data type: Double.

Required: NO (optional).

Average traffic flow (vehicles/h).

sped

Data type: Double.

Required: NO (optional).

Average traffic speed(km/h).

accu

Data type: orca2:Reliability

Required: YES.

Accuracy of the measurement/estimation. It can be used by the Harmonizer to discard unreliable data from the simulation.

startTime

Data type: dateTime (string formatted as ISO 8601, with or without timezone).

Required: NO (optional).

Starting instant when a traffic element starts to be valid.

endTime

Data type: dateTime (string formatted as ISO 8601, with or without timezone).

Required: NO (optional).

Ending instant when a traffic element stops being valid.

tsys

In an Optima model, the transport systems (tsys) are all the available ways to transport persons and goods.

Every model can have its different list of transportation systems: car, bus, train, etc.

Required: NO (optional)

Example: tsys="CAR"

OpenLRTraffic

List of attributes:

Attribute Descrption

code

Data type: String.

Required: NO (optional).

OpenLR base64 location code.

lane

Data type: Integer.

Required: NO (optional).

Lane index. Lanes can be either approach lanes or normal lanes. In case you specify a lane with an N value, the traffic is considered an attribute to the Nth lane. This N value must be lower than the maximum between the number of approach and normal lanes as modeled in the network.

accu

Data type: orca2:Reliability

Required: YES.

Accuracy of the measurement/estimation. It can be used by the Harmonizer to discard unreliable data from the simulation.

startTime

Data type: dateTime (string formatted as ISO 8601, with or without timezone).

Required: NO (optional).

Starting instant when a traffic element starts to be valid.

endTime

Data type: dateTime (string formatted as ISO 8601, with or without timezone).

Required: NO (optional).

Ending instant when a traffic element stops being valid.

tsys

In an Optima model, the transport systems (tsys) are all the available ways to transport persons and goods.

Every model can have its different list of transportation systems: car, bus, train, etc.

Required: NO (optional)

Example: tsys="CAR"

PLOCTraffic

List of attributes:

Attribute Descrption

pril

Data type: String.

Required: YES.

Predefined location, primary location.

secl

Data type: String.

Required: YES.

Predefined location, secondary location.

fprg

Data type: Float.

Required: YES.

Predefined location, from progressive.

fprg is a number in the range [0,1] that defines the start point of the segment as a proportion of the entire street length.

tprg

Data type: Float.

Required: YES.

Predefined location, to progressive.

tprog is a number in the range [0,1] that defines the end point of the segment as a proportion of the entire street length.

lane

Data type: Integer.

Required: NO (optional).

Lane index. Lanes can be either approach lanes or normal lanes. In case you specify a lane with an N value, the traffic is considered an attribute to the Nth lane. This N value must be lower than the maximum between the number of approach and normal lanes as modeled in the network.

flow

Data type: Double.

Required: NO (optional).

Average traffic flow (vehicles/h).

sped

Data type: Double.

Required: NO (optional).

Average traffic speed(km/h).

accu

Data type: orca2:Reliability

Required: YES.

Accuracy of the measurement/estimation. It can be used by the Harmonizer to discard unreliable data from the simulation.

startTime

Data type: dateTime (string formatted as ISO 8601, with or without timezone).

Required: NO (optional).

Starting instant when a traffic element starts to be valid.

endTime

Data type: dateTime (string formatted as ISO 8601, with or without timezone).

Required: NO (optional).

Ending instant when a traffic element stops being valid.

tsys

In an Optima model, the transport systems (tsys) are all the available ways to transport persons and goods.

Every model can have its different list of transportation systems: car, bus, train, etc.

Required: NO (optional)

Example: tsys="CAR"

StreetTraffic

List of attributes:

Attribute Descrption

strt

Data type: Integer.

Required: YES.

Identifier of the street network element.

fsnd

Data type: Integer.

Required: YES.

Identifier of the tail (initial node) of the street network element.

lane

Data type: Integer.

Required: NO (optional).

Lane index. Lanes can be either approach lanes or normal lanes. In case you specify a lane with an N value, the traffic is considered an attribute to the Nth lane. This N value must be lower than the maximum between the number of approach and normal lanes as modeled in the network.

flow

Data type: Double.

Required: NO (optional).

Average traffic flow (vehicles/h).

sped

Data type: Double.

Required: NO (optional).

Average traffic speed(km/h).

accu

Data type: orca2:Reliability

Required: YES.

Accuracy of the measurement/estimation. It can be used by the Harmonizer to discard unreliable data from the simulation.

fprog

Data type: Float.

Required: YES.

Predefined location, from progressive.

fprog is a number in the range [0,1] that defines the start point of the segment as a proportion of the entire street length.

tprog

Data type: Float.

Required: YES.

Predefined location, to progressive.

tprog is a number in the range [0,1] that defines the end point of the segment as a proportion of the entire street length.

startTime

Data type: dateTime (string formatted as ISO 8601, with or without timezone).

Required: NO (optional).

Starting instant when a traffic element starts to be valid.

endTime

 

Data type: dateTime (string formatted as ISO 8601, with or without timezone).

Required: NO (optional).

Ending instant when a traffic element stops being valid.

tsys

 

In an Optima model, the transport systems (tsys) are all the available ways to transport persons and goods.

Every model can have its different list of transportation systems: car, bus, train, etc.

Required: NO (optional)

Example: tsys="CAR"

Response status

HTTP status Description

202 Accepted

The processing request has been accepted, and all data matching the model has been saved.

All data that did not match the model (for example, referring to a non-existing controller) is discarded.

400 Bad request

Several conditions can be classified under this code.

Generally, when the API has been called with wrong arguments.

For example, some element of the request is missing.

401 Unauthorized

Before using any Optima endpoint you have to authenticate yourself (see → Authentication). Otherwise, this code is returned.

500 Internal server error

Several conditions can be classified under this code.

For example, if DB is not reachable or the endpoint instance is not found.

Response content-type

application/xml

Response output

An XML message describing a forecast result as defined in orca2.xsd.

Important:  The publicationTime timestamp is the time of the overall XML payload publication.

In the measuredData tag used in the request, ALL THE REQUIRED attributes must be present for any type of trafficElement.

If one of these elements is incoherent with the model:

  • It is discarded.

  • The response can change depending on how many elements are discarded.

An element is incoherent with the model if, for example, you provide:

  • a strt attribute in a traffic element of type StreetTraffic that is not part of the traffic model.

  • a code attribute (for a traffic element OpenLRTraffic or DetectorTraffic) specified within a wrong traffic element.

The response is:

  • ALL the elements in the tag are discarded: 400 Bad request.

  • Otherwise: 202 Accepted.

In the payload shown in this example, you can find the lane information that makes sense only for strt location.

Specifying a value for lane is optional. Please refer to → lane for lane numbering acceptance rules.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate

Request input

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>fcd</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2015-12-07T16:46:44.733">
    <MetaInfo>
        <LocationUsed xsi:type="LocationUsedTDE" type="Street"/>
    </MetaInfo>
    <measuredData creationTime="2015-12-07T16:46:44.733">
        <trafficElement xsi:type="StreetTraffic" strt="1230194803510957" fsnd="102931237978" lane="1" sped="31.389913999999997" accu="80" startTime="2015-12-07T16:41:44.733" endTime="2015-12-07T16:46:44.733"/>
        <trafficElement xsi:type="StreetTraffic" strt="724063784" fsnd="683804260" lane="1" sped="52.849957" accu="60"/>
        <trafficElement xsi:type="StreetTraffic" strt="709661539" fsnd="620301828" lane="1" sped="98.279655" accu="80"/>
        <trafficElement xsi:type="StreetTraffic" strt="557330528" fsnd="620259228" lane="1" sped="64.94727" accu="20"/>
        <trafficElement xsi:type="StreetTraffic" strt="766619638" fsnd="840300415" lane="1" sped="57.029907" accu="40"/>
        <trafficElement xsi:type="StreetTraffic" strt="558172188" fsnd="621306797" lane="1" sped="56.949932000000004" accu="40"/>
        <trafficElement xsi:type="StreetTraffic" strt="584400276" fsnd="718944269" lane="1" sped="45.999924" accu="20"/>
        <trafficElement xsi:type="StreetTraffic" strt="59626647" fsnd="65154156" lane="1" sped="38.521236" accu="40"/>
        <trafficElement xsi:type="StreetTraffic" strt="764449651" fsnd="628489003" lane="1" sped="44.429848" accu="80"/>
        <trafficElement xsi:type="StreetTraffic" strt="757371875" fsnd="633534902" lane="1" sped="46.979958" accu="40"/>
        <trafficElement xsi:type="StreetTraffic" strt="761658626" fsnd="836911098" lane="1" sped="70.95992" accu="20"/>
        <trafficElement xsi:type="StreetTraffic" strt="578576822" fsnd="683817017" lane="1" sped="87.73963" accu="40"/>
        <trafficElement xsi:type="StreetTraffic" strt="572734913" fsnd="600309189" lane="1" sped="113.62979" accu="80"/>
        <trafficElement xsi:type="StreetTraffic" strt="766666734" fsnd="840329255" lane="1" sped="46.499916" accu="40"/>
        <trafficElement xsi:type="StreetTraffic" strt="832762252" fsnd="886179303" lane="1" sped="73.729706" accu="20"/>
        <trafficElement xsi:type="StreetTraffic" strt="55389109" fsnd="65224235" lane="1" sped="66.519936" accu="20"/>
    </measuredData>
    </payloadPublication>
</Orca2Model>

Response status

HTTP status Description

202 Accepted

The processing request has been accepted.

Data are stored in the DB.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate

Request input

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>pasta</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2015-12-07T16:46:44.100">
    <MetaInfo>
        <LocationUsed xsi:type="LocationUsedOpenLR"/>
    </MetaInfo>
    <measuredData >
        <trafficElement xsi:type="OpenLRTraffic" code="CwV7RCAU5hJSAv+z/4gSQoA=" flow="828.0" startTime="2015-12-07T16:41:44.100" endTime="2015-12-07T16:46:44.100" accu="95"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwV2zCALGhtqAQBt/9kbOoI=" flow="438" startTime="2015-12-07T16:41:44.100" endTime="2015-12-07T16:46:44.100" accu="100"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwVqLiAF6RtqAQBS/+UbGg==" flow="408" accu="100"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwV2OiASLiuwAf/u/5srAA==" flow="354" accu="100"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwVt9CAKhxtpAgCo/9obGQ==" flow="66" accu="100"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwV0qSARkSOMAgBv/6EjHA==" flow="516" accu="100"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwV0aiAKJSOMAQBM/8cjO3I=" flow="330" accu="100"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwV3CCAPBiurAgCg/5krO1Q=" flow="468" accu="100"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwV0DSADIxJCBABYAOoSUaM=" flow="2532" accu="95"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwVpiSANhBtnAgClAAYbFw==" flow="840" accu="95"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwV2OyAPiRtiAQApADgbEg==" flow="594" accu="100"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwVzzCAMhiOSAv+d/3cjIoA=" flow="342" accu="100"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwV2FiAIzRtiAQAxAEMbEg==" flow="1296" accu="100"/>
        <trafficElement xsi:type="OpenLRTraffic" code="CwVxviALWCOfAv/fAIEjDw==" flow="780" accu="100"/>
    </measuredData>
    </payloadPublication>
</Orca2Model>

Response status

HTTP status Description

202 OK

The processing request has been accepted.

Data are stored in the DB.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate

Request input

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>utc</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2015-12-18T10:25:44.000">
    <MetaInfo>
        <LocationUsed xsi:type="LocationUsedPredefined" type="TMC"/>
    </MetaInfo>
    <measuredData creationTime="2015-12-18T10:25:44.000">
        <trafficElement xsi:type="PLOCTraffic" pril="2108" secl="2107" flow="828.0" accu="95" startTime="2015-12-18T10:20:44.000" endTime="2015-12-18T10:25:44.000"/>
        <trafficElement xsi:type="PLOCTraffic" pril="2110" secl="2109" flow="828.0" sped="98" startTime="2015-12-18T10:20:44.000" endTime="2015-12-18T10:25:44.000" accu="95"/>
        <trafficElement xsi:type="PLOCTraffic" pril="2109" secl="2110" sped="77.2" accu="95"/>
    </measuredData>
    </payloadPublication>
</Orca2Model>

Response status

HTTP status Description

202 OK

The processing request has been accepted.

Data are stored in the DB.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate

Request input

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>pasta</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication">
    <MetaInfo>
        <LocationUsed xsi:type="LocationUsedTDE" type="CountLocation"/>
    </MetaInfo>
    <measuredData creationTime="2015-12-07T14:40:00.000">
        <trafficElement xsi:type="ClocTraffic" cloc="5"  flow="828.0" accu="95" startTime="2015-12-07T14:35:00.000" endTime="2015-12-07T14:40:00.000"/>
        <trafficElement xsi:type="ClocTraffic" cloc="159"  flow="438" accu="100"/>
        <trafficElement xsi:type="ClocTraffic" cloc="7"  flow="408" accu="100"/>
        <trafficElement xsi:type="ClocTraffic" cloc="11"  flow="354" accu="100"/>
        <trafficElement xsi:type="ClocTraffic" cloc="9090909090"  flow="354" accu="87"/>
    </measuredData>
    </payloadPublication>
</Orca2Model>

Response status

HTTP status Description

202 OK

The processing request has been accepted.

Data are stored in the DB.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate

Request input

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>posttest</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2015-12-18T10:25:44.000">
    <MetaInfo>
        <LocationUsed xsi:type="LocationUsedTDE" type="Detector"/>
    </MetaInfo>
    <measuredData creationTime="2015-12-18T10:25:44.000">
        <trafficElement xsi:type="DetectorTraffic" code="dd_mec" status="0" flow="828.0" accu="95" startTime="2015-12-18T10:20:44.000" endTime="2015-12-18T10:25:44.000"/>
        <trafficElement xsi:type="DetectorTraffic" code="dd_st" status="0" flow="828.0" sped="98" startTime="2015-12-18T10:20:44.000" endTime="2015-12-18T10:25:44.000" accu="95"/>
        <trafficElement xsi:type="DetectorTraffic" code="dd_st" status="0" flow="828.0" sped="77" accu="53"/>
	<trafficElement xsi:type="DetectorTraffic" code="LZA-15-22-MBLV1a" flow="828.0" sped="98" startTime="2015-12-18T10:20:44.000" endTime="2015-12-18T10:25:44.000" accu="95"/>
	<trafficElement xsi:type="DetectorTraffic" code="LZA-15-19-MCGH1a" status="2" flow="828.0" sped="77" accu="53"/>
    </measuredData>
    </payloadPublication>
</Orca2Model>

Response status

HTTP status Description

202 OK

The processing request has been accepted.

Data are stored in the DB.

Additional Notes

In the example:

  • The fourth <trafficElement.../> is not associated to the status attribute, therefore trafficstate.status=null.
  • The fifth <trafficElement.../> is associated to the status=2 attribute, therefore TRAFFICSTATE.STATUS=2 (see → Values for status:).

In all cases, the provided code is looked up in the detector table and all the information related to the detector is transferred to the associated traffic state structure.

For example, the code LZA-15-19-MCGH1a must match the value of the detector code stored in the detector table.

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate

Request input

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>tacme</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2021-08-10T10:25:44">
    <MetaInfo>
        <LocationUsed xsi:type="LocationUsedTDE" type="Detector"/>
    </MetaInfo>
    <measuredData>
        <trafficElement xsi:type="DetectorTraffic" code="22032131" status="0" flow="1000.0" tsys="HGV" accu="95"/>
        <trafficElement xsi:type="DetectorTraffic" code="22032131" status="0" flow="1200.0" tsys="LGV" accu="95"/>
        <trafficElement xsi:type="DetectorTraffic" code="22032232" status="0" flow="2300.0" tsys="CAR" accu="95"/>
    </measuredData>
    </payloadPublication>
</Orca2Model>

Response status

HTTP status Description

202 OK

The processing request has been accepted.

Data are stored in the DB.

In some of the previous examples, you can find payloads with a set time zone.

It is not generally required, as illustrated in → ORCAv2 timestamp format.