Reading Buses APIV2.1.0
A C#, .net Standard Library for the Reading Buses Open Data API (http://rtl2.ods-live.co.uk/cms/apiservice), available to use in your C# console, WPF, UWP or Win Form Applications.
ReadingBusesAPI.ReadingBuses Class Reference

This is the main class for the library, here you can initialise a singleton instance and then query and use the Reading Buses API. More...

Public Member Functions

BusStop GetLocation (string actoCode)
Get a bus stop location based upon a bus stops location code More...
BusStop[] GetLocations ()
All the bus stop locations that Reading Buses Visits More...
bool IsLocation (string actoCode)
Checks to see if the acto code for the bus stop exists in the API feed or not. More...
BusService[] GetServices ()
All the Services Reading Buses Operates More...
BusService[] GetServices (string brandName)
Returns all services Reading Buses Operates under a brand name, for example "pink" would return "22,25,27,29" services. More...
BusService[] GetServices (Company operatorCode)
Returns all services Reading Buses Operates under a specific operator. More...
BusService[] GetService (string serviceNumber)
Returns a service which matches the Service Number passed, because the Reading Buses API now supports, Kennections and Newbury and District a service number can no longer be considered unique. More...
BusService GetService (string serviceNumber, Company operators)
Returns a service which matches the Service Number passed and the bus operator. More...
bool IsService (string serviceNumber)
Checks to see if a service of that number exists or not in the API feed. More...
bool IsService (string serviceNumber, Company operators)
Checks to see if a service of that number exists or not in the API feed, for a specific bus operator. More...
Task< ArchivedBusTimeTable[]> GetVehicleTrackingHistory (DateTime date, string vehicle)
Gets the archived real bus departure and arrival times along with their time table history for a specific vehicle, on a specific date. This can be used to find how late a vehicle was throughout that day. More...

Static Public Member Functions

static void SetCache (bool value)
Sets if you want to cache data into local files or always get new data from the API, which will take longer. More...
static void SetDebugging (bool value)
Sets if you want to debug the library by making requests to a dummy server instead of the real live sever. More...
static void SetWarning (bool value)
Sets if you want to print out warning messages to the console screen or not. Only done so in debug. More...
static void SetFullError (bool value)
Sets if you want to print out the full error logs to console, only needed for debugging library errors. Only done so in debug. More...
static void SetCacheValidityLength (int days)
Sets how long to keep Cache data for before invalidating it and getting new data. More...
static void InvalidateCache ()
Deletes any Cache data stored, Cache data is deleted automatically after a number of days, use this only if you need to force new data early. More...
static async Task< ReadingBuses > Initialise (string apiKey)
Used to initially initialise the ReadingBuses Object, it is recommended you do this in your programs start up. More...
static ReadingBuses GetInstance ()
You will never need more than one ReadingBuses object, a singleton is used to ensure you always get the same instance. More...

Static Package Functions

static void PrintWarning (string message)
Internal method for printing warning messages to the console screen. Only done so in debug. More...
static void PrintFullErrorLogs (string message)
Internal method for printing warning messages to the console screen. Only done so in debug. More...
static Company GetOperatorE (string operatorCodeS)
Converts the short hand code for an operator into its Enum value, for example RGB stands for Reading Buses. More...

Properties

static bool Debugging [get, private set]
Keeps track of if cache data is being used or not More...
static bool Cache = true [get, private set]
Keeps track of if cache data is being used or not More...
static bool Warning = true [get, private set]
Keeps track of if warnings are being outputted to console or not. More...
static bool FullError [get, private set]
Keeps track of if full error logs are being outputted to console or not. More...
static int CacheValidityLength = 7 [get, private set]
Stores how many days cache data is valid for in days before being regenerated More...
static string ApiKey [get, private set]
Holds the users API Key. More...
GpsController GpsController [get]
Stores the GPS controller, which can help get vehicle GPS data. More...

Private Member Functions

ReadingBuses (string apiKey)
Create a new Reading Buses library object, this is the main control. More...
async Task SetUp ()
Creates cache data and retrieves bus services and bus stop data. More...

Static Private Member Functions

static void DeleteInstance ()
Deletes the current singleton instance if there was an error generating one. More...

Private Attributes

Dictionary< string, BusStop > _locations
Holds information on all the bus stops/locations visited by Reading Buses More...
List< BusService > _services
Holds information on all the services operated by Reading Buses More...

Static Private Attributes

static ReadingBuses _instance
The singleton instance More...

Detailed Description

This is the main class for the library, here you can initialise a singleton instance and then query and use the Reading Buses API.

//Optional
ReadingBuses.SetCache(true);
ReadingBuses Controller = await ReadingBuses.Initialise("API KEY HERE");
BusService service = Controller.GetService("17"); or ReadingBuses.GetInstance().GetService("17");

Cached Data is data stored locally in JSON and XML files, stored in a hidden folder called "cache", in the same directory the program is executed from. This is a copy of the results from an API call, such as the bus services and bus stops, because it is unlikely for this data to change regularly. By default the cached data will be updated every 7 days, but you can request new data or disable cache if you wish. Caching data is however faster as you do not need to keep making API requests for data likely to be the same.

Constructor & Destructor Documentation

ReadingBuses()

ReadingBusesAPI.ReadingBuses.ReadingBuses ( string apiKey )
private

Create a new Reading Buses library object, this is the main control.

Parameters
apiKey The Reading Buses API Key, get your own from http://rtl2.ods-live.co.uk/cms/apiservice

Member Function Documentation

DeleteInstance()

static void ReadingBusesAPI.ReadingBuses.DeleteInstance ( )
static private

Deletes the current singleton instance if there was an error generating one.

GetInstance()

static ReadingBuses ReadingBusesAPI.ReadingBuses.GetInstance ( )
static

You will never need more than one ReadingBuses object, a singleton is used to ensure you always get the same instance.

Returns
Returns the ReadingBuses object to be used throughout your program.
Exceptions
InvalidOperationException Thrown if you attempt to get an instance before you have called the "Initialise" function.

See ReadingBuses.Initialise(string) to initially initialise the ReadingBuses Object singleton.

GetLocation()

BusStop ReadingBusesAPI.ReadingBuses.GetLocation ( string actoCode )

Get a bus stop location based upon a bus stops location code

Parameters
actoCode The code of the bus stop
Returns
A Bus Stop object for the Acto Code specified.
Exceptions
ReadingBusesApiExceptionMalformedQuery Thrown if the bus stop does not exist. You should first check with 'IsLocation' If there is any uncertainty.

See ReadingBuses.IsLocation(string) to check if it is a location.

GetLocations()

BusStop [] ReadingBusesAPI.ReadingBuses.GetLocations ( )

All the bus stop locations that Reading Buses Visits

Returns
All the bus stops Reading Buses visits

GetOperatorE()

static Company ReadingBusesAPI.ReadingBuses.GetOperatorE ( string operatorCodeS )
static package

Converts the short hand code for an operator into its Enum value, for example RGB stands for Reading Buses.

Parameters
operatorCodeS
Returns
The Enum equivalent of the bus operator short code.

GetService() [1/2]

BusService [] ReadingBusesAPI.ReadingBuses.GetService ( string serviceNumber )

Returns a service which matches the Service Number passed, because the Reading Buses API now supports, Kennections and Newbury and District a service number can no longer be considered unique.

Parameters
serviceNumber The service number/ID for the service you wish to be returned eg: 17 or 22.
Returns
The services matching the ID.
Exceptions
ReadingBusesApiExceptionMalformedQuery Thrown if the bus services does not exist. You should first check with 'IsService' If there is any uncertainty.

See ReadingBuses.IsService(string) to check if it is a service.

GetService() [2/2]

BusService ReadingBusesAPI.ReadingBuses.GetService ( string serviceNumber,
Company operators
)

Returns a service which matches the Service Number passed and the bus operator.

Parameters
serviceNumber The service number/ID for the service you wish to be returned eg: 17 or 22.
operators The bus operator to search in, for example "ReadingBuses"
Returns
The services matching the ID.
Exceptions
ReadingBusesApiExceptionMalformedQuery Thrown if the bus services does not exist. You should first check with 'IsService' If there is any uncertainty.

See ReadingBuses.IsService(string) to check if it is a service.

GetServices() [1/3]

BusService [] ReadingBusesAPI.ReadingBuses.GetServices ( )

All the Services Reading Buses Operates

Returns
All the Services Reading Buses Operates

GetServices() [2/3]

BusService [] ReadingBusesAPI.ReadingBuses.GetServices ( Company operatorCode )

Returns all services Reading Buses Operates under a specific operator.

Parameters
operatorCode The operator to filter by.
Returns
An array of Bus Services which are of the brand name specified.

GetServices() [3/3]

BusService [] ReadingBusesAPI.ReadingBuses.GetServices ( string brandName )

Returns all services Reading Buses Operates under a brand name, for example "pink" would return "22,25,27,29" services.

Parameters
brandName The brand name for the services you wish to find, eg "pink" or "sky blue".
Returns
An array of Bus Services which are of the brand name specified.

GetVehicleTrackingHistory()

Task<ArchivedBusTimeTable[]> ReadingBusesAPI.ReadingBuses.GetVehicleTrackingHistory ( DateTime date,
string vehicle
)

Gets the archived real bus departure and arrival times along with their time table history for a specific vehicle, on a specific date. This can be used to find how late a vehicle was throughout that day.

Parameters
date The date you want a report for, must be in the past.
vehicle The vehicle ID number
Returns
An array of Archived Bus Departure and arrival times with their timetabled data.
Exceptions
ReadingBusesApiExceptionMalformedQuery If you have tried to get data for a date in the future. Or if you have not provided any date, and/or you have not provided at least either the service or location or vehicle.
ReadingBusesApiExceptionBadQuery Thrown if the API responds with an error message.
ReadingBusesApiExceptionCritical Thrown if the API fails, but provides no reason.

Initialise()

static async Task<ReadingBuses> ReadingBusesAPI.ReadingBuses.Initialise ( string apiKey )
static

Used to initially initialise the ReadingBuses Object, it is recommended you do this in your programs start up.

Parameters
apiKey The Reading Buses API Key, get your own from http://rtl2.ods-live.co.uk/cms/apiservice
Returns
An instance of the library controller. This same instance can be got by calling the "GetInstance" method.
Exceptions
ReadingBusesApiExceptionBadQuery Can throw an exception if you pass an invalid or expired API Key.

See ReadingBuses.GetInstance() to get any future instances afterwards.

InvalidateCache()

static void ReadingBusesAPI.ReadingBuses.InvalidateCache ( )
static

Deletes any Cache data stored, Cache data is deleted automatically after a number of days, use this only if you need to force new data early.

IsLocation()

bool ReadingBusesAPI.ReadingBuses.IsLocation ( string actoCode )

Checks to see if the acto code for the bus stop exists in the API feed or not.

Parameters
actoCode The ID Code for a bus stop.
Returns
True or False depending on if the stop is in the API feed or not.

IsService() [1/2]

bool ReadingBusesAPI.ReadingBuses.IsService ( string serviceNumber )

Checks to see if a service of that number exists or not in the API feed.

Parameters
serviceNumber The service number to find.
Returns
True or False for if a service is the API feed or not.

IsService() [2/2]

bool ReadingBusesAPI.ReadingBuses.IsService ( string serviceNumber,
Company operators
)

Checks to see if a service of that number exists or not in the API feed, for a specific bus operator.

Parameters
serviceNumber The service number to find.
operators The specific bus operator you want to search in.
Returns
True or False for if a service is the API feed or not.

PrintFullErrorLogs()

static void ReadingBusesAPI.ReadingBuses.PrintFullErrorLogs ( string message )
static package

Internal method for printing warning messages to the console screen. Only done so in debug.

Parameters
message The message to print off to console.

PrintWarning()

static void ReadingBusesAPI.ReadingBuses.PrintWarning ( string message )
static package

Internal method for printing warning messages to the console screen. Only done so in debug.

Parameters
message The message to print off to console.

SetCache()

static void ReadingBusesAPI.ReadingBuses.SetCache ( bool value )
static

Sets if you want to cache data into local files or always get new data from the API, which will take longer.

Parameters
value True or False for if you want to get Cache or live data.
Exceptions
ReadingBusesApiExceptionMalformedQuery Thrown if you attempt to change the cache options after the library has been instantiated

SetCacheValidityLength()

static void ReadingBusesAPI.ReadingBuses.SetCacheValidityLength ( int days )
static

Sets how long to keep Cache data for before invalidating it and getting new data.

Parameters
days The number of days to store the cache data for before getting new data.

SetDebugging()

static void ReadingBusesAPI.ReadingBuses.SetDebugging ( bool value )
static

Sets if you want to debug the library by making requests to a dummy server instead of the real live sever.

Parameters
value True or False for if you want to debug or not.

Unless you are developing or editing library in some way you should not need to use this.

SetFullError()

static void ReadingBusesAPI.ReadingBuses.SetFullError ( bool value )
static

Sets if you want to print out the full error logs to console, only needed for debugging library errors. Only done so in debug.

Parameters
value True or False for printing full error logs to console.

SetUp()

async Task ReadingBusesAPI.ReadingBuses.SetUp ( )
private

Creates cache data and retrieves bus services and bus stop data.

Returns
Gets the basic bus stops and services data.
Exceptions
ReadingBusesApiExceptionBadQuery If the API key is invalid or expired.

SetWarning()

static void ReadingBusesAPI.ReadingBuses.SetWarning ( bool value )
static

Sets if you want to print out warning messages to the console screen or not. Only done so in debug.

Parameters
value True or False for printing warning messages.

Member Data Documentation

_instance

ReadingBuses ReadingBusesAPI.ReadingBuses._instance
static private

The singleton instance

_locations

Dictionary<string, BusStop> ReadingBusesAPI.ReadingBuses._locations
private

Holds information on all the bus stops/locations visited by Reading Buses

_services

List<BusService> ReadingBusesAPI.ReadingBuses._services
private

Holds information on all the services operated by Reading Buses

Property Documentation

ApiKey

string ReadingBusesAPI.ReadingBuses.ApiKey
static get private set package

Holds the users API Key.

Cache

bool ReadingBusesAPI.ReadingBuses.Cache = true
static get private set package

Keeps track of if cache data is being used or not

CacheValidityLength

int ReadingBusesAPI.ReadingBuses.CacheValidityLength = 7
static get private set package

Stores how many days cache data is valid for in days before being regenerated

Debugging

bool ReadingBusesAPI.ReadingBuses.Debugging
static get private set package

Keeps track of if cache data is being used or not

FullError

bool ReadingBusesAPI.ReadingBuses.FullError
static get private set package

Keeps track of if full error logs are being outputted to console or not.

GpsController

GpsController ReadingBusesAPI.ReadingBuses.GpsController
get

Stores the GPS controller, which can help get vehicle GPS data.

Warning

bool ReadingBusesAPI.ReadingBuses.Warning = true
static get private set package

Keeps track of if warnings are being outputted to console or not.


The documentation for this class was generated from the following file:
ReadingBusesAPI.ReadingBuses.ReadingBuses
ReadingBuses(string apiKey)
Create a new Reading Buses library object, this is the main control.
Definition: ReadingBuses.cs:58