Routed Services Input Data format (XML)

In this section of the manual we discuss the routed services XML input format used by PLANit. Routed services require a Service Network to be defined on.

• If you are only interested to see an example file, jump to the Expanded Example.
• XML Schema of routed services https://www.goplanit.orgplanitmanual.github.io/version//xsd/routedservicesinput.xsd

<routedservices>

routed services can be described in a stand alone XML file - only describing the routed service characteristics - or as part of a PLANit XML file describing all input components. Either way, all routed services that exist on a given parent service network while its contents are defined within its XML root element <routedservices>. When part of a larger (single) PLANit input file, the structure should resemble something like the following:

<PLANit	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xmlns:gml="http://www.opengis.net/gml"											
		xsi:noNamespaceSchemaLocation="https://planitmanual.github.io/version/<version>/xsd/routedservicesinput.xsd">
	<routedservices>
		...
	</routedservices>
	...
</PLANit>

Whereas if, it is a stand-alone file, it should look something like

<routedservices
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	 xmlns:gml="http://www.opengis.net/gml"
	 xsi:noNamespaceSchemaLocation="https://planitmanual.github.io/version/<version>/xsd/routedservicesinput.xsd">
...	
</routedservices>

This root element has an id as well as a service layers container element which references the related service network these routed services are defined upon:

The service layers element contains the actual definitions of the routed services for each service network layer that is referenced.

In the remainder of this page, we discuss each of the routed services XML elements in order of expected appearance. We explore their attributes, sub-elements, or simple elements (elements without sub-elements). At the bottom of the page an expanded example is provided highlighting all the available options explicitly.

XML Elements

This section discusses the (complex) XML elements under the <routedservices> root element in expected order of appearance.

<servicelayers>

This container element defines all the service layers that have routed services defined on them. the container is uniquely associated with a single service network, meaning that all its elements must reference a layer within that aprticualr service network.

This element has a single attribute:

The container element itself has one or more service layer elements for which routed services are defined:

<> <servicelayer>

A service layer references a service layer in the parent service network while defining routed service on this referenced service layer.

All routed services that are defined supporting certain modes, must ensure that the supported modes are available on the reference service layer - which in turn rely on the physical layer it is based on - .

This element has the following attributes:

Each service layer element has the following sub-element:

<><> <services>

The actual routed services for a particular mode are defined within this container element.

The referenced mode must be available on the service layer.

This element has a single attribute:

Each Services element has one or more of the following sub-element:

<><><> <service>

A routed service definition is defined in this element. A routed service can either be frequency or schedule based.

This element has the following attributes:

Each routed service has one or more of the following simple elements:

Each Routed Service has trips defined through its sub-element:

<><><><> <trips>

The trips container element of a routed service instance.

This element has one of more of the following sub-elements:

<><><><><> <trip>

A trips defines either a scheduled or frequency based definition of a routed service trip. Note that this does not need to represent a single execution of the trip, a trip can define multiple executed trips through a schedule with multiple departures for this trip or via its frequency.

This element has the following attributes:

Each trip definition has one of the two options below as sub-element:

<><><><><><> <schedule>

The schedule element describes a schedule for a routed service (trip). While possible to define a unique schedule for each trip with a single departure time and stop times, the schedule is deifned such that is allows to define multiple trips by defining multiple departure times and relative timings between stops via the reltimings element. As such a schedule has the following two sub-elements:

<><><><><><><> <departures>

The departures container element of scheduled routed service trip(s).

This element has one of more of the following sub-element:

<><><><><><><><> <departure>

A specific departure time for a scheduled routed service trip. Each departure supports the following attributes:

<><><><><><><> <reltimings>

The relative timings for each leg of each trip after it has departed by means of one of the specified departure times. Since these timings are applied to all defined departure times, they are in relative timing rather than absolute timing, hence the naming ‘reltimings’.

A default dwell time may be specified as an attribute. This is to be applied to all legs when no dwell time is available.

This element has one of more of the following sub-element:

<><><><><><><><> <leg>

A leg of the scheduled routed trip, relative to the preceding leg (or departure time). Each leg has a duration and optional dwell time (at the end of the leg) to define its duration, as well as a references to the service network leg it is routed on.

A leg has the following attributes:

<><><><><><> <frequency>

A routed service can be defined based on frequency, in which case no individual scheduled services are defined by the average frequency (per hour) the routed service is being offered. This can be defined via this element

A frequency based routed service (trip) element defines a frequency as its value (floating point number) and has the following additional attributes:

An example of this element could look something like this:

<frequency lsrefs="34,21,44,2,8" unit="h">3.5</frequency>

Expanded Example

Below you will find an expanded example where all elements and attributes are explicitly set, to give you an idea of the overall structure of the routed services XML. This example does not make sense as an actual input file, it is purely meant to show off all aspects of the file, rather than be used as a practically feasible input file.

<routedservices
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:gml="http://www.opengis.net/gml"
   xsi:noNamespaceSchemaLocation="https://planitmanual.github.io/version/<version>/xsd/routedservicesinput.xsd">
    <id>routed_services_id</id>
    <servicelayers servicenetworkref="service_network">
      <servicelayer id="routed_service_layer" servicelayerref="service_layer">
        <services moderef="bus">
          <service id="line_4">
            <name>4</name>
            <namedescription>city to beach</namedescription>
            <servicedescription>bus line running from the city to the beach directly</servicedescription>
            <trips>
              <!-- in this example we have both frequency based trips and some additional explicitly scheduled trips -->
              <trip id="scheduled_trips_line4" externalid="some_external_ref">
                <schedule>
                  <departures>
                    <departure id="dep1" time="07:00:00" />
                    <departure id="dep2" time="09:50:00" />
                  </departures>
                  <reltimings dwelltime="00:30:00">
                    <leg lsref="ls1" duration="00:03:00" dwelltime="00:01:00" />
                  </reltimings>
                </schedule>
              </trip>
              <trip id="frequency_based_trips_line_4" externalid="some_external_ref">
                <frequency lsrefs="ls1" unit="h">3</frequency>
              </trip>
            </trips>
          </service>
          <!-- and another service in the opposite direction -->
          <service id="line_4_opp">
            <name>4</name>
            <namedescription>beach to city</namedescription>
            <servicedescription>bus line running from the beach to the city
              directly</servicedescription>
            <trips>
              <!-- in this example we have only explicitly scheduled trips -->
              <trip id="scheduled_trips_line4_opp" externalid="some_external_ref_opp">
                <schedule>
                  <departures>
                    <departure id="1" time="08:00:00" />
                    <departure id="2" time="08:50:00" />
                    <departure id="3" time="09:30:00" />
                  </departures>
                  <reltimings>
                    <leg lsref="ls2" duration="00:03:00" dwelltime="00:02:00" />
                  </reltimings>
                </schedule>
              </trip>
            </trips>
          </service>
        </services>
      </servicelayer>
    </servicelayers>
  </routedservices>