rtpi rest web services - specification-2• automated feeds (e.g. twitter / rss) • external api...

RTPI REST Web Services


Specification


Specification


REVISION HISTORY

Version: Author:

1.0 Andrzej Kroczynski








APPROVALS

Version: Approved By

DISTRIBUTION

Name Title

RTPI REST Web Services - Specification

Date: Comments:

2012-01-24

2012-02-02 Added requested changes

2012-07-18 Added due time field to real time information

results

2012-07-19 Added route information to bus stop

information results

2012-07-23 Changed route information

reference to results

2012-08-06 New web service methods to get operators list

and to get last update timestamp for

referenced data

2012-08-22 New web service to get list of routes

2012-10-29 CR1 changes

Date: Comments:

Date: Version

of 14

Added requested changes

Added due time field to real time information

Added route information to bus stop

Changed route information – moved operator

New web service methods to get operators list

and to get last update timestamp for

New web service to get list of routes


1. CONTENTS

1. CONTENTS ................................

2. INTRODUCTION

2.1. Purpose

3. OVERALL DESCRIPTION

3.1. Requirements Summary

3.2. Overview

3.3. Response Error Codes

3.4. Methods

3.4.1. 3.4.2. 3.4.3. 3.4.4. 3.4.5. 3.4.6. 3.4.7.


................................................................................................

................................................................................................

Purpose ................................................................................................

ESCRIPTION ................................................................................................

Requirements Summary ................................................................

Overview ................................................................................................

Response Error Codes ................................................................

Methods ................................................................................................

Retrieve Real Time Bus Information ................................

Retrieve Timetable Bus Information by Date ................................

Retrieve Full Timetable Bus Information ................................

Retrieve Bus Stop Information ................................................................

Retrieve Route Information ................................................................

Retrieve Operator Information ................................

Retrieve Route List Information ................................

of 14

........................................................ 3 .................................................. 4 .................................................... 4

........................................ 5 ........................................................... 5

.................................................. 5 .............................................................. 5

................................................... 6 .......................................................... 6

............................................ 7 ................................................... 8

................................. 10 ..................................... 11

................................................................ 13 ............................................................... 14


2. INTRODUCTION

2.1. Purpose

This document describes RTPI REST Web Services API interface that will be available to retrieve

information, timetables and bus stops.


NTRODUCTION

RTPI REST Web Services API interface that will be available to retrieve


of 14

RTPI REST Web Services API interface that will be available to retrieve real time bus


3. OVERALL DESCRIPTION

3.1. Requirements Summary

System will provide RTPI data to consumers over the internet. Example of services using the system:

• SMS Services

• Smartphone applications

• Web based applications

• Automated Feeds (e.g. twitter / RSS)

• External API

3.2. Overview

RTPI REST Web Services API (RRWS API) provides REST interface to retrieve information on real time bus


Each method available in RRWS API will be invoked using plain HTTP Request

parameters provided, result will be returned either in XML or JSON format

is used by default). Response will contain

error status of the request.

3.3. Response Error Codes

Following error codes are defined in the system:

Error Code Description

0 Success

1 No Results

2 Missing Parameter

3 Invalid Parameter

4 Scheduled Downtime

5 Unexpected System Error

Error code is included in response for each message. For some error codes

free text format (Error Message field)


ESCRIPTION

Requirements Summary


Automated Feeds (e.g. twitter / RSS)

rvices API (RRWS API) provides REST interface to retrieve information on real time bus


Each method available in RRWS API will be invoked using plain HTTP Request (GET method)

will be returned either in XML or JSON format (if format is not provided then JSON

Response will contain requested information (see method specification for details) and

Response Error Codes

error codes are defined in the system:

Missing Parameter

Invalid Parameter

Scheduled Downtime

Unexpected System Error

Error code is included in response for each message. For some error codes additional details will be provided

field).

of 14


rvices API (RRWS API) provides REST interface to retrieve information on real time bus

(GET method). Depending on

(if format is not provided then JSON

requested information (see method specification for details) and

additional details will be provided in


3.4. Methods

3.4.1. Retrieve Real Time Bus Information

Method http://[rtpiserver]/realtimebusinformation

[operator]&format=[format]

Description Method to retrieve real time bus information for given stop number and route

Parameters - stopid - required, existing bus stop id

- routeid – optional, route identifier

- maxresults – optional, maximum number of results, if not provided system will

depending on server configuration

- operator – optional, bus service operator (e.g. DublinBus), if not provided information for all providers is

returned

- format – optional, valid values: xml, json; if not provided JSON format is used by default.

Response List of buses buses arriving at a given bus stop

XML format.

JSON:

{

"errorcode" : "[Error code]

"errormessage" : "numberofresults"

"stopid" : [Stop id],

"timestamp" : "[Date/time information returned] "results" : [{

"arrivaldatetime"

"duetime" :

"departuredatetime" "departureduetime"

"scheduledarrivaldatetime"

"scheduleddeparturedatetime"

"destination" "destinationlocalized"

"origin" : "

"originlocalized"

"direction" "operator" :

"additionalinformation"

"lowfloorstatus "route" : "[Route]

"sourcetimestamp

}, ...

...]

}


Retrieve Real Time Bus Information

realtimebusinformation?stopid=[stopid]&routeid=[routeid]

&format=[format]

to retrieve real time bus information for given stop number and route

required, existing bus stop id

optional, route identifier

optional, maximum number of results, if not provided system will

depending on server configuration

optional, bus service operator (e.g. DublinBus), if not provided information for all providers is

optional, valid values: xml, json; if not provided JSON format is used by default.

buses arriving at a given bus stop (including route number, arrival time and destination) in JSON or

[Error code]",

: "[Additional error details]", "numberofresults" : [Number of results],

: [Stop id],

[Date/time information returned]",

"arrivaldatetime" : "[Arrival time in dd/MM/yyyy HH:mm:ss format]

: "[Arrival Due time in minutes]",

"departuredatetime" : "[Departure time in dd/MM/yyyy HH:mm:ss format]"departureduetime" : "[Departure Due time in minutes]

"scheduledarrivaldatetime" : "[Scheduled arrival time in

dd/MM/yyyy HH:mm:ss format]"scheduleddeparturedatetime" : "[Scheduled departure time in

dd/MM/yyyy HH:mm:ss format]

"destination" : "[Service destination name]", "destinationlocalized" : "[Translated service destination name]

"[Service origin name]",

"originlocalized" : "[Translated service origin name]

: "[Service direction]", : "[Bus service operator name]",

"additionalinformation" : "[Additional information]",

lowfloorstatus" : "[Bus low floor status (yes or no)][Route]",

sourcetimestamp" : "[Timestamp in dd/MM/yyyy HH:mm:ss format]

of 14

?stopid=[stopid]&routeid=[routeid]&maxresults&operator=

to retrieve real time bus information for given stop number and route

optional, maximum number of results, if not provided system will limit number of results

optional, bus service operator (e.g. DublinBus), if not provided information for all providers is


(including route number, arrival time and destination) in JSON or

in dd/MM/yyyy HH:mm:ss format]",

[Departure time in dd/MM/yyyy HH:mm:ss format]", [Departure Due time in minutes]",

[Scheduled arrival time in

dd/MM/yyyy HH:mm:ss format]", [Scheduled departure time in

HH:mm:ss format]",

[Translated service destination name]",

[Translated service origin name]",

,

[Bus low floor status (yes or no)]",

[Timestamp in dd/MM/yyyy HH:mm:ss format]",


XML:

<realtimeinformation

<errorcode>[Error code]

<errormessage>[Additional error details] <numberofresults>[Number

<stopid>[Stop Id]</

<timestamp>[Date/time information returned] <results>

<result>

<arrivaldatetime <duetime>[Dearture

<departuredatetime

<departureduetime

<scheduledarrivaldatetime

<scheduleddeparturedatetime

<destination>[Service destination name]

<destinationlocalized <origin>[Service origin

<originlocalized

<direction>[Service direction] <operator>[Bus service operator name]

<additionalinformation

<lowfloorstatus

<route>[Route] <sourcetimestamp

</result>

... ...

</results>

</realtimeinformation

3.4.2. Retrieve Timetable Bus Information

Method http://[rtpiserver]/timetableinformation?

e time]&maxresults=[maxresults]

Description Method to retrieve timetable

Parameters - type – required, value: day; time table information is retrieved for given day only

- stopid - required, existing bus stop id

- routeid – optional, route identifier

- datetime – optional, if pro

otherwise timeta

- maxresults – optional, maximum number of results, if not provided system will

for given date

- operator – optional, bus service operator (e.g. DublinBus), if not provided information for all

providers is returned


Response List of buses buses arriving at a g

JSON or XML format.

JSON:


realtimeinformation>

[Error code]</errorcode>

[Additional error details]</errormessage> [Number of results]</numberofresults>

</stopid>

[Date/time information returned]</timestamp>

arrivaldatetime>[Arrival time in dd/MM/yyyy HH:mm:ss format]Dearture Due time in minutes]</duetime >

departuredatetime>[Departure time in

dd/MM/yyyy HH:mm:ss format]</departuredatetimedepartureduetime>[Departure Due time in minutes]</departureduetime

scheduledarrivaldatetime>[Scheduled arrival time in

dd/MM/yyyy HH:mm:ss format]</

scheduleddeparturedatetime>[Scheduled departure time in dd/MM/yyyy HH:mm:ss format]</ scheduleddeparturedatetime

[Service destination name]</destination>

destinationlocalized>[Translated service destination name][Service origin name]</ origin>

originlocalized>[Translated service origin name]</ originlocalized

[Service direction]</ direction> [Bus service operator name]</operator>

additionalinformation>[Additional information]</additionalinformation

lowfloorstatus>[Bus low floor status (yes or no)]</lowfloorstatus

[Route]</route> sourcetimestamp>[Timestamp in dd/MM/yyyy HH:mm:ss format]

realtimeinformation>

Retrieve Timetable Bus Information by Date

/timetableinformation?type=day&stopid=[stopid]&routeid=[routeid]&datetime=[Dat

time]&maxresults=[maxresults]&operator=[operator]&format=[format]

timetable information for given stop number and route

required, value: day; time table information is retrieved for given day only


optional, route identifier

optional, if provided timetable information for given date/time

otherwise timetable for current date/time will be returned

optional, maximum number of results, if not provided system will

optional, bus service operator (e.g. DublinBus), if not provided information for all

providers is returned


buses arriving at a given bus stop (including route number, arrival time and destination) in

of 14

in dd/MM/yyyy HH:mm:ss format]</arrivaldatetime>

departuredatetime> departureduetime>

</ scheduledarrivaldatetime>

Scheduled departure time in dd/MM/yyyy HH:mm:ss scheduleddeparturedatetime>

[Translated service destination name]</destinationlocalized>

originlocalized>

additionalinformation>

lowfloorstatus>

[Timestamp in dd/MM/yyyy HH:mm:ss format]</sourcetimestamp>

stopid=[stopid]&routeid=[routeid]&datetime=[Dat

required, value: day; time table information is retrieved for given day only

given date/time will be returned

optional, maximum number of results, if not provided system will return all results

optional, bus service operator (e.g. DublinBus), if not provided information for all


(including route number, arrival time and destination) in


{

"errorcode" : "

"errormessage" "numberofresults"

"stopid" : [Stop id],

"timestamp" : "

"results" : [{ "arrivaldatetime"

"destination"

"destinationlocalized" "operator"

"lowfloorstatus

"route" : " },

...

...]

}

XML:

<timetableinformation

<errorcode>[Error code] <errormessage>[Additional error details]

<numberofresults>

<stopid>[Stop Id] <timestamp>[Date/time information returned]

<results>

<result>

<arrivaldatetimeformat]</arrivaldatetime

<destination>

<destinationlocalizedname]</destinationlocalized

<operator>[Bus service operator name]

<lowfloorstatus <route>[Route]

</result>

... ...

</results>

</timetableinformation

3.4.3. Retrieve Full Timetable Bus Information

Method http://[rtpiserver]/timetableinformation?

mat]

Description Method to retrieve timetable information for given stop number and route

Parameters - type – required, value: week; time table information is retrieved for whole

- stopid - required, existing bus stop id

- routeid – required, route identifier


Response Timetable for given bus stop and route

JSON:

{

"errorcode" : "


"[Error code]",


: [Stop id],

"[Date/time information returned]",

"arrivaldatetime" : "[Arrival time in dd/MM/yyyy HH:mm:ss format]

"destination" : "[Service destination name]",

"destinationlocalized" : "[Translated service destination name] : "[Bus service operator name]",

lowfloorstatus" : "[Bus low floor status (yes or no)]

"[Route]"

timetableinformation>

[Error code]</errorcode> [Additional error details]</errormessage>

>[Number of results]</numberofresults>

[Stop Id]</stopid> [Date/time information returned]</timestamp>

arrivaldatetime>[Arrival time in dd/MM/yyyy HH:mm:ss arrivaldatetime>

>[Service destination name]</destination>

destinationlocalized>[Translated service destination destinationlocalized>

[Bus service operator name]</operator>

lowfloorstatus>[Bus low floor status (yes or no)]</lowfloorstatus[Route]</route>


Retrieve Full Timetable Bus Information

timetableinformation?type=week&stopid=[stopid]&routeid=[routeid]&

Method to retrieve timetable information for given stop number and route

required, value: week; time table information is retrieved for whole


required, route identifier


Timetable for given bus stop and route in JSON or XML format.

"[Error code]",

of 14

[Arrival time in dd/MM/yyyy HH:mm:ss format]",

destination name]",

[Bus low floor status (yes or no)]",

[Arrival time in dd/MM/yyyy HH:mm:ss

[Translated service destination

lowfloorstatus>

stopid=[stopid]&routeid=[routeid]&format=[for

required, value: week; time table information is retrieved for whole week



"errormessage"

"numberofresults"

"stopid" : [Stop id], "route" : [Route],

"timestamp" : "

"results" : [{

"startdayofweek" "enddayofweek"

"destination"

"destinationlocalized" "lastupdated"

"departures"

"[Departure time in HH:mm:ss format] ...

...

]

}, ...

...]

}

XML:

<timetableinformation <errorcode>[Error code]

<errormessage>[Additional error details]

<numberofresults> <stopid>[Stop Id]

<route>[Route]</route

<timestamp>[Date/time <results>

<result>

<startdayofweek

<enddayofweek <destination>

<destinationlocalized

name]</destinationlocalized <lastupdated>

<departures>

<departure> ...

...

</departures> </result>

...


: "[Additional error details]",

"numberofresults" : [Number of results],

: [Stop id], : [Route],


"startdayofweek" : "[Day of week (0-Sunday, 1-Monday, ...)]"enddayofweek" : "[Day of week (0-Sunday, 1-Monday, ...)]

"destination" : "[Service destination name]",

"destinationlocalized" : "[Translated service destinatio"lastupdated" : "[Last update date/time for this record]

"departures" : [

[Departure time in HH:mm:ss format]",

timetableinformation> [Error code]</errorcode>

[Additional error details]</errormessage>

>[Number of results]</numberofresults> [Stop Id]</stopid>

route>


startdayofweek>[Day of week (0-Sunday, 1-Monday, ...)]

enddayofweek>[Day of week (0-Sunday, 1-Monday, ...)]</>[Service destination name]</destination>

destinationlocalized>[Translated service destination

destinationlocalized> >[Last update date/time for this record]</

>[Departure time in HH:mm:ss format]</departure

>

of 14

Monday, ...)]", Monday, ...)]",

[Translated service destination name]", [Last update date/time for this record]",

Monday, ...)]</startdayofweek>

</enddayofweek>

[Translated service destination

</lastupdated>

departure>


...

</results>

</timetableinformation

3.4.4. Retrieve Bus Stop Information

Method http://[rtpiserver]/busstopinformation?stopid

Description Function to retrieve bus stops defined in the system

Parameters - stopid - optional, bus stop id, if not provided all bus stops are returned

- stopname – optional, stop name, only matching stops are retur

- operator – optional, if provided


Response List of stops defined in the system

JSON:

{

"errorcode" : "


"timestamp" : "

"results" : [{ "stopid" :

"displaystopid"

"shortname"

"shortnamelocalized" "fullname"

"fullnamelocalized"

"latitude" "longitude"

"lastupdated"

"operators" "name"

"routes"

"[Route Number] ...

...

]

... ...

]

},

...

... ...]

}

XML:



Retrieve Bus Stop Information

busstopinformation?stopid=[stopid]&stopname=[stopname

Function to retrieve bus stops defined in the system

optional, bus stop id, if not provided all bus stops are returned

optional, stop name, only matching stops are returned

optional, if provided retrieves data only for given operator


defined in the system in JSON or XML format.

"[Error code]",



: "[Stop Id]",

"displaystopid" : "[Stop Identifier to display for the end user]

" : "[Stop Name]",

"shortnamelocalized" : "[Translated Stop Name]", : "[Full Name]",

"fullnamelocalized" : "[Translated Full Name]",

: "[latitude]", " : "[longitude]",

"lastupdated" : "[Last update date/time for this record]

"operators" : [ : "[Operator Name]",

"routes" : [

[Route Number]",

of 14

stopname]&format=[format]

optional, bus stop id, if not provided all bus stops are returned

retrieves data only for given operator


the end user]",

[Last update date/time for this record]",


<busstopinformation


<errormessage>[Additional error details] <numberofresults>

<timestamp>[Date/time information returned]

<results>

<result> <stopid>[Stop Id

<displaystopid

<shortname>[Stop Name

<shortnamelocalized

<fullname>[Full Name <fullnamelocalized

<latitude>[latitude

<longitude>[longitude

<lastupdated> <operators>

<operator>

<name>[Operator name] <routes>

<route>

... ...

</routes>

</operator> ...

...

</operators>

</result> ...

...

... </results>

</busstopinformation

3.4.5. Retrieve Route Information

Method http://[rtpiserver]/routeinformation?route

Description Function to retrieve route details

Parameters - route - required

- operator – required, operator id


Response List of routes and bus stops

JSON:

{


information>


[Additional error details]</errormessage> >[Number of results]</numberofresults>


Stop Id]</stopid>

displaystopid>[ Stop Identifier to display for the

end user]</displaystopid> Stop Name]</shortname>

shortnamelocalized>[Translated Stop Name]</shortnamelocalized

Full Name]</fullname> fullnamelocalized>[Translated Full Name]</fullnamelocalized

latitude]</ latitude>

longitude]</ longitude>

>[Last update date/time for this record]</

[Operator name]</name>

>[route number]</route>

>

>

busstopinformation>

Retrieve Route Information

routeinformation?routeid=[route]&operator=[operator]&

route details defined in the system

required, requested route id

required, operator id


routes and bus stops defined in the system in JSON or XML format.

of 14

shortnamelocalized>

fullnamelocalized>

</lastupdated>

operator=[operator]&format=[format]



"errorcode" : "

"errormessage"

"numberofresults" "route" : "[Route]

"timestamp" : "

"results" : [{

"operator" "origin" :

"origintranslated"

"destination "destinationtranslated"

"lastupdated"

"stops" : [{ "stopid"

"displaystopid"

"shortname"

"shortnamelocalized" "fullname"

"fullnamelocalized"

"latitude "longitude

},

... ...]

},

... ...]

}

XML:

<routeinformation>


<errormessage>[Additional error details] <numberofresults>

<route>[Date/time information returned]

<timestamp>[Date/time information returned]

<results> <result>

<operator>[Operator name]

<origin>[Origin name] <originlocalized

<destination>

<destinationlocalized <lastupdated>

<stops>

<stop> <stopid>[Stop Id]

<displaystopid

<shortname <shortnamelocalized

<fullname

<fullnamelocalized <latitude

<longitude

<stop> <stops>

</result>

...

...


"[Error code]",


"numberofresults" : [Number of results], [Route]",


: "[Operator name]", : "[Origin name]",

"origintranslated" : "[translated origin name]",

destination" : "[Destination name]", "destinationtranslated" : "[Translated destination name]

"lastupdated" : "[Last update date/time for this record]

: [{ "stopid" : "[Stop Id]",

"displaystopid" : "[Stop Identifier to display for the end user]

"shortname" : "[Stop Name]",

"shortnamelocalized" : "[Translated Stop Name]"fullname" : "[Full Name]",

"fullnamelocalized" : "[Translated Full Name]

latitude" : "[latitude]" longitude" : "[longitude]"

...]


[Additional error details]</errormessage> >[Number of results]</numberofresults>

[Date/time information returned]</route>


[Operator name]</operator>

[Origin name]</origin> originlocalized>[Translated origin name]</originlocalized

>[Destination Name]</destination>

destinationlocalized>[Translated destination name]</destinationlocalized>[Last update date/time for this record]</

[Stop Id]</stopid>

displaystopid>[ Stop Identifier to display for the

end user]</displaystopid>

shortname>[Stop Name]</shortname> shortnamelocalized>[Translated Stop Name]</shortnamelocalized

fullname>[Full Name]</fullname>

fullnamelocalized>[Translated Full Name]</fullnamelocalizedlatitude>[latitude]</ latitude>

longitude>[longitude]</ longitude>

of 14

[Translated destination name]",

[Last update date/time for this record]",

[Stop Identifier to display for the end user]",

[Translated Stop Name]",

[Translated Full Name]",

originlocalized>

destinationlocalized> </lastupdated>

[ Stop Identifier to display for the

shortnamelocalized>

fullnamelocalized>


...

</results>

</routeinformation>

3.4.6. Retrieve Operator

Method http://[rtpiserver]/operatorinformation?format=[format]

Description Function to retrieve information about route operators defined in the system

Parameters - format – optional, valid values: xml, json; if not provided JSON format is used by default.

Response List of all operators in the system in JSON or XML format.

JSON:

{ "errorcode" : "

"errormessage"

"numberofresults" "timestamp" : "

"results" : [{

"operatorreference" "operatorname"

"operatordescription"

},

...

...]

}

XML:

<operatorinformation


<errormessage>[Additional error details]

<numberofresults> <timestamp>[Date/time

<results>

<result> <operatorreference

<operatorname

<operatordescription </result>

...

... ...

</results>

</operatorinformation


>

Retrieve Operator Information

operatorinformation?format=[format]

Function to retrieve information about route operators defined in the system


List of all operators in the system in JSON or XML format.

"[Error code]",


"numberofresults" : [Number of results], "[Date/time information returned]",

"operatorreference" : "[Operator reference code]", "operatorname" : "[Operator name]",

"operatordescription" : "[Operator description]"

operatorinformation>


[Additional error details]</errormessage>

>[Number of results]</numberofresults> [Date/time information returned]</timestamp>

operatorreference>[Operator reference code]</operatorreference

operatorname>[Operator name]</operatorname>

operatordescription>[Operator description]</operatordescription

operatorinformation>

of 14

Function to retrieve information about route operators defined in the system


operatorreference>

operatordescription>


3.4.7. Retrieve Route List Information

Method http://[rtpiserver]/routelistinformation?

Description Function to retrieve list of routes defined

Parameters - operator – optional, if provided retrieves data only for given operator


Response List of routes defined in the system in JSON or XML

JSON:

{

"errorcode" : "


"timestamp" : "

"results" : [{ "operator"

"route" : "

}, ...

...]

}

XML:

<routelistinformation

<errorcode>[Error code] <errormessage>[Additional error details]

<numberofresults>

<timestamp>[Date/time information returned] <results>

<result>

<operator>[Operator reference]

<route>[Route </result>

...

... ...

</results>

</routelistinformation


Retrieve Route List Information

routelistinformation? operator=[operator]&format=[format]

Function to retrieve list of routes defined in the system



List of routes defined in the system in JSON or XML format.

"[Error code]",



: "[Operator Reference]",

"[Route]"

routelistinformation>

[Error code]</errorcode> [Additional error details]</errormessage>

>[Number of results]</numberofresults>


[Operator reference]</operator>

Route]</route>

routelistinformation>

of 14

format=[format]



rtpi rest web services - specification-2• automated feeds (e.g. twitter / rss) • external api...

Documents