Pushing traffic pollution measurements with ORCAv2

This endpoint enables you to handle information about the types od pollution registered in your traffic network, according to ORCAv2 protocol (see ORCA2.xsd).

For each trafficElementassociated to a specific location, in the payload you can specify a set of attributes related to pollutants and defined through the AirQuality object:

Object Attributes associated

AirQuality

List of attributes:

Attribute Description

PM10

Data type: Double.

Required: NO (optional).

Fine particulates, referred to as PM10, are particulate pollutants in the air with a diameter of 10 micrometers or smaller.

Measured in [µg/m3] .

PM2.5

Data type: Double.

Required: NO (optional).

Fine particulates, referred to as PM 2.5, are particulate pollutants in the air with a diameter of 2.5 micrometers or smaller.

Measured in [µg/m3] .

NO2

Data type: Double.

Required: NO (optional).

Nitrogen dioxide.

Measured in [µg/m3].

O3

Data type: Double.

Required: NO (optional).

Ozone.

Measured in [µg/m3].

CO

Data type: Double.

Required: NO (optional).

Carbon monoxide.

Measured in [µg/m3].

SO2

Data type: Double.

Required: NO (optional).

Sulfur dioxide.

Measured in [µg/m3].

Temp

Data type: Double.

Required: NO (optional).

Environmental temperature.

Measured Celsius degrees [°C].

Press

Data type: Double.

Required: NO (optional).

Environmental pressure.

Measuered in atmosphere [atm]

RelHum

Data type: Double.

Required: NO (optional).

Environmental relative humidity.

Measured in percentage.

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/pollution

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 for each trafficElement in the payload:

Traffic element (complexType) Attributes associated

ClocTraffic

List of attributes:

Attribute Description

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). The correct policy it is to always provide the attribute status.

Status semantic.

Possible values:

  • 0 = OK

  • 1 = PARTLY_OK

  • 2 = DEFECT.

The Count Locations layer displays the status as OK even if Optima receives measurements from the sensor but does not receive explicit availability information from the sensor.

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 Description

code

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

status

Data type: Integer.

Required: NO (optional). The correct policy it is to always provide the attribute status.

Status semantic.

Possible values:

  • 0 = OK

  • 1 = PARTLY_OK

  • 2 = DEFECT.

The Count Locations layer displays the status as OK even if Optima receives measurements from the sensor but does not receive explicit availability information from the sensor.

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 Description

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 Description

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 Description

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.

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-11T17:13:50.524+01:00">
        <MetaInfo>
            <LocationUsed xsi:type="LocationUsedTDE" type="Street"/>
        </MetaInfo>
        <measuredData creationTime="2015-12-11T17:10:00.000+01:00">
            <trafficElement xsi:type="StreetTraffic" startTime="2015-12-11T17:10:00.000+01:00" endTime="2015-12-11T18:10:00.000+01:00" strt="127" fsnd="3151" fprg="0.3" tprg="0.8" PM10="10.2" PM2.5="12" NO2="234" Temp="31.389" RelHum="212"/>
            <trafficElement xsi:type="StreetTraffic" startTime="2015-12-11T17:10:00.000+01:00" endTime="2015-12-11T18:10:00.000+01:00" strt="50" fsnd="4497" fprg="0.1" tprg="0.4" PM10="10.2" PM2.5="12" NO2="234" Temp="31.389" RelHum="212"/>
            <trafficElement xsi:type="StreetTraffic" startTime="2015-12-11T17:10:00.000+01:00" endTime="2015-12-11T18:10:00.000+01:00" strt="50" fsnd="4497" fprg="0.6" tprg="0.9" PM10="10.2" PM2.5="12" NO2="234" Temp="31.389" RelHum="212"/>
        </measuredData>
    </payloadPublication>
</Orca2Model>

Response status

HTTP status Description

202 Accepted

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.