Samtrafiken NeTEx import

This page contains documentation with clarifications of how Netex (the Nordic Profile) data is imported by Samtrafiken.

The data is delivered in a zip file that consists of the following required files:

  • _shared_data.xml - A prefix is allowed in the file name as long as it matches “.*_shared _data.xml”.

  • _stops.xml - A prefix is allowed in the file name as long as it matches “.*_stops.xml”.

  • line_{Line.Number}_{Line.Id}.xml - One file per line. Files must contain “line” (case-insensitive) and end with “.xml”, but otherwise they may be named anything.

The files are described below.

Changelog of this documentation

2024-02-12 - Added the two fields JourneyPart.StartTimeDayOffset and JourneyPart.EndTimeDayOffset with explanations.

2024-11-08 - Added description of the field ServiceJourney.PrivateCode.

NeTEx version requirements

Samtrafiken requires submitted NeTEx datasets to comply with the Norwegian NeTEx 1.0.11 standard.

If you are using Java, you can use the netex-java-model package offered by Entur. This package helps validating your NeTEx files against the previously mentioned XSD files, and is the same validation as we use when we receive NeTEx files. https://github.com/entur/netex-java-model/releases/tag/netex-java-model-1.0.11

<dependency> <groupId>org.entur</groupId> <artifactId>netex-java-model</artifactId> <version>1.0.11</version> </dependency>

In order to validate a file, you can take a look at this example code:

NeTExValidator netexValidator = new NeTExValidator(); Schema schema = netexValidator.getSchema(); Validator validator = schema.newValidator(); validator.setProperty(XMLConstants.ACCESS_EXTERNAL_DTD, ""); validator.setProperty(XMLConstants.ACCESS_EXTERNAL_SCHEMA, ""); validator.setErrorHandler(new XmlErrorHandler()); validator.validate(new StreamSource(netexFile));

If you want to validate the files in another way, you can use XSD files directly. These files can be found here: GitHub - NeTEx-CEN/NeTEx: NeTEx is a CEN Technical Standard for exchanging Public Transport schedules and related data.

In case the version requirements would change in a way that your Netex files no longer validate against the new version, Samtrafiken will contact you before the change happens.

Codespace, ids and versioning

  • The id attribute must follow the pattern: [codespace]:[type]:[id] or [countrycode]:[codespace]:[type]:[id] . Examples: 253:Authority:9010005000000000 or SE:253:Authority:9010005000000000.
    Be consistent with your choice throughout all of the files.

  • All ids must be unique across all files in a single NeTEx delivery for a given version.

  • The version must be a positive whole number (integer) or “any”.

  • The version number must be increased in such a way that the latest version of the object always has the highest number.

  • We recommend using the pattern YYYYMMDDHHmmSS as version if your non-netex objects are already version controlled with "exists from"-dates.

  • The Xmlns value of the Codespace-element is provided by Samtrafiken.

Authorities

When delivering one authority, which is the usual case, the following fields are required:

  • CompanyNumber, the company VAT number

  • Name, a public facing name for the authority

  • LegalName, the complete legal name of the authority,

  • OrganisationType, always “authority”

<Authority version="20131206" id="SE:253:Authority:9010005000000000"> <!-- PrivateCode may be present, but will be ignored if only 1 authority is provided --> <CompanyNumber>5560388950</CompanyNumber> <!-- Required --> <Name>Östgötatrafiken</Name> <!-- Required --> <LegalName>Östgötatrafiken</LegalName> <!-- Required --> <OrganisationType>authority</OrganisationType> <!-- Always "authority" --> </Authority>

Delivering multiple Authorities

Only when delivering more than one authority: In case you need to deliver multiple authorities, the PrivateCode field should be present. PrivateCode should be a number ranging 1-999, and be unique for each authority. Samtrafiken assigns a codespace number to every incoming data feed (see Samtrafiken NeTEx import | Codespace, ids and versioning above). This number should be used as PrivateCode on one of your authorities. The authority which bears this number should be the most important of your authorities. For example, if you deliver data for both your own company and another company, it is the authority for your own company which should bear the samtrafiken-assigned codespace number.

ServiceCalendar and DayTypeAssignment

You must use the <Date> or the <OperatingPeriodRef> element in the DayTypeAssignment when specifying operating days.
We do not support the use of the OperatingDayRef element.
Example:

Note: An OperatingPeriod is valid up to the datetime specified in the ToDate, but NOT including that time, see the example below:

JourneyParts and Timingpoints

ServiceFacilities or TrainNumbers can be specified for parts of a journey using JourneyParts, and are defined by two StopPoints and their passing times. See the XML file below for an example.

TimingPoints (where a vehicle does not stop, but is merely passing by at a specified time) are ignored by Samtrafiken. If a JourneyPart begins or ends at a PointInJourneyPattern which is a reference to a TimingPoint, then that JourneyPart will be ignored completely by Samtrafiken.

JourneyParts for TrainNumbers should only be used if the train changes train number during the journey. Otherwise no JourneyPart should be used and the TrainNumber should only be specified on the ServiceJourney.
Keep in mind that JourneyParts with TrainNumbers affects a train’s identifier (or announced journey code) when searched for in (most) journey planners.
For example if you submit a ServiceJourney which changes train numbers during the journey (meaning it contains two JourneyParts with TrainNumberRefs) and it is searched for in Samtrafikens Hafas journey planner, the announced journey code of the search result will vary depending on which stop along the route is used as the departure stop for the search query.
Example: If the train travels from A to E,
and between A and B the train number is 1,
and between C and E the train number is 2,
a search query from A to E will result in the train number being 1,
and a search query from C to E will result in the train number being 2.

ServiceJourney.PublicCode

This element will be used as the announced journey code for the ServiceJourney. This element is optional but if not present there must be either a train number for trains or Line.PublicCode for other public transports available.

Notable requirements on some input values

A few fields have strict requirements on what values that are allowed in them. These requirements are necessary in order for Samtrafiken to be able to use the delivered data.

The most important fields are listed here for clarity. The examples for each file also have comments on fields that have special requirements.

To see requirements for ServiceFacilities, click here.

Required fields with special requirements

Element

Requirement

Used for

Comment

Element

Requirement

Used for

Comment

StopPlace.Name

Required.
Max 50 characters.

Used as StopArea.name/StopPoint.name in Samtrafiken's systems.

 

StopPlace.PrivateCode

Required.
Must be either

  • a, for the dataset unique, number between 1 and 999998

  • a 9-digit rikshållplatsnumber, such as 740000001

Used as StopArea.Number in Samtrafiken's systems.

If PrivateCode is not supplied, then the last part of the StopPlace.id will be tried instead. For example if the StopPlace.PrivateCode is empty and the StopPlace.id is: SE:253:StopPlace:174711, then 174711 will be used as StopArea.Number.

The requirement (between 1-999998) remains the same.

When delivering stops using rikshållplatsnumbers, all numbers should already exist as a rikshållplats.

Line.Name

Required.
Should match the Line.PublicCode unless the line has a specific brand name such as "Nockebybanan". Should never be a description of route, e.g. "Stockholm - Göteborg" is forbidden.

 

 

Line.PrivateCode

Required.
Must be a number between 1 and 9998.

Used as Line.Number in Samtrafiken's systems.

This should be unique in combination with the lines TransportOrganisation in the entire dataset.

ServiceJourney.PrivateCode

Required.

Must be a number between 1 and 99998.

Must be unique within a line for a given operating date.

Used internally in Samtrafiken’s systems as journey number.

Necessary for Samtrafiken to be able to create connections/broken connections between different operators.

The same PrivateCode can be used for different ServiceJourneys in the same Line as long as they do not have the same operating dates.

If you are a train operator and are unable to provide a valid PrivateCode you must contact Samtrafiken and we may configure the field to be optional, and be generated by Samtrafiken instead.

ServiceJourney.trainNumbers

Required if the ServiceJourney.TransportMode is of type rail.

Max 5 characters.

Used as DatedVehicleJourney.AnnouncedTrainNumber in Samtrafiken's systems.

The train number must be specified if the ServiceJourney.TransportMode is of type rail.

 

DestinationDisplay.FrontText

Required.
Max 50 characters.

 

 

Optional fields with special requirements

Element

Requirement

Used for

Comment

Element

Requirement

Used for

Comment

Quay.Name

Optional

Max 50 characters

Used as StopPoint.name in Samtrafikens systems

 

StopPlace.ShortName

Quay.ShortName

Optional

Max 16 characters

Used as StopArea.ShortName/StopPoint.ShortName in Samtrafikens systems

 

StopPlace.AlternativeName.Abbreviation

Optional

Max 8 characters

 

 

Quay.PublicCode

Optional

Max 4 characters

Public facing stop point designation. When not present, the local number (auto-increment per StopPlace) is used instead.

Automatically shortened to 4 characters if too long.

For train operators: If the quay is not known (yet), use * as designation.

DestinationDisplay.PublicCode

Optional

Max 8 characters

 

Usually the same as Line.PublicCode

DestinationDisplay.FrontText

Optional

Max 50 characters

 

 

ServiceJourney.PublicCode

Optional

Max 5 characters

Public facing journey code. When not present, the first announced train number (for trains) or Line.PublicCode is used.

Import will fail if ServiceJourney.PublicCode is present but empty

ServiceJourney.FlexibleServiceProperties.BookingContact.Phone

Optional

Max 20 characters

 

 

ServiceJourney.FlexibleServiceProperties.BookingNote

Optional
Max 255 characters

 

If this value is longer than 255 characters it will be cut off at 252 characters and three dots will be added in the end (for example “blablabl…”).

_shared_data.xml

This is an example of the _shared_data.xml file with instructions on how the different fields and elements are expected to be used.

 

_stops.xml

This is an example of the _stops.xml file with instructions on how the different fields and elements are expected to be used.

 

line_{Line.Number}_{Line.Id}.xml

This is an example of a line file with instructions on how the different fields and elements are expected to be used.