Highway Information API

Version 2.0.1
October 2013

Introduction

The Traffic Road Event Information System (TREIS) API lets you access real time data on events/incidents that affect traffic conditions across the network of national highways in New Zealand. An example of an event/incident could include road works, an accident, or weather related problems such as ice or snow. Note that this information is ONLY for notable events/incidents that may cause delays to road users or require caution, and only where the details have been verified by the Transport Agency or another official source.

The TREIS API makes available three sets of data:

1. Events/Incidents
   This is a detailed list of confirmed events/incidents on the state highway with a specified location. For example, caution advised due to a land slip blocking one lane of traffic.
2. General Warnings – North Island
   These are the general warning messages that apply to a wider geographic area within the North Island. For example, widespread flooding and slips in the Hawke’s Bay area.
3. General Warnings – South Island
   The same as 2, but only for the South Island. For example, Otago And Southland Winter Conditions Exist And Motorists Are Advised To Watch For Ice And Grit In Shaded Areas And On Bridge Decks And To Carry Chains Especially When Travelling The Alpine Passes

Additional details

More detail is available in the TREIS Webservices Documentation [PDF, 198 KB] which covers:

• specification of the TREIS web services API; and
• Information on how to connect to the TREIS web services API.

This document is intended for data architects and developers that must integrate their applications with the TREIS web services API.

Linear referencing (RS/RP) & geospatial coordinates

Overview

The TREIS webservice feed contains location data expressed in NZ Map Grid (NZMG) coordinates.

Linear referencing (RS/RP) & geospatial coordinates for TREIS Web services

The TREIS webservice returns highway event locations in 2 forms: linear referenced (“RS/RP”), and geospatial (currently NZMG coordinates).

Linear referencing is the default positioning system used in the NZTA LRMS and RAMM systems, and measures a linear distance offset along a road centreline from a known marker position (reference station or RS). The TREIS webservice returns either a single RS/RP (for a point event) or 2 values (bounding a linear stretch of road).

Geospatial coordinates provide a (x,y) position for points along a road centreline in a known coordinate system. A road event covering a stretch of road will be defined by an array of (x,y) points along the centreline.

The Spatial LRMS data extract embedded in the TREIS database allows RS/RP & geospatial coordinates to be reconciled for any stretch of State Highway.

Coordinate systems

Users of the TREIS webservice feed may wish to consume geospatial coordinates in other coordinate systems, commonly WGS84 which may be used in the Google Maps API. In this case, it is recommended that users reproject data in their web client application. A suggested mechanism is to use a JavaScript version of the Proj.4 library to reproject coordinates. Proj.4 is described generally here: http://trac.osgeo.org/proj/ and the Javascript implementation here: http://trac.osgeo.org/proj4js/

Relevant parameters for coordinate conversion are the “srid” (equivalent to “EPSG code”) values for each coordinate systems, as follows:

WGS84 & NZTM should cover the vast majority of common use for NZ web mapping.

Note also that the transformGeom method of the NZTA Location Referencing API can reproject  data between coordinate systems.

Future use of NZMG at NZTA

NZMG is no longer a NZ national standard, having been replaced by the projected coordinate system "NZ Transverse Mercator" (NZTM) some time ago. Currently, most NZTA geospatial data is  still held in NZMG; this is planned to be replaced by NZTM with the next 2 years or so. The TREIS webservice feed will be upgraded to provide updated coordinate systems support in the future.

Event Regions Map

TREIS API added element eventRegions to the roadEvent complexType. It is an optional element as indicated by the minOccurs=’0’ attribute.

<xs:element name="roadEvent">
        <xs:complexType>
                <xs:sequence>
                                <xs:element ref="tns:alternativeRoute"/>
                                 .....
                                <xs:element minOccurs="0" ref="tns:eventRegions"/>
                </xs:sequence>
     </xs:complexType>
</xs:element>

eventRegions complexType definition:

<xs:element name="eventRegions"> 
<xs:complexType> 
<xs:sequence> 
<xs:element maxOccurs="unbounded" ref="tns:eventRegion" /> 
</xs:sequence> 
</xs:complexType> 
</xs:element> 
<xs:element name="eventRegion" type="xs:string" /> 

An example of TREIS SOAP Web service response is given below:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <tns:GetTreisInfoResponse xmlns:tns="https://infoconnect.highwayinfo.govt.nz/schemas/treis">
         <tns:roadEvent>  <tns:alternativeRoute>Tiakitahuna Rd, No 1 Line And Karere Rd</tns:alternativeRoute>
            <tns:directLineDistance1>0.22 km northwest of Tiakitahuna</tns:directLineDistance1>
            <tns:directLineDistance2>1.90 km southwest of Karere</tns:directLineDistance2>
            <tns:directLineDistance3>3.75 km southwest of Longburn</tns:directLineDistance3>
            <tns:eventComments>Serious Collision - Northbound Traffic Has Been Diverted.</tns:eventComments>
            <tns:eventDescription>Crash</tns:eventDescription>
            <tns:eventId>68523</tns:eventId>
            <tns:eventIsland>North Island</tns:eventIsland>
            <tns:eventType>Road Hazard</tns:eventType>
            <tns:expectedResolution>Until further notice</tns:expectedResolution>
            <tns:impact>Delays</tns:impact>
            <tns:locationArea>SH 56 Tiakitahuna Road, Tiakitahuna, South Of Palmerston North</tns:locationArea>
            <tns:locations>
               <tns:location>056-0011/04.94   Tiakitahuna</tns:location>
            </tns:locations>
            <tns:planned>false</tns:planned>
            <tns:restrictions/>
            <tns:startDate>2012-11-16T12:52:00.000+13:00</tns:startDate>
            <tns:status>Active</tns:status>
            <tns:wktGeometry>SRID=27200;POINT (2722186.572841235 6086239.972712915)</tns:wktGeometry>
            <tns:eventCreated>2012-11-16T12:56:23.267+13:00</tns:eventCreated>
            <tns:eventModified>2012-11-16T13:13:45.420+13:00</tns:eventModified>
            <tns:informationSource>Police</tns:informationSource>
            <tns:supplier>Official</tns:supplier>
            <tns:eventRegions>             <tns:eventRegion>Taranaki, Manawatu-Wanganui, Hawke's Bay & Gisborne Region</tns:eventRegion>             </tns:eventRegions>
         </tns:roadEvent>
      </tns:GetTreisInfoResponse>
   </soapenv:Body>
</soapenv:Envelope>

For access to this API and any additional documentation available, please  request access by completing our InfoConnect access registration form.