Getting harmonized traffic states

Multiple incoming data of speed and flow over the same street are fused by the Harmonizer. The endpoint returns the harmonized data.

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

GET 

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

Request resource

Resource Description

{location}

The path parameter supported are:

  • strt
  • openlr
  • ploc

For more details, please see → Basics on locations.

Request parameters

Parameter Required Description

startTime

NO

Initial time for the data to be retrieved.

endTime

NO

End time for the data to be retrieved.

Important:   If both startTime and endTime are not specified, the request returns all data stored within the real time harmonized data DB table.

tsys

NO

Identifiers of one or more specific transport systems. If not specified, the request returns traffic states for the equivalent transport system.

If multiple transport systems are specified, the request returns information for all valid transport systems.

For an invalid transport system, the response is empty.

If you want to specify multiple transport systems, associated (for example) to the location street, the endpoint call is:

 

https://<HOST>:<PORT>/datex-interface/orca2/trafficstate/strt/?tsys=value1, value2,..

Example

https://<HOST>:<PORT>/datex-interface/orca2/trafficstate/strt/?tsys=car,train

type

YES

Required only for the ploc location.

Identifies the extra graph (if any) over which data is available. If the specified type does not exist, the response is empty.

Request content-type

Not applicable.

Request body (payload)

Not applicable.

The response timestamps are compliant with the standard ISO 8601.

If the timestamps do not specify any timezones, the system assumes the same timezone of Optima AS. If the timezones are specified, timestamps are converted to the timezone of the Optima AS.

The Optima AS timezone is included in the header of the response.

Response status

HTTP status Description

200 OK

Result of the processed request.

400 Bad request

Several conditions can be classified under this code.

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

For example, if:

  • startTime and endTime are not specified.
  • startTime is strictly greater than endTime.
  • Some element of the request is missing.

Response content-type

application/xml

Response output

XML message as defined in orca2.xsd. The response returns only fields not NULL.

Request

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

Response status

HTTP status Description

200 OK

Result of the processed request.

Response output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>PTV-OPTIMA</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2016-01-25T11:34:13.313">
        <MetaInfo>
            <LocationUsed xsi:type="LocationUsedTDE" type="Street"/>
            <timezone>Europe/Rome</timezone>
        </MetaInfo>
        <measuredData creationTime="2016-01-25T11:30:00">
            <trafficElement xsi:type="StreetTraffic" strt="759865934" fsnd="729427108" sped="82.05668799999998" accu="20" startTime="2016-01-25T11:25:00" endTime="2016-01-25T11:30:00"/>
            <trafficElement xsi:type="StreetTraffic" strt="763554246" fsnd="838129731" sped="66.50994" accu="20" startTime="2016-01-25T11:25:00" endTime="2016-01-25T11:30:00"/>
            <trafficElement xsi:type="StreetTraffic" strt="565534338" fsnd="633504091" sped="116.184657" accu="60" startTime="2016-01-25T11:25:00" endTime="2016-01-25T11:30:00"/>
        </measuredData>
    </payloadPublication>
</Orca2Model>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate/strt/?street=1226024517&fsnd=2809474

Response status

HTTP status Description

200 OK

Result of the processed request.

Response output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1" xmlns:ns2="http://datex2.eu/schema/2/2_0">
	<exchange>
		<provider>PTV-OPTIMA</provider>
	</exchange>
	<payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2021-04-08T11:13:22.641">
		<MetaInfo>
			<LocationUsed xsi:type="LocationUsedTDE" type="Street"/>
			<timezone>Europe/London</timezone>
		</MetaInfo>
		<measuredData creationTime="2021-04-08T11:10:00">
			<trafficElement xsi:type="StreetTraffic" strt="1226024517" fsnd="2809474" sped="14.428571428571429" accu="100.0" startTime="2021-04-08T11:05:00" endTime="2021-04-08T11:10:00"/>
		</measuredData>
		<measuredData creationTime="2021-04-08T11:15:00">
			<trafficElement xsi:type="StreetTraffic" strt="1226024517" fsnd="2809474" sped="15.857142857142858" accu="100.0" startTime="2021-04-08T11:10:00" endTime="2021-04-08T11:15:00"/>
		</measuredData>
	</payloadPublication>
</Orca2Model>

Request

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

Response status

HTTP status Description

200 OK

Result of the processed request.

Response output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>PTV-OPTIMA</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2016-01-25T11:55:08.716">
        <MetaInfo>
            <LocationUsed xsi:type="LocationUsedOpenLR" version="1.4.2"/>
            <timezone>Europe/Rome</timezone>
        </MetaInfo>
        <measuredData creationTime="2016-01-25T11:50:00">
            <trafficElement xsi:type="OpenLRTraffic" code="CwU6Ox/O7xtlBQGYACMbNoI=" sped="81.26642999999999" accu="20" startTime="2016-01-25T11:45:00" endTime="2016-01-25T11:50:00"/>
            <trafficElement xsi:type="OpenLRTraffic" code="CwVV7R+xfRt1FPpQ/xkbZ74v" sped="87.10984" accu="20" startTime="2016-01-25T11:45:00" endTime="2016-01-25T11:50:00"/>
        </measuredData>
    </payloadPublication>
</Orca2Model>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate/ploc/?type=TMC

Response status

HTTP status Description

200 OK

Result of the processed request.

Response output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>PTV-OPTIMA</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2016-01-25T12:08:55.904">
        <MetaInfo>
            <LocationUsed xsi:type="LocationUsedPredefined" type="TMC"/>
            <timezone>Europe/Rome</timezone>
        </MetaInfo>
        <measuredData creationTime="2016-01-25T12:05:00">
            <trafficElement xsi:type="PLOCTraffic" pril="20994" secl="20993" fprg="3243.4773" tprg="3325.1416" sped="77.90319666666667" accu="30" startTime="2016-01-25T12:00:00" endTime="2016-01-25T12:05:00"/>
            <trafficElement xsi:type="PLOCTraffic" pril="21204" secl="21203" fprg="10.955353" tprg="171.87282" sped="78.81248" accu="20" startTime="2016-01-25T12:00:00" endTime="2016-01-25T12:05:00"/>
        </measuredData>
    </payloadPublication>
</Orca2Model>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate/strt/?tsys=car

Response status

HTTP status Description

200 OK

Result of the processed request.

Response output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>PTV-OPTIMA</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2016-01-25T12:18:00.523">
        <MetaInfo>
            <LocationUsed xsi:type="LocationUsedTDE" type="Street"/>
            <timezone>Europe/Rome</timezone>
        </MetaInfo>
    </payloadPublication>
</Orca2Model>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate/strt/?tsys=submarine

Response status

HTTP status Description

200 OK

Result of the processed request.

Response output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1"/>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate/strt/?startTime=2016-01-25T12:00:00.000+01:00&endTime=2016-01-25T12:10:00.000+01:00

Response status

HTTP status Description

200 OK

Result of the processed request.

Response output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>PTV-OPTIMA</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2016-01-25T15:05:13.455">
        <MetaInfo>
            <LocationUsed xsi:type="LocationUsedTDE" type="Street"/>
            <timezone>Europe/Rome</timezone>
        </MetaInfo>
        <measuredData creationTime="2016-01-25T12:10:00">
            <trafficElement xsi:type="StreetTraffic" strt="760012714" fsnd="835776410" sped="77.23653333333333" accu="30" startTime="2016-01-25T12:05:00" endTime="2016-01-25T12:10:00"/>
            <trafficElement xsi:type="StreetTraffic" strt="565534338" fsnd="633504091" sped="122.034632" accu="60" startTime="2016-01-25T12:05:00" endTime="2016-01-25T12:10:00"/>
        </measuredData>
        <measuredData creationTime="2016-01-25T12:15:00">
        …
        </measuredData>
        <measuredData creationTime="2016-01-25T12:05:00">
        …
        </measuredData>
        <measuredData creationTime="2016-01-25T12:00:00">
        …
        </measuredData>
    </payloadPublication>
</Orca2Model>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate/strt/?startTime=2016-01-25T12:00:00.000+01:00&endTime=2016-01-25T12:00:00.000+01:00

Response status

HTTP status Description

200 OK

Result of the processed request.

Response output

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Orca2Model xmlns="http://sistemaits.com/orca2/1">
    <exchange>
        <provider>PTV-OPTIMA</provider>
    </exchange>
    <payloadPublication xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeasuredPublication" publicationTime="2016-01-25T15:26:36.523">
        <MetaInfo>
            <LocationUsed xsi:type="LocationUsedTDE" type="Street"/>
            <timezone>Europe/Rome</timezone>
        </MetaInfo>
        <measuredData creationTime="2016-01-25T12:05:00">
            <trafficElement xsi:type="StreetTraffic" strt="760012714" fsnd="835776410" sped="77.90319666666667" accu="30" startTime="2016-01-25T12:00:00" endTime="2016-01-25T12:05:00"/>
        </measuredData>
        <measuredData creationTime="2016-01-25T12:00:00">
        ....
        </measuredData>
    </payloadPublication>
</Orca2Model>

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate/strt/?startTime=2016-01-25T12:30:00.000+01:00&endTime=2016-01-25T12:00:00.000+01:00

Response status

HTTP status Description

400 Bad request

Several conditions can be classified under this code.

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

For example, if:

  • startTime and endTime are not specified.
  • startTime is strictly greater than endTime.
  • Some element of the request is missing.

Response output

startTime successive to endTime

Request

https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate/strt/?street=1226024517&fsnd=2809474&startTime=2021-03-15T12:19:00&endTime=2021-03-15T12:39:00

You have to make two different calls:

  1. A call for getting all transport systems traceable into the system:

    https://<OPTIMA_HOST_IP_ADDRESS>:<PORT_NUMBER>/datex-interface/orca2/trafficstate/strt/?tsys=car,train

  2. A call for getting "equivalent" transport systems

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