Location Referencing API
The Location Referencing API:
- Publishes the spatial centreline of the StateHighway in vector form, using industry standard KML format
- Provides querying and validation against the logical structure of the State Highway network, supporting user interfaces with constrained choices of State Highway, Reference Station, Road Section, and Direction
- Provides conversion methods for accurately translating between linear route positions and spatial representations of both point and polyline objects, down to sub-metre accuracy
- The API provides fuzzy searches for route positions across increasing, decreasing, and dual carriageway road sections
For more information about the NZ Transport Agency's (NZTA) Location Referencing model, see http://www.nzta.govt.nz/resources/location-ref-management-sys-manual/lrms.html
Getting Started: What is the Location Referencing API?
The Location Referencing API provides access to authoritative data representing locations along the State Highway network. The API appears as a collection of WS-I standards compliant SOAP services which have been validated against multiple web services clients including PHP, Adobe FLEX, Java, and .Net.
The Location Referencing API includes:
- Logical network structure: Querying and validation against the logical structure of the road network, utilizing both hierarchical and connectivity models. Exposing the logical structure of the network allows user interfaces to be built which include drop lists with valid choices of State Highway, Reference Station, Road Section, Direction, which can be linked in a parent-child manner.
- Spatial Centerline: The authoritative spatial centreline of the State Highway Network is provided in vector form, using industry standard KML format. The State Highway centreline can be overlaid by developers into their own map content to graphically render the State Highway centreline along with other content relevant to road users.
- Linear/Spatial Translation: Conversion methods are provided for accurately translating between linear route positions and spatial representations of both point and polyline objects. Linear to spatial conversions (and spatial to linear conversions) are calculated using the measured distance between vertices, resulting in completely faithful conversions down to sub-metre accuracy.
- Directionally tolerant location search: The API also provides fuzzy searches for route positions across increasing, decreasing, and dual carriageway road sections. The directional tolerance feature contributed to increasing the success rate of linear/spatial conversion for these datasets from 20%-25% to 80%-95%. When integrating and combining third party data with the NZTA's other InfoConnect data sources, this feature increases the ability to use spatial and linear location to correlate data by a factor of 4-5 times.
The documentation and code samples provided demonstrate how to convert data from the existing (linear location only) TREIS event feed, showing how to translate those linear event locations into spatial locations for use on a map. This use case was chosen as it allows registered InfoConnect users to use the documentation to easily integrate the code samples provided into their applications, and starting representing and using TREIS event data spatially - without any change required to the existing TREIS data feeds.
Quick Start Guide
The Location Referencing API is accessible as a SOAP endpoint, and the WSDL can be viewed directly from your web browser as an XML document. The URL for the service is:
http://lrms.highwayinfo.govt.nz/lrms/service/v4/LrmsService?wsdl
The meaning of the operations and data types is best understood in terms of the NZTA's Location Referencing Management System (LRMS), which is documented here:
http://www.nzta.govt.nz/resources/location-ref-management-sys-manual/lrms.html
Usage Policy
There are no specific guidelines on what you can do with the Location Referencing API, however, the NZTA anticipates that the services and data provided will be most useful when combined with other sources of information. It is a key concern that information provided to road users is kept up to date, as one of the key objectives of InfoConnect is to inform road users with useful information. If a partner is displaying out of date, and hence inaccurate information, this would not be acceptable.
