Using the Movia Web Services

Contents 1 Introduction .............................................................................................................................. 2

1.1 What is a web service? ..................................................................................................... 2 1.2 SOAP and REST Services ................................................................................................ 2

1.2.1 SOAP Services ........................................................................................................ 2 1.2.2 REST Services ......................................................................................................... 2

1.3 Main focus: .NET and Java clients .................................................................................... 3 2 The Movia Web Services ......................................................................................................... 3

2.1 In short .............................................................................................................................. 3 2.2 HTTPS .............................................................................................................................. 3 2.3 Authentication (SOAP Services) ........................................................................................ 3

3 Creating a SOAP web service client ........................................................................................ 4 3.1 The WSDL file ................................................................................................................... 4 3.2 Example: A SOAP web service client in .NET ................................................................... 4

3.2.1 Generating the proxy ................................................................................................ 4 3.2.2 Calling the web service ............................................................................................ 5

3.3 Example: A SOAP web service client in Java .................................................................... 5 3.3.1 Generating the proxy ................................................................................................ 5 3.3.2 Calling the proxy ...................................................................................................... 5

4 API overview ............................................................................................................................ 7 4.1 BusStopService (SOAP).................................................................................................... 7

4.1.1 GetDeparturesAtStop ............................................................................................... 7 4.1.2 GetDeparturesAtAllStops ......................................................................................... 7 4.1.3 GetAllStopPoints ...................................................................................................... 7

4.2 BusLocationService (SOAP) ............................................................................................. 7 4.2.1 GetCurrentBusLocation ............................................................................................ 7

4.3 JourneyProgressService (SOAP) ...................................................................................... 8 4.3.1 GetJourneyProgress ................................................................................................ 8

4.4 WebApi (REST) ................................................................................................................. 9 4.4.1 Search Controller ..................................................................................................... 9 4.4.2 Stops Controller ..................................................................................................... 10 4.4.3 Lines Controller ...................................................................................................... 12 4.4.4 Depatures Controller .............................................................................................. 13 4.4.5 Time Tables Controller ........................................................................................... 14 4.4.6 Deviations Controller .............................................................................................. 15 4.4.7 Integration Controller .............................................................................................. 17

5 Terminology ........................................................................................................................... 19

1 Introduction This document gives an overview of how to use the web services made available by Movia. All terminology used in this document can be found in the section.

1.1 What is a web service?

A web service is a programming interface that is accessed over a network. Web services enforce a client-server architecture, where client and server communicate with each other over a network, mainly using the HTTP protocol.

A web service client can execute operations on a web service as if these operations were available locally. Under the hood, the operation calls are negotiated over the network.

1.2 SOAP and REST Services

Web Services exists in many architectural flavors. Movia exposes services using two of these, namely: SOAP Services and REST (Representational State Transfer) Services. In the following each of these service approaches are described.

1.2.1 SOAP Services

For SOAP Services, all communication between a web service and its clients takes place using XML messages. These XML messages are formatted according the SOAP (Simple Object Access Protocol) standard.

1.2.1.1 WSDL

A WSDL file is a file that contains the complete description of a SOAP web service. WSDL stands for Web Service Definition Language. A WSDL file is an XML document describing what operations a web service exposes, and which parameters and returns values are used.

1.2.1.2 Compatibility and interoperability

To ensure maximum compatibility with other languages and technologies, the Movia SOAP Web Services comply with the so-called WS-I Basic 1.1 Profile. This is a specification, defined by the Web Services Interoperability Organization (WS-I), that provides interoperability guidelines for web services.

1.2.1.3 Client proxy

Before a client can call a SOAP web service, it generally must obtain a reference to a client proxy. A client proxy is a local representation of a SOAP web service. When a client wants to call an operation on web service, it calls that operation on the proxy. The proxy then takes care of forwarding the operation call to the actual web service. Instructions on how to generate a client proxy can be found later on in this document (Section 3).

1.2.2 REST Services

REST Services (sometimes RESTful Services) is a development in web services over the recent years where emphasis has been moving to simpler representational state transfer (REST) based communications. REST APIs do not require XML-based web service protocols (SOAP and WSDL) to support their interfaces, but solely rely on HTTP communication.

1.2.2.1 JSON

JSON (JavaScript Object Notation) is an open standard format that uses human-readable text to transmit data objects consisting of attribute–value pairs. It is used primarily to transmit data between a server and web application, as an alternative to XML. Although originally derived from the JavaScript scripting language, JSON is a language-independent data format, and code for parsing and generating JSON data is readily available in a large variety of programming languages. The JSON format is described in RFC 4627 and ECMA-404.

1.3 Main focus: .NET and Java clients

Clients written in many different programming languages can access a web service. Therefore, it is difficult to use general terminology when talking about creating a web service client. This document uses general terminology where possible, but focuses mainly on web service clients written in .NET and Java.

2 The Movia Web Services Movia exposes several web services that can be used for obtaining information about buses and bus operations.

2.1 In short

Currently, Movia exposes the following SOAP Web Services:

BusStopService Exposes static and real-time information about departures at bus stops WSDL: https://wsilb.moviatrafik.dk/BusStopService/BusStopService.svc?wsdl See section 4.1 for details.

BusLocationService Exposes real-time information about the location of busses. WSDL: https://wsilb.moviatrafik.dk/BusLocationService/BusLocationService.svc?wsdl See section 4.24.4 for details.

JourneyProgressService Exposes real-time information about the stops & duration of a bus journey. WSDL: https://wsilb.moviatrafik.dk/JourneyProgressService/Service.svc?wsdl See section 4.3 for details.

Moreover, the following REST Services are exposed:

WebApi Exposes various methods to support web and app based information channels. See section 4.4 for details.

2.2 HTTPS

All Movia Web Services use SSL over HTTP, also known as HTTPS. This means that all messages flowing between a web service and its client are encrypted. This is also known as Transport Layer Security.

2.3 Authentication (SOAP Services)

The SOAP Web Services are protected with a username and a password, also known as Basic Authentication. A valid username and password are handed out upon web service delivery.

3 Creating a SOAP web service client This section describes how to create a web service client for any of the Movia SOAP Web Services.

3.1 The WSDL file

The WSDL files for the various Movia Web Services can be found online. For example, the WSDL file for the BusStopService is located at: https://wsilb.moviatrafik.dk/BusStopService/BusStopService.svc?wsdl

The WSDL file is the key element in generating a SOAP web service client. How to use the WSDL file to communicate with the web service is very technology-specific. The following sections will explain how to do this using .NET and Java.

3.2 Example: A SOAP web service client in .NET

Writing a web service client in .NET involves 2 steps: generating a proxy from the WSDL file and calling the web service via the proxy.

The example code below is written in C# and assumes the .NET 3.5 framework.

3.2.1 Generating the proxy

3.2.1.1 Using Visual Studio

The easiest way to generate a client proxy in .NET is by using Visual Studio:

1. Create a project that will contain the web service client code.

2. Right click the project’s ‘Service References’, and select ‘Add new Service Reference’.

3. Specify the URL of the WSDL file and press ‘Go’.

4. After the service discovery has completed, enter a name for the service reference and press ‘Ok’.

3.2.1.2 Using svcutil.exe

The client proxy can also be generated without Visual Studio, by using the tool called svcutil.exe. Svcutil.exe is normally located in C:\Program Files\Microsoft SDKs\Windows\v6.0A\bin. It can be executed from the command line, as such:

A complete list of options for svcutil.exe can be found at http://msdn.microsoft.com/en-us/library/aa347733.aspx.

This generates two files:

A file containing the code for the client proxy. This file can be used directly from the client code. It can, of course, also be compiled to a DLL, which can then be used as a project reference.

A configuration file, containing configuration settings for the client proxy (an endpoint and a binding configuration to be precise). The contents of this file should be included in the main config file of the client project.

3.2.1.3 Regarding wsdl.exe

A third way of generating a client proxy is by using a tool called wsdl.exe. Wsdl.exe is mainly meant for generating proxies for ASMX services (old-style .NET web services). Since all Movia Web Services are written using the Windows Communication Foundation (WCF), the use of wsdl.exe is not recommended.

svcutil.exe <URL to WSDL file>

3.2.2 Calling the web service

After the proxy has been generated, the following code can be used to call the web service. This example assumes that a proxy was generated for the BusLocationService web service.

3.3 Example: A SOAP web service client in Java

3.3.1 Generating the proxy

There are several web service frameworks available for Java. The example code below uses JAX-WS.

Writing a web service client in Java involves 2 steps: generating a proxy from the WSDL file and calling the web service via the proxy.

3.3.1.1 Using NetBeans

An easy way to generate a client proxy in Java is by using the NetBeans IDE. The NetBeans IDE wraps the JAX-WS command line utilities in a graphical way:

1. Create a project that will contain the web service client code.

2. Right click on the project, select ‘New’ and click ‘Web Service Client’.

3. Specify the URL of the WSDL file.

4. Set the ‘Client Style’ to JAX-WS and select the ‘Generate dispatch code’ checkbox.

5. Press ‘Ok’.

3.3.1.2 Using wsimport

The client proxy can also be generated without an IDE like NetBeans. JAX-WS contains a utility called wsimport, which can be called from the command line:

This command generates all the class files that make up the proxy. These class files should be added to the classpath of the client application.

A complete list of options for wsimport can be found at https://jax-ws.dev.java.net/jax-ws-ea3/docs/wsimport.html.

3.3.2 Calling the proxy

After the proxy has been generated, the following code can be used to call the web service. This example assumes that a proxy was generated for the BusLocationService web service.

// Import the namespace in which the proxy is located

using schemas.movia.dk._2010._02._25.BusLocationService;

...

// Instantiate the proxy

BusLocationServiceClient client = new BusLocationServiceClient();

// Set username and password

client.ClientCredentials.UserName.UserName = "your username";

client.ClientCredentials.UserName.Password = "your password";

// Make a service call

CurrentBusLocationResult result = client.GetCurrentBusLocation(50);

wsimport <URL to WSDL file>

// Import the packages in which the proxy is located

import dk.movia.schemas._2010._02._25.buslocationservice.*;

import dk.movia.schemas._2010._02._25.buslocationservice.entity.*;

import dk.movia.schemas._2010._02._25.buslocationservice.exception.*;

// Import required Java packages

import java.net.URL;

import javax.xml.namespace.QName;

...

// Instantiate the proxy

URL url = new URL("URL to WSDL file");

QName name = new QName("https://schemas.movia.dk/2010/02/25/BusLocationService",

"BusLocationService");

BusLocationService service = new BusLocationService(url, name);

// Set username and password

IBusLocationService port = service.getBasicHttpBindingIBusLocationService();

BindingProvider bp = (BindingProvider) port;

bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "your username");

bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "your password");

// Make a service call

CurrentBusLocationResult result = port.getCurrentBusLocation(50);

4 API overview This section gives an overview of which methods are located in which web services.

4.1 BusStopService (SOAP)

The following methods are available in the BusStopService web service.

4.1.1 GetDeparturesAtStop

Description Return a list of departures at a certain stop point, within the specified time frame.

Input StopPointId: stop point id.

TimeWindowInMinutes: time window, in minutes, in which to look for departures.

Output List of departures, each departure containing an id, a line name, a destination, a via-destination, a departure time and a real-time flag.

4.1.2 GetDeparturesAtAllStops

Description For all valid stop points, return a list of departures from that stop point, within the specified time frame.

Input TimeWindowInMinutes: time window, in minutes, in which to look for departures.

Output List of stop point ids, each associated with a list of departures for that stop point. A departure contains an id, a line name, a destination, a via-destination, a departure time and a real-time flag.

4.1.3 GetAllStopPoints

Description Return a list of all valid stop point ids and names.

Input N/A

Output A mapping from stop point id to stop point name. The mapping contains all valid stop points in the system.

4.2 BusLocationService (SOAP)

The following methods are available in the BusLocationService web service.

4.2.1 GetCurrentBusLocation

Description Return the current location of a bus.

Input BusNumber: bus number or bus id

Output The current location of the specified bus, consisting of a line number, a destination, the name of the current stop point, the name of the next stop point, the arrival time at the next stop point and a last updated time.

4.3 JourneyProgressService (SOAP)

4.3.1 GetJourneyProgress

Description Return the stops&duration of a journey.

Input BusNumber: bus number or bus id

Output A Journey stops&duration with realtime.

4.4 WebApi (REST)

4.4.1 Search Controller

4.4.1.1 ByText Action (GET)

GET: https://wsilb.moviatrafik.dk/webapi/search/ByText?text=404 Returns an ordered set of lines and stops that are matched by the given search text. Each result indicates its kind (i.e. line or stop), a name for display, and a key that can be used as input for respective actions. For lines furthermore the designation are included, and the type of line. The order of the list indicates the confidence of the result, and thus should the order be preserved when the results are presented to the end user. Parameters:

text : string Search text

Response (example):

[

{

"key": "9014200040410000",

"name": "Ringsted st - Bjergbakken - Tvær Alle - Ringsted st",

"kind": "line",

"type": "ALM",

"designation": "404"

},

{

"key": "624,610",

"name": "DTU, Bygning 404",

"kind": "stop"

}

]

NOTICE: It is only a small fraction of searches that will return both kinds of results, as in the example above. This is simply due the naming conventions that Movia uses, and the internal logic that the search uses. NOTICE: Currently the search algorithm is performed using substring search with simple ranking, and the index is only updated manually. However in the final release, the search will be optimized using tokenization, and selection metrics will be used to rank results.

4.4.2 Stops Controller

4.4.2.1 Nearby Action (GET)

GET: https://wsilb.moviatrafik.dk/webapi/stops/Nearby?eastingCoordinate=722264.09&northingCoordinate=6178575.52&searchDistance=100 Returns a list of stops that are within the search distance of the given coordinates. Parameters:

eastingCoordinate : decimal(15,2) Easting Coordinate (X) in UTM-format, Zone 32

northingCoordinate : decimal(15,2) Northing Coordinate (Y) in UTM-format, Zone 32

searchDistance : int [0; 500] Search distance (dX/dY) in meters.

Response (truncated example):

[

{

"key": "2160,1989,47374,47380",

"name": "Nørrebro st.",

"lines": [

{

"key": "1989;9012200000410000",

"name": "Svanemøllen st. - Lergravsparken st.",

"type": "ABUS",

"designation": "4A",

"hasDeviation": false

},

{

"key": "47380;9012200000400000",

"name": "Lergravsparken st. - Svanemøllen st.",

"type": "ABUS",

"designation": "4A",

"hasDeviation": false

},

{

"key": "2160;9012200000500000",

"name": "Lufthavnen, Udenrigs - Husum Torv",

"type": "ABUS",

"designation": "5A",

"hasDeviation": true

},

...

]

},

...

]

4.4.2.2 FromKey Action (GET)

GET: https://wsilb.moviatrafik.dk/webapi/stops/FromKey?key=1106,1183,1328,7060,10025 Returns information about the stop collection given by the key, including lines that are departing from the stop collection. Parameters:

key : string Movia WebApi Key

Response (truncated example):

[

{

"key": "1106,1183,1328,7060,10025",

"name": "Toftegårds Plads",

"lines": [

{

"key": "1183;9014200000110000",

"name": "Avedøre st. - Klampenborg st.",

"type": "ABUS",

"designation": "1A",

"hasDeviation": true

},

{

"key": "10025;9014200000120000",

"name": "Klampenborg St. - Avedøre st.",

"type": "ABUS",

"designation": "1A",

"hasDeviation": true

},

{

"key": "1183;9014200000410000",

"name": "Svanemøllen st. - Lergravsparken st.",

"type": "ABUS",

"designation": "4A",

"hasDeviation": true

},

{

"key": "10025;9014200000420000",

"name": "Lergravsparken st. - Svanemøllen st.",

"type": "ABUS",

"designation": "4A",

"hasDeviation": true

},

{

"key": "1106;9014200001810000",

"name": "Friheden st. - Nordhavn st.",

"type": "ALM",

"designation": "18",

"hasDeviation": false

},

...

]

},

...

]

4.4.3 Lines Controller

4.4.3.1 FromKey Action (GET)

GET: https://wsilb.moviatrafik.dk/webapi/lines/FromKey?key=9014200000110000 Returns information about the line given by the key, including stops that are on the line. Parameters:

key : string Movia WebApi Key

Response (truncated example):

{

"key": "9014200000110000",

"name": "Avedøre st. - Klampenborg st.",

"type": "ABUS",

"designation": "1A",

"hasDeviation": true,

"mapKey": "9011200000100000",

"stops": [

{

"key": "28399;9014200000110000",

"name": "Avedøre st.",

"road": "Avedøre st."

},

{

"key": "6916;9014200000110000",

"name": "Hvidovre Gymnasium",

"road": "Naverporten"

},

{

"key": "6917;9014200000110000",

"name": "Pottemagerporten",

"road": "Naverporten"

},

{

"key": "6918;9014200000110000",

"name": "Naverporten",

"road": "Rebslagerporten"

},

...

{

"key": "1491;9014200000110000",

"name": "Klampenborg st.",

"road": "Dyrehavevej"

}

]

}

4.4.4 Depatures Controller

4.4.4.1 FromKey Action (GET)

GET: https://wsilb.moviatrafik.dk/webapi/departures/FromKey?key=1152;9014200000610000 Returns a list of stops with lines that are departing from the given stop collection, along with upcoming departure times for each line. The result is constructed from the given key. Parameters:

key : string Movia WebApi Key

Response (example):

[

{

"name": "Hovedbanegården",

"lines": [

{

"designation": "6A",

"type": "ABUS",

"destination": "Emdrup Torv",

"departures": [

{

"departureTime": "2013-10-11T13:07:44",

"timeLeft": 0,

"timeIsReal": 1

},

{

"departureTime": "2013-10-11T13:20:06",

"timeLeft": 13,

"timeIsReal": 1

},

{

"departureTime": "2013-10-11T13:32:00",

"timeLeft": 25,

"timeIsReal": 0

}

]

},

{

"designation": "6A",

"type": "ABUS",

"destination": "Buddinge st.",

"departures": [

{

"departureTime": "2013-10-11T13:19:18",

"timeLeft": 12,

"timeIsReal": 1

},

{

"departureTime": "2013-10-11T13:28:25",

"timeLeft": 21,

"timeIsReal": 1

},

{

"departureTime": "2013-10-11T13:39:00",

"timeLeft": 32,

"timeIsReal": 0

}

]

}

]

}

]

4.4.5 Time Tables Controller

4.4.5.1 FromKey Action (GET)

GET:

https://wsilb.moviatrafik.dk/webapi/timetables/FromKey?key=1183;9012200000410000

Returns links to PDF Time Tables, and Subscription Information for use with Movia Services for

Mobile [CSC.1] for a stop/line, deducted from the given key.

Parameters:

key : string Movia WebApi Key

Response (example):

{

"lineTimeTablePdfUrl": "http://www.moviatrafik.dk/Timetable%20Resources/4a-0004-110813.pdf",

"stopTimeTablePdfUrl": "http://www.moviatrafik.dk/_layouts/movia/createPDF.aspx?url-

ToHtml=http%3a%2f%2fwww.moviatrafik.dk%2fdinrejse%2fkoreplaner%2fBuslinje%2fafgang-

stider%2fPages%2fAfgangsTider.aspx%3fline_direc-

tion_gid%3d9014200000410000%26stop_gid%3d9025200000001183%26printToPdf%3dyes",

"subscriptionKey": {

"lineGid": "9011200000400000",

"directionGid": "9014200000410000",

"stopAreaGid": "9025200000001183"

}

}

4.4.6 Deviations Controller

4.4.6.1 FromKey Action (GET)

GET: https://wsilb.moviatrafik.dk/webapi /deviations/FromKey?key=1183;9014200000110000 Returns deviation information about the line given by the key. Parameters:

key : string Movia WebApi Key

Response (example):

[

{

"header": "Linje 1A kører en anden rute ved Christiansborg",

"text": "Linje 1A kører i begge retninger ad fra Tietgensgade ad H.C. Andersens Boulevard

- Jarmers Plads - Nørre Voldgade - Nørreport St. - Øster Voldgade til Østerport St. i stedet for

den normale rute forbi Christiansborg og Kongens Nytorv. \n\nDet betyder at bussen ikke kører til

stoppestedet Stormbroen, Nationalmuseet, Christiansborg, Holmens Kirke, Kongens Nytorv/Magasin,

Odd Fellow Palæet, Fredericiagade/Bredgade, Esplanaden/Grønningen, Dr.Tværgade/St.Kongensgad, Fre-

dericiag./St.Kongensg. og Esplanaden/St.Kongensgade.\n\nDu kan istedet tage bussen fra stoppeste-

der på den omlagte rute. Der kører i øvrigt pendulbusser mellem Østerport St. og Hovedbanegården

via Kongens Nytorv, Bredgade og Store Kongensgade. \n\nDet gælder fra den 11-10-2013 kl 17:45

til den 12-10-2013 kl 0:30.\n\nDet skyldes Kulturnatten 2013. \n"

}

]

4.4.6.2 GeneralMessages Action (GET)

GET: https://wsilb.moviatrafik.dk/webapi/deviations/GeneralMessages Returns general deviation information. Response (example):

[

{

"header": "Movias busser kører normalt",

"text": "<p>&nbsp;</p>"

}

]

4.4.7 Integration Controller

4.4.7.1 ToKey Action (GET)

GET: https://wsilb.moviatrafik.dk/webapi/integration/ToKey?directionOfLine=9014200000510000&stopArea=9021200000492000 Converts a direction of line and stop area to a key. This is useful when integrating with CSC BusApi. Parameters:

directionOfLine : string Direction of Line Gid.

stopArea : string Stop Area Gid.

Response (example):

{

"key": "2122,2073,1965,25081,2148,2219,27988,258,452,2947,45841;9014200000510000"

}

5 Terminology This section contains an alphabetically ordered list of terms used in this document. Basic authentication: Web-based authentication scheme that works by sending the username and password with each request.

HTTP (Hypertext Transfer Protocol): The standard transmission protocol used on the Internet.

HTTPS (Hypertext Transfer Protocol Secure): Encrypted form of information transfer (HTTP + SSL).

JAX-WS (Java API for XML Web Services): A Java programming language API for creating web services.

SOAP (Simple Object Access Protocol): XML-based protocol to let applications exchange information over HTTP.

SSL (Secure Sockets Layer): Cryptographic protocol which provide secure communications on the Internet.

WSDL (Web Service Definition Language): XML format for describing web services.

WS-I (Web Services Interoperability Organization): Open industry organization chartered to establish Best Practices for Web services interoperability.