trafikinfo

README

🚦 Trafikinfo 🦺

A Go library for the Trafikinfo API from Trafikverket

This library provides the necessary primitives to interact with the Trafikinfo API. It contains a query builder that can be used to build up a Request object. You can then xml.Marshal it and pass it on to your favourite HTTP client to retrieve it. The response can be decoded using xml.Unmarshal.

The data returned by the Trafikinfo API is licensed under Creative Commons CC0.

Usage

See the example client in examples/client. It includes preparing the query, decoding the response etc.

Multiple queries can be passed by either passing multiple NewQuery() into a single Query() call, or chaining .Query() multiple times on the result of NewRequest().

Calling .Filter() multiple times on a Query will replace the whole filter, as a query can only have one filter block.

Supported object types

This library provides facilities for response decoding for the following object types and versions.

Object	Version(s)
Camera	1
FerryAnnouncement	1.2
FerryRoute	1.2
Icon	1.1
MeasurementData20	1.0
MeasurementData100	1.0
Parking	1.4
PavementData	1
RailCrossing	1.5
ReasonCode	1
RoadCondition	1.2
RoadData	1
RoadGeometry	1
Situation	1.5
TrafficFlow	1.4
TrafficSafetyCamera	1
TrainAnnouncement	1.9
TrainMessage	1.7
TrainPosition	1.1
TrainStation	1.4
TrainStationMessage	1
TravelTimeRoute	1.5
WeatherMeasurepoint	2
WeatherObservation	2

Documentation

Overview

Package trafikinfo provides the necessary primitives to interact with the Trafikinfo API. It contains a query builder that can be used to build up a Request object. You can then encoding/xml.Marshal it yourself or call Request.Build. It should be passed as the body to an HTTP request. You can encoding/xml.Unmarshal the response into a struct.

Each package in trv provides a trv.ObjectType that you can pass to NewQuery to create a Request for that object type. It also provides a Response object that you can use to decode the response, instead of having to specify your own. A package's Response type can only be used if all Query in a Request are for the same trv.ObjectType. For other cases you'll need to craft a response struct yourself.

Requests should be done against the v2 Endpoint. Earlier versions of the API are deprecated by Trafikverket and not supported in this library. All requests must be POST requests, for example using net/http.NewRequestWithContext together with net/http.MethodPost.

A number of endpoints return IconID elements, either at the root of the object, or in one of its embedded objects. Each of these IconID strings can be plugged into a query for the code.dny.dev/trafikinfo/trv/icon/v1dot1.Icon resource. It in turn will give you access to a base64 encoded PNG in the response, as well as a URL at which the icon can be retrieved.

When using certain filters, for example Equal, querying for an attribute with a value that doesn't exist will not result in an error by the API. Instead you'll get an empty response.

When creating a query, a Change ID of 0 is automatically included, unless explicitly set to something else with Query.ChangeID. The query also always requests for a trv.LastModified to be returned in the response.

Package design

Much of the code in this library is automatically generated using the XSD schemas provided by Trafikverket. This results in some pointer-heavy structs in code.dny.dev/trafikinfo/internal/trv as all fields are effectively optional.

In order to make it easier to drill down into nested structs, the public structs in trv expose all fields as methods instead which perform nil-checks themselves when returning nested values. In the case of nested structs, they'll instead return a pointer to an empty struct. This results in a fluent-style API, letting you write something like:

Observation().Aggregated5minutes().Precipitation().TotalWaterEquivalent().Value()

You will get a value back which may be nil, no matter if Observation, Aggregated5minutes, Precipitation and TotalWaterEquivalent elements where present in the response or not.

When a method returns a slice, that slice may be nil or empty. You can always safely iterate over those using a for loop, or check the length of the returned slice. A nil slice always has a length of 0.

XML to Go type mapping

The data types are mapped to their closest representation in Go:

• xs:long and :integer are mapped to int64 (to ensure they still decode correctly on 32-bit systems)
• xs:int to int (as int is always at least 32 bits)
• xs:unsignedByte to uint8
• xs:dateTime to time.Time
• xs:float, :double and :decimal to float64 (for xs:float float32 is in theory enough but this avoids needing to deal with the extra type, whereas xs:decimal could in theory exceed a float64 but this never happens with the API in practice as it's only used for sensor values)

Data License

The data returned by the Trafikinfo API is licensed under Creative Commons CC0:

• https://data.trafikverket.se/documentation/datacache/intro
• https://creativecommons.org/publicdomain/zero/1.0/.

Index

• Constants
• type Evaluation
  • func Eval(alias, function string) Evaluation
  • func (v Evaluation) MarshalXML(e *xml.Encoder, start xml.StartElement) error
• type Filter
  • func And(filters ...Filter) Filter
  • func ElementMatch(filters ...Filter) Filter
  • func Equal(name, value string) Filter
  • func Exists(name string, exists bool) Filter
  • func GreaterThan(name, value string) Filter
  • func GreaterThanOrEqual(name, value string) Filter
  • func In(name, value string) Filter
  • func Intersects(name, value string) Filter
  • func LessThan(name, value string) Filter
  • func LessThanOrEqual(name, value string) Filter
  • func Like(name, value string) Filter
  • func Near(name, value string, minDistance, maxDistance int) Filter
  • func Not(filters ...Filter) Filter
  • func NotEqual(name, value string) Filter
  • func NotIn(name, value string) Filter
  • func NotLike(name, value string) Filter
  • func Or(filters ...Filter) Filter
  • func Within(name, value, shape string, radius float64) Filter
  • func (f Filter) MarshalXML(e *xml.Encoder, start xml.StartElement) error
• type Query
  • func NewQuery(obj trv.ObjectType) Query
  • func (q Query) ChangeID(opt string) Query
  • func (q Query) Distinct(field string) Query
  • func (q Query) Eval(evaluations ...Evaluation) Query
  • func (q Query) Exclude(fields ...string) Query
  • func (q Query) Filter(filters ...Filter) Query
  • func (q Query) ID(opt string) Query
  • func (q Query) Include(fields ...string) Query
  • func (q Query) IncludeDeletedObjects(opt bool) Query
  • func (q Query) Limit(opt int) Query
  • func (q Query) MarshalXML(e *xml.Encoder, start xml.StartElement) error
  • func (q Query) OrderBy(opt string) Query
  • func (q Query) SSEURL(opt bool) Query
  • func (q Query) Skip(opt int) Query
• type Request
  • func NewRequest() *Request
  • func (r *Request) APIKey(key string) *Request
  • func (r *Request) Build() ([]byte, error)
  • func (r *Request) Query(queries ...Query) *Request

Constants

const (
	Endpoint = "https://api.trafikinfo.trafikverket.se/v2/data.xml"
)

Types

type Evaluation

type Evaluation struct {
	// contains filtered or unexported fields
}

func Eval

func Eval(alias, function string) Evaluation

func (Evaluation) MarshalXML

func (v Evaluation) MarshalXML(e *xml.Encoder, start xml.StartElement) error

type Filter

type Filter struct {
	// contains filtered or unexported fields
}

Filter represents a filter element in the query.

func And

func And(filters ...Filter) Filter

And builds an AND filter

This filter should be called with at least 2 filters. With only one filter the AND doesn't make much sense and is equivalent to adding the child filter on the Query directly. Despite this, an AND filter with only one child is still considered valid by the API.

func ElementMatch

func ElementMatch(filters ...Filter) Filter

ElementMatch builds an ELEMENTMATCH filter

This filter should be called with at least 2 filters. Using any less than 2 filters will result in the API returning an error.

func Equal

func Equal(name, value string) Filter

Equal filters by if the field provided by name matches the specified value

func Exists

func Exists(name string, exists bool) Filter

Exists filters by whether the field provided by name exists or not

func GreaterThan

func GreaterThan(name, value string) Filter

GreaterThan filters by whether the field specified by name is greater than the specified value

func GreaterThanOrEqual

func GreaterThanOrEqual(name, value string) Filter

GreaterThanOrEqual filters by whether the field specified by name is greater than or equal to the specified value

func In

func In(name, value string) Filter

In filters by if the field specified by name matches any of the provided values

func Intersects

func Intersects(name, value string) Filter

Intersects filters by if te field specified in name intersects with the coordinates provided in value

func LessThan

func LessThan(name, value string) Filter

LessThan filters by whether the field specified by name is less than the specified value

func LessThanOrEqual

func LessThanOrEqual(name, value string) Filter

LessThanOrEqual filters by whether the field specified by name is less than or equal to the specified value

func Like

func Like(name, value string) Filter

Like filters by if the field provided by name matches the regex provided by value

func Near

func Near(name, value string, minDistance, maxDistance int) Filter

Near filters by if the field specified in name is within the specified min/max dinstance from the point coordinates sepcified in value

func Not

func Not(filters ...Filter) Filter

Not builds an NOT filter

This filter should be called with at least 1 filter.

func NotEqual

func NotEqual(name, value string) Filter

NotEqual is the inverse of Equal

func NotIn

func NotIn(name, value string) Filter

NotIn is the inverse of In

func NotLike

func NotLike(name, value string) Filter

NotLIke is the inverse of Like

func Or

func Or(filters ...Filter) Filter

Or builds an OR filter

This filter should be called with at least 2 filters. With only one filter the OR doesn't make much sense and is equivalent to adding the child filter on the Query directly. Despite this, an OR filter with only one child is still considered valid by the API.

func Within

func Within(name, value, shape string, radius float64) Filter

Within filters by if the field specified in name falls within the specified shape, radius and the coordinates in value

func (Filter) MarshalXML

func (f Filter) MarshalXML(e *xml.Encoder, start xml.StartElement) error

type Query

type Query struct {
	// contains filtered or unexported fields
}

Query is used to request information from the Trafikinfo API

func NewQuery

func NewQuery(obj trv.ObjectType) Query

NewQuery returns a query that other methods can be chained on to further customise the request.

func (Query) ChangeID

func (q Query) ChangeID(opt string) Query

ChangeID sets the change ID for the request. This should initially be 0 to request all data, and then be set to the value of the change ID in the response to only get updated/deleted objects since the previous change ID.

func (Query) Distinct

func (q Query) Distinct(field string) Query

Distinct returns an array of unique values of this field

func (Query) Eval

func (q Query) Eval(evaluations ...Evaluation) Query

func (Query) Exclude

func (q Query) Exclude(fields ...string) Query

Exclude ensures element matching the specifields fields are omitted

func (Query) Filter

func (q Query) Filter(filters ...Filter) Query

func (Query) ID

func (q Query) ID(opt string) Query

ID is an arbitrary value which will be echoed in the response. It can be used to associate queries with responses, especially when a request includes multiple queries.

func (Query) Include

func (q Query) Include(fields ...string) Query

Include ensures only elements matching the specified fields are returned

func (Query) IncludeDeletedObjects

func (q Query) IncludeDeletedObjects(opt bool) Query

IncludeDeletedObjects requests that deleted objects also be returned. This defaults to false.

func (Query) Limit

func (q Query) Limit(opt int) Query

Limit sets the limit for the amount of items to be returned. This can be used together with Skip to implement pagination. A Limit of 0 means no limit at all, i.e return everything.

func (Query) MarshalXML

func (q Query) MarshalXML(e *xml.Encoder, start xml.StartElement) error

func (Query) OrderBy

func (q Query) OrderBy(opt string) Query

OrderBy takes a sorting expression the items in the response will be sorted by.

For example:

OrderBy("SomeData.Name desc, SomeData.Description asc")

func (Query) SSEURL

func (q Query) SSEURL(opt bool) Query

func (Query) Skip

func (q Query) Skip(opt int) Query

Skip sets how many items to skip/exclude from the response. This can be used together with Limit to implement pagination.

type Request

type Request struct {
	XMLName string  `xml:"REQUEST"`
	Login   *login  `xml:"LOGIN"`
	Queries []Query `xml:"QUERY"`
}

Request tells the API what we're interested in

It must include the Login information and at least one Query.

func NewRequest

func NewRequest() *Request

NewRequest returns a Request using the specified API authentication key and the data to be retrieved and filtered by the specified queries. At least 1 query needs to be provided.

func (*Request) APIKey

func (r *Request) APIKey(key string) *Request

APIKey sets the API key to use for this request

func (*Request) Build

func (r *Request) Build() ([]byte, error)

Build returns the XML encoded request as an array of bytes. It can be passed as http.NewRequest's body by wrapping it in a call to bytes.NewBuffer().

The Build() method is final when used in a fluent API style, you can't chain additional methods on it that continue to modify the request.

func (*Request) Query

func (r *Request) Query(queries ...Query) *Request

Query adds one or more queries to the request