• nw api itinerary

NetWizard Itinerary API

This API is designed specifically for manipulating hop-on hop-off itineraries from the perspective of the passenger.

Contents

• Hop-On Hop-Off Terminology

• Interface Limitations

• Function Reference

  • ping

  • authenticate

  • readUserDetails

  • writeUserDetails

  • readPasses

  • initialiseItinerary

  • readSectors

  • readPickups

  • readLegs

  • validateLeg

  • readLegAvailability

  • readLegAvailabilityRange

  • writeLeg

  • cancelLeg

---

Hop-on Hop-off Terminology

Hop-On Hop-Off
A form of travel, usually by bus, where passenger can board at one location and then disembark at any of a number of predetermined locations along a fixed route of travel. The passenger is free to spend as many days as they like at as few or as many locations along the route however there is usually a maximum time available to complete the entire journey.

Pass
The product the passenger buys. The pass itself contains no confirmed travel but instead determines the itinerary or itineraries of locations they can visit.

Sector
The smallest unit of travel. A sector does not represent a location but rather the road between two locations.

Leg
A collection of one or more booked sectors that represents a continuous block of travel. If the leg spans an overnight stop the passenger will be required to disembark for the night at the overnight stop.

Itinerary
An ordered sequence of sectors that represents the entire journey. The remaining travel is the difference between the sectors in the itinerary and sectors in the booked legs.

Overnight Stop
The last sector for each day ends in an overnight stop. The bus waits at this location until the departure time the next day. Any passengers in the middle of a leg will be required to disembark for the night.

---

Interface Limitations

Passenger Perspective
Only passes stamped with the current user's pax id are visible through this interface. It cannot be used by agents or operators to edit their customer's itineraries.

Enforced Sector Order
Sectors can only be booked in order of their sequence id. A skipped sector cannot be revisited at a later date by this interface.

Static Starting Location
If the starting location is not the lowest sector in the sequence, the preceding sectors are considered skipped sectors.

Static Routes
When the operator makes a route change they need to update existing passes. Any pass that has not been updated by the operator since the route change will not be able to be modified by this interface.

---

Function Reference

---

ping

string ping()

This is a simple test function that returns the string "pong" if called successfully.

Example

 $results = $api->ping();
 var_dump($results);

Results

 string(4) "pong"

---

authenticate

array authenticate(string user, string auth, string method)

Authenticates a user by password or hash and returns an associative array containing details of the authenticated user and the API being called. When attempting to authenticate by hash, force the user id to lower case and append the password. Then take an md5 hash of the results. The required hash algorithm may change in a future revision.

Return Fields

Example 1 - Authentication by password.

 $results = $api->authenticate('john', 'fr33b33r', 'password');
 var_dump($results);

Results

 array(6) {
   ["strSessionID"]=>
   string(42) "PHPSESSID=d4771fc303eb43978dc96469a689eb4a"
   ["strUserID"]=>
    string(4) "john"
   ["strAgentOrgID"]=>
   string(3) "ATA"
   ["strFinEntID"]=>
   string(3) "ATA"
   ["strApplication"]=>
   string(13) "Itinerary API"
   ["strVersion"]=>
   string(3) "0.4"
 }

Example 2 - Authentication by hash.

 $hash = md5('johnfr33b33r');

 $results = $api->authenticate('john', $hash, 'hash');
 var_dump($results);

Results

 array(6) {
   ["strSessionID"]=>
   string(42) "PHPSESSID=84781fc303eb48878dc96469a888eb4a"
   ["strUserID"]=>
   string(4) "john"
   ["strAgentOrgID"]=>
   string(3) "ATA"
   ["strFinEntID"]=>
   string(3) "ATA"
   ["strApplication"]=>
   string(13) "Itinerary API"
   ["strVersion"]=>
   string(3) "0.4"
 }

---

readUserDetails

array readUserDetails()

Returns an associative array containing details of the currently user.

Return Fields

Example

  $results = $api->readUserDetails();
  var_dump($results);

Results

  array(10) {
    ["intPeopleID"]=>
    int(5)
    ["strFirstName"]=>
    string(4) "John"
    ["strLastName"]=>
    string(5) "Smith"
    ["strEmail"]=>
    string(16) "john@example.com"
    ["strMobile"]=>
    string(10) "0123456789"
    ["strUserID"]=>
    string(4) "john"
    ["strAgentOrgID"]=>
    string(3) "ATA"
    ["strAgentOrgName"]=>
    string(25) "Adventure Tours Australia"
    ["strFinEntID"]=>
    string(3) "ATA"
    ["strFinEntName"]=>
    string(25) "Adventure Tours Australia"
  }

---

writeUserDetails

boolean writeUserDetails(array details)

Accepts an associative array of user details and updates the current user record. Only the fields that need to be updated should be provided. Any fields that are not listed in the parameter fields will be ignored. Returns the boolean true if successful.

User Details Fields

Example

  $details = array(
    'strFirstName' => 'Josh',
    'strPasswd' => 'mor3fr33b33r'
  );

  $results = $api->writeUserDetails($details);
  var_dump($results);

Results

  bool(true)

---

readPasses

array readPasses()

Returns an indexed array where each element is an associative array of pass details including as array containing all the itineraries under the pass. Most users will only have a single pass with a single itinerary but it is possible to have multiple passes booked against the one user and multiple itineraries under the one pass. If the user has no passes the array will be empty.

Return Fields

Example

  $results = $api->readPasses();
  var_dump($results);

Results

 array(1) {
   [0]=>
   array(5) {
     ["intCfmNo"]=>
     int(1518073)
     ["strTourCode"]=>
     string(5) "BRUCE"
     ["strTourName"]=>
     string(10) "BRUCE pass"
     ["strTitle"]=>
     string(10) "Bruce Pass"
     ["arrItineraries"]=>
     array(1) {
       [0]=>
       array(12) {
         ["intCfmNo"]=>
         int(1518073)
         ["strTourCode"]=>
         string(5) "BRUCE"
         ["strTourName"]=>
         string(10) "BRUCE pass"
         ["strTitle"]=>
         string(10) "Bruce Pass"
         ["intBasisID"]=>
         int(2793)
         ["strBasisDesc"]=>
         string(15) "Sydney - Cairns"
         ["intSubBasisID"]=>
         int(4505)
         ["strSubBasisDesc"]=>
         string(5) "Gross"
         ["dteTourDate"]=>
         string(11) "05-Feb-2008"
         ["dteFirstDateOfTravel"]=>
         string(11) "08-Feb-2008"
         ["ysnIsConfirmed"]=>
         int(-1)
         ["ysnIsCancelled"]=>
         int(0)
       }
     }
   }
 }

---

initialiseItinerary

boolean initialiseItinerary(integer confirmation)

Loads the specified itinerary into session. An itinerary must be initialised before subsequent function calls can be made. Returns the boolean true if successful.

Example

 $results = $api->initialiseItinerary(19371105);
 var_dump($results);

Results

 bool(true)

readSectors

array readSectors(integer confirmation)

Returns an indexed array where each element an associative array of sector details. The confirmation number must be that of an itinerary that is already initialised.

Return Fields

Example

 $results = $api->readSectors(19371105);
 var_dump($results);

Results

 array(21) {
   [0]=>
   array(9) {
     ["strSectorKey"]=>
     string(11) "SYDSURF:340"
     ["strTourCode"]=>
     string(7) "SYDSURF"
     ["strTourName"]=>
     string(15) "Sydney - Nabiac"
     ["intDay"]=>
     int(17)
     ["intSeqID"]=>
     int(340)
     ["strSuburbDesc_From"]=>
     string(6) "Sydney"
     ["strSuburbDesc_To"]=>
     string(6) "Nabiac"
     ["ysnDEFL"]=>
     int(0)
     ["ysnOvernight"]=>
     int(0)
     ["ysnBooked"]=>
     int(-1)
   }
   [1] => ...

   ...

   [20] => ...
 }

---

readPickups

array readPickups(integer confirmation, string sector)

Returns an indexed array where each element an associative array of pickup details. The confirmation number must be that of an itinerary that is already initialised and the sector key must be in that itinerary.

Return Fields

Example

 $results = $api->readPickups(19371105, 'BRISHER:380');
 var_dump($results);

Results

 array(3) {
   [0]=>
   array(3) {
     ["intPickupID"]=>
     int(4412)
     ["strPickupKey"]=>
     string(19) "BRSYDSURF:1794:4412"
     ["strPickupValue"]=>
     string(33) "BASE BACKPACKERS (SYDNEY) @ 06:25"
   }
   [1]=>
   array(3) {
     ["intPickupID"]=>
     int(4004)
     ["strPickupKey"]=>
     string(19) "BRSYDSURF:1794:4004"
     ["strPickupValue"]=>
     string(41) "KINGS X, CNR MACLEAY & ORWELL ST @ 06:10"
   }
   [2]=>
   array(3) {
     ["intPickupID"]=>
     int(3998)
     ["strPickupKey"]=>
     string(19) "BRSYDSURF:1794:3998"
     ["strPickupValue"]=>
     string(28) "OZ EXPERIENCE OFFICE @ 06:40"
   }
 }

---

readLegs

array readLegs(integer confirmation)

Returns an indexed array where each element an associative array of leg details. The confirmation number must be that of an itinerary that is already initialised.

Return Fields

Sector Fields

Example

 $results = $api->readSectors(19371105);
 var_dump($results);

Results

 array(5) {
   [0]=>
   array(7) {
     ["intLegID"]=>
     int(1)
     ["intLegNumber"]=>
     int(1)
     ["strLegDesc"]=>
     string(19) "Sydney to Byron Bay"
     ["dteTourDate"]=>
     string(11) "05-Feb-2008"
     ["strPickupKey"]=>
     string(19) "BRSYDSURF:1794:3998"
     ["ysnIsWaitList"]=>
     int(0)
     ["arrSectors"]=>
     array(4) { array of sectors }
   }
   [1]=> ...

   ...

   [4]=> ...
   }
 }

---

validateLeg

boolean validateLeg(integer confirmation, string date, string hopon, string pickup, string hopoff)

Returns the boolean true if the specified new leg is bookable. The confirmation number must be that of an itinerary that is already initialised. The hop-on and hop-off sector keys must be in the itinerary specified and the pickup must belong to the hop-on sector. The date must be after the hop-off date of the previous leg if there is one. There must also be availability on all the sectors.

Example

 $results = $api->validateLeg(19371105, '31-Oct-2008', 'BRIS_BYR:365', 'BSTH:1605:4010', 'BYR_NOOSA:400');
 var_dump($results);

Results

 bool(true)

---

readLegAvailability

array readLegAvailability(integer confirmation, string date, string hopon, string pickup, string hopoff)

Returns an associtive array containing details of the leg availability as well as an array of individual sector availability details. The confirmation number must be that of an itinerary that is already initialised. The availability of a leg will generally be the minimum availability of all the sectors.

Return Fields

Sector Fields

Example

 $results = $api->readLegAvailability(134105, '31-Oct-2008', 'HBB:420', 'PHBB:1213:4025', 'BAW:430');
 var_dump($results);

Results

 array(7) {
   ["strHopOnKey"]=>
   string(7) "HBB:420"
   ["strHopOffKey"]=>
   string(7) "BAW:430"
   ["strLegName"]=>
   string(21) "Hervey Bay to Agnes Waters"
   ["dteTourDate"]=>
   string(11) "31-Oct-2008"
   ["intAvailability"]=>
   int(7)
   ["boolThreshold"]=>
   bool(false)
   ["arrSectorAvailability"]=>
   array(2) {
     [0]=>
     array(5) {
       ["strSectorKey"]=>
       string(7) "HBB:420"
       ["strSectorName"]=>
       string(23) "Hervey Bay to Bundaberg"
       ["dteTourDate"]=>
       string(11) "31-Oct-2008"
       ["intAvailability"]=>
       int(7)
       ["boolThreshold"]=>
       bool(false)
     }
     [1]=>
     array(5) {
       ["strSectorKey"]=>
       string(7) "BAW:430"
       ["strSectorName"]=>
       string(25) "Bundaberg to Agnes Waters"
       ["dteTourDate"]=>
       string(11) "31-Oct-2008"
       ["intAvailability"]=>
       int(10)
       ["boolThreshold"]=>
       bool(true)
     }
   }
 }

---

readLegAvailabilityRange

array readLegAvailabilityRange(integer confirmation, string date, string hopon, string pickup, string hopoff)

Returns an array of seven associtive arrays each containing brief availability details for the leg. The range is a seven day period with the fourth day being the requested departure date for the leg. The confirmation number must be that of an itinerary that is already initialised. This function is designed to help find availability on nearby days when the requested day has no seats left.

Return Fields

Example

 $results = $api->readLegAvailabilityRange(134105, '19-Sep-2008', 'HBB:420', 'PHBB:1213:4025', 'BAW:430');
 var_dump($results);

Results

 array(7) {
   [0]=>
   array(3) {
     ["dteTourDate"]=>
     string(11) "16-Sep-2008"
     ["intAvailability"]=>
     int(0)
     ["boolThreshold"]=>
     bool(false)
   }
   [1]=> ...
   ...
   [5]=> ...
   [6]=>
   array(3) {
     ["dteTourDate"]=>
     string(11) "22-Sep-2008"
     ["intAvailability"]=>
     int(10)
     ["boolThreshold"]=>
     bool(true)
   }
 }

---

writeLeg

array writeLeg(integer confirmation, string date, string hopon, string pickup, string hopoff)

Writes the specified new leg to the database and returns an array of leg details if successful. This function will call validate leg as part of the commit process and any errors returned from the validation process will be returned as faults. The leg details are in the same format as a single element from readLegs().

Writing a new leg will uninitialise the itinerary. The itinerary will need to be initialised again if additional modifications to the itinerary are required.

Example

 $results = $api->writeLeg(134105, '30-Nov-2008', 'HBB:420', 'PHBB:1213:4025', 'BAW:430');
 var_dump($results);

Results

 array(7) {
   ["intLegID"]=>
   int(12)
   ["intLegNumber"]=>
   int(4)
   ["strLegDesc"]=>
   string(26) "Hervey Bay to Agnes Waters"
   ["dteTourDate"]=>
   string(11) "30-Nov-2008"
   ["strPickupKey"]=>
   string(20) "BRHERKROOM:1213:4071"
   ["ysnIsWaitList"]=>
   int(0)
   ["arrSectors"]=>
   array(2) {
      [0]=>
      array(7) {
       ["intCfmNo"]=>
       int(1730018)
       ["strSectorKey"]=>
       string(7) "HBB:420"
       ["strTourCode"]=>
       string(3) "HBB"
       ["dteTourDate"]=>
       string(11) "30-Nov-2008"
       ["intSeqID"]=>
       int(420)
       ["strSuburbDesc_From"]=>
       string(10) "Hervey Bay"
       ["strSuburbDesc_To"]=>
       string(8) "Brisbane"
     }
     [1]=>
     array(7) {
       ["intCfmNo"]=>
       int(1730019)
       ["strSectorKey"]=>
       string(7) "BAW:430"
       ["strTourCode"]=>
       string(3) "BAW"
       ["dteTourDate"]=>
       string(11) "30-Nov-2008"
       ["intSeqID"]=>
       int(430)
       ["strSuburbDesc_From"]=>
       string(8) "Brisbane"
       ["strSuburbDesc_To"]=>
       string(12) "Agnes Waters"
     }
   }
 }

---

cancelLeg

boolean cancelLeg(integer confirmation, integer leg)

Cancels the leg and all associated sectors specified by the leg identifier and returns the boolean true if successful. It is important to note that cancellation is done by leg identifier (intLegID) and NOT by leg number (intLegNumber).

Cancelling a leg will uninitialise the itinerary. The itinerary will need to be initialised again if additional modifications to the itinerary are required.

Example

 $results = $api->cancelLeg(134105, 7);
 var_dump($results);

Results

 bool(true)