Login | Register

Example Code:

The tutorials presented on this page show examples of how to use each function currently available in CoachHire API. Before you can get started you will need to register in the Sandbox environment and get your specific App ID and Secret Key.

In the following examples note that the URL specified is to the sandbox environment. The App ID and Secret Key are examples only. You will need to use your personal App ID and Secret Key when making API calls.

The API uses XML protocol when making a call to the Coach Hire system. Any data that is sent back as a result is in JSON format.

Specific examples are provided below;

The XML Header

Every call must be preceded with the following XML code. This is then followed with the specific XML parameters to execute the required function.

<?xml version='1.0' encoding='utf-8'?>
<JobFile>
  <appID>234234</appID>
  <appSecret>aa7a8be59191e948b259a4f8ca25bd207b635577</appSecret>

This will be followed by the specific API request

The XML Footer

At the end of each request, you must provide a footer specifying the URL, the request type as well as some additional options. The example below is based on using PHP;

//Initialize handle and set options (required)http://api.coachhire.com/lib/api/?send=xml');  
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_ANY); 
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);  
curl_setopt($ch, CURLOPT_TIMEOUT, 4);  
curl_setopt($ch, CURLOPT_POSTFIELDS, $request_xml); 
curl_setopt($ch, CURLOPT_REFERER, $_SERVER['HTTP_HOST']); 
curl_setopt($ch, CURLOPT_HTTPHEADER, array( "Content-type: application/atom+xml" )); 

//Execute the request and also time the transaction ( optional )
$start = array_sum(explode(' ', microtime()));
$result = curl_exec($ch); 
$stop = array_sum(explode(' ', microtime()));
$totalTime = $stop - $start;
 
//Check for errors ( again optional )
if ( curl_errno($ch) ) {
    $result = 'ERROR -> ' . curl_errno($ch) . ': ' . curl_error($ch);
} else {
    $returnCode = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
    switch($returnCode){
        case 200:
            break;
        default:
            $result = 'HTTP ERROR -> ' . $returnCode;
            break;
    }
}
 
curl_close($ch);

echo $result; 

Now we will look at the specific API calls. To assist in readability, the API footer information is not repeated for each example. However, the required component of the footer is needed for each API call being made.

Function: Get Vehicle Options

The following code is a complete example of the code required to get Vehicle Options based on the number of passengers and the latitude and longitude of the journey.


<?xml version='1.0' encoding='utf-8'?>
<JobFile>
  <appID>23423413</appID>
  <appSecret>abe1f4dc775a5a055afcd2abfe137b67f615f0bf</appSecret>
  <getAjaxData>
    <getFor>Vehicle</getFor>
    <setPax>2</setPax>
    <datetimePickup>
      <date>18-11-2015</date>
      <time>11:00</time>
    </datetimePickup>
    <datetimeReturn>
      <date>20-11-2015</date>
      <time>14:00</time>
    </datetimeReturn>
    <collection>
      <latitude>51.50406791565994</latitude>
      <longitude>-0.2167654037475586</longitude>
    </collection>
    <destination>
      <latitude>51.62688886390242</latitude>
      <longitude>0.17994403839111328</longitude>
    </destination>
  </getAjaxData>
</JobFile>

See the table below for;

Tag Format Notes
<username> string Name of User making request (optional)
<getAjaxData> N/A This says the API is requesting some data be returned
<getFor> string This value indicates the data requested is for Vehicles
<setPax> integer

The number of passengers - this determines which vehicles are appropriate - In this case 2 passengers

<datetimePickup> date/time

The date format must be as dd-mm-yyyy and the time as hh:mm using standard 24 hour time - This is needed as the date may have an impact on the price

<datetimeReturn> date/time

This is required where it is a return journey. Do NOT include this tag if the journey is only one way

<collection> float

This is split into longitude and latitude coordinates. You must supply this information - There is currently no API call to get map locations

<destination> float Same rules and format as collection coordinates

Data Returned - Get Vehicle Options:

An example of what is returned from the API is shown below. The code of 200 indicates the call was successful. The count (in this example 3) indicates the number of items or vehicle options available. For each vehicle, the API will also return the luggage options. Note that the Value is an integer and will be used later to either get pricing or insert a job. You will need to supply both the Vehicle and Luggage options when using the API to insert a job.

Callback : {
    "code":200,
    "count":1,
    "data":[
        {
            "value":"2",
            "name":"Executive Saloon Car",
            "short_des": "Typically a Mercedes E Class, Audi A6, Volvo S70 or similar. Arrive in comfort and style, comfortably seats 3-4 passengers, great for short or long journeys.",
            "long_des": "Equipped with Satelite Navigation. Leather Seats,Climate Control, Daily Newspaper/Magazine.",
            "images": [],
            "bag":[ 
              {"value":"23","name":"No luggage."}, 
              {"value":"31","name":"Lap Luggage Only"}, 
              {"value":"22","name":"Hand luggage only."}
            ] 
        } 
      ]
    } 

Function: Get Pricing

The Coach Hire system uses an auto-price function. With this most jobs can be priced and booked without any requirement for manual confirmation. The pricing is based on the journey itself - specifically the distance as calculated by the Pick Up and Return dates, the Google Map coordinates and the chosen vehicle. At this stage it is not possible to get pricing for a range of vehicles with a single request. As such you need to make this enquiry for each of the vehicles that you require pricing for.

<?xml version='1.0' encoding='utf-8'?>
   <JobFile>
     <appID>23423411</appID>
     <appSecret>9a83d44f4cc7067d20f8f2f060be3ab6848e6d23</appSecret>
     <username>Sandbox User</username>
     <getAjaxData>
        <getFor>Pricing</getFor>
        <setCar>2</setCar>
        <collection/>
          <latitude>51.0550733</latitude>
          <longitude>-1.7381232000000182</longitude>
        </collection>
        <destination>
          <latitude>52.4836536</latitude>
          <longitude>-1.8926380999999992</longitude>
        </destination>
     </getAjaxData>
   </JobFile>

To break this down: Let's look at each tag and what is required;

Tag Format Notes
<username> string Name of User making request (optional)
<getAjaxData> N/A This says the API is requesting some data be returned
<getFor> string This value indicates the data requested is for Pricing
<setCar> integer

This is the record ID of the vehicle for which pricing is being requested. You will have the record IDs of the vehicles from a Get Vehicle Options request

<collection> float

This is split into longitude and latitude coordinates. You must supply this information - There is currently no API call to get map locations

<destination> float Same rules and format as collection coordinates
<datetimePickup> date/time

The date format must be as dd-mm-yyyy and the time as hh:mm using standard 24 hour time - This is needed as the date may have an impact on the price

<datetimeReturn> date/time

This is required where it is a return journey. Do NOT include this tag if the journey is only one way

Data Returned - Pricing:

Here the return is a single item with a price for the specified journey with the nominated vehicle. This is for information - not used when inserting the job - but rather to enable you to make a decision on that option based on the price.

Callback : {
    "code":200,
    "count":1,
    "data": {
        "price":177
    }
}

Function: Get Journey Type

This call will return the valid Journey Types and their Record ID’s. When inserting a job into the system, you must supply a valid Journey Type by specifying the appropriate record ID. Accordingly, you will need to use this API call to get this information. The request for Journey Type does not require any additional parameters.

<?xml version='1.0' encoding='utf-8'?>
   <JobFile>
     <appID>23423411</appID>
     <appSecret>9a83d44f4cc7067d20f8f2f060be3ab6848e6d23</appSecret>
     <username>Sandbox User</username>
     <getAjaxData>
        <getFor>journeyType</getFor>
    </getAjaxData>
</JobFile>

To break this down: Let'€™s look at each tag and what is required;

Tag Format Notes
<username> string Name of User making request (optional
<getAjaxData> N/A This says the API is requesting some data be returned
<getFor> string This value indicates the data requested is for Pricing

Data Returned - Journey Type:

An example of what is returned from the API is shown below. The code of 200 indicates the call was successful. The count (in this example 8) indicates the number of items or Journey Types available. Note that the Value is an integer and will be used later to insert a job.

Callback : { 
    "code":200, 
    "count":8, 
    "data":[ 
        {"value":"34","name":"Airport Transfer"}, 
        {"value":"41","name":"Birthday"}, 
        {"value":"30","name":"Business Travel"}, 
        {"value":"36","name":"Club or Society"},

 

Function Search

The Search function will retrieve a range of bookings that meet the filter criteria.  The search may be filtered by:

  • Date Range
  • Booking Status
  • External Reference (Your Reference)
     

This function is limited to return a maximum of 10 items per request.  This is manipulated by the tag <page>.  Page 1 will return results 1-10 and page 2 will return results 11-20 etc.  If fewer than 10 are returned on any page, then there are no more matching results.  A call with no results will have a value of 0 (Zero) in the  count.


<?xml version='1.0' encoding='utf-8'?>
<JobFile>
  <appID>23423413</appID>
  <appSecret>abe1f4dc775a5a055afcd2abfe137b67f615f0bf</appSecret>
  <getQuote>
    <filter>
      <page>1</page>
      <status>all</status>
      <extRef></extRef>
      <dateStart>01-12-2015</dateStart>
      <dateEnd>03-12-2015</dateEnd>
    </filter>
    <requests>
      <request>Quote ID</request>
      <request>REF ID</request>
      <request>Name</request>
      <request>TEL</request>
      <request>EMAIL</request>
      <request>DATE OUT</request>
      <request>ROUTE</request>
      <request>CALLBACK</request>
      <request>PROGRESS</request>
      <request>STATUS</request>
      <request>STAFF</request>
      <request>VEHICLE</request>
      <request>PRICE</request>
      <request>DATE BACK</request>
      <request>PAY</request>
      <request>DRIVER</request>
    </requests>
  </getQuote>
</JobFile>

See the table below for an explanation of the input requirements;

Tag Format Notes
<page> integer As each request is limited to a maximum of 10 results, this determines which block of 10 you are requesting
<status> string a status of all will include bookings that otherwise match the search filter.  Other valid values include B for  active Booking and C for Completed Booking.
<extref> string This is an field you can supply when inserting a booking - which can also be used to search.  This does not have to be unique and many bookings can have the same value.
<dateStart> date Must be in this format of DD-MM-YYYY
<dateEnd> date Must be in this format of DD-MM-YYYY

Data Returned: Search

An example of what is returned from the API is shown below. The code of 200 indicates the call was successful.  The count (in this example 2) indicates  the number of bookings that match the search filter; quote_id is the unique Coach Hire booking reference, date1 refers to the date out while date2 refers to the date back. As their are no values in car_name and drivername this means that they have not yet been assigned for these bookings.

Callback : {
  "code":200,
  "count":2,
  "data":[
    {
      "quote_id":"292398",
      "name":"CustomerName1",
      "phone_h":"038410778",
      "phone_m":"0801020305",
      "email":"customer@theirdomain.com",
      "date1":"2016-03-03 05:00:00",
      "route":"Alderbury,
       Salisbury,
       Wil<br> >>LEEDS HILTON,
       NEVILLE S",
      "callback_date":"Not set",
      "progress":"",
      "status_re":"Booking",
      "sales_person":"",
      "car_name":"",
      "price":"50.54",
      "date2":"2016-03-04 04:00:00",
      "pay_ok":" On Account",
      "drivername":"No driver"
    },
    {
      "quote_id":"292399",
      "name":"CustomerName2",
      "phone_h":"038410778",
      "phone_m":"0801020305",
      "email":"customer@theirdomain.com",
      "date1":"2016-03-03 05:00:00",
      "route":"Alderbury,
       Salisbury,
       Wil<br> >>LEEDS HILTON,
       NEVILLE S",
      "callback_date":"Not set",
      "progress":"",
      "status_re":"Booking",
      "sales_person":"",
      "car_name":"",
      "price":"120.00",
      "date2":"2016-03-04 04:00:00",
      "pay_ok":" On Account",
      "drivername":"No driver"
    }
  ]
}

 

Function: Get Quote Data

This function returns all data for a single quote. You must supply the Coach Hire booking reference in this call. The function is shown below:


<?xml version='1.0' encoding='utf-8'?>
<JobFile>
  <appID>23423413</appID>
  <appSecret>abe1f4dc775a5a055afcd2abfe137b67f615f0bf</appSecret>
  <quoteIdGet>292402</quoteIdGet>
</JobFile>
Tag Format Notes
<quoteIdGet>
integer This is the Coach Hire booking reference

Data Returned: Get Quote Data

The information returned has all the data about the quote. It is divided into 3 sections. The first is customer information followed by the journey information and finally the passenger information. Flight details are optional as are the notes.

Callback : {  
  "JobFile":{
    "quote_id":"292402",
    "customer":{
      "email":"custemail@theidomain.com",
      "name":"Customer Test",
      "phoneNumber":"0801020304",
      "mobileNumber":"0801020304",
      "company":"Customer Company",
      "extRef":"201511240406"
    },
    "journey":{
      "datetimePickup":"30-11-2015 00:00:00",
      "datetimeReturn":"",
      "collection":{
        "address":"16 Sterne St, White City, London W12 8AD, UK",
        "note":"",
        "latitude":"51.505243274494994",
        "longitude":"-0.22054195404052734"
      },
      "destination":{
        "address":"25 Canada Square, Canary Wharf, London E14 5LQ, UK",
        "note":"",
        "latitude":"51.50438847107615",
        "longitude":"-0.018324851989746094"
      },
      "directed":"0.0",
      "flightDepartures":{
        "flightNo":"",
        "datetime":""
      },
      "flightArrival":{
        "flightNo":"",
        "datetime":""
      },
      "totalPassenger":"1",
      "vehicle":"3",
      "luggage":"37",
      "journeyType":"43"
    },
    "passenger":{
      "email":"passenger@theirdomain.com",
      "name":"Pax Name1",
      "phoneNumber":"0801020304"
    },
    "pricing":{"totalPrice":"82.50"}
  }
}

Function: Insert Booking

Now that you have gathered the vehicle, luggage, joorney type and price, you are ready to insert a booking to the system. See example below;


<?xml version='1.0' encoding='utf-8'?>
<JobFile>
  <appID>23423413</appID>
  <appSecret>abe1f4dc775a5a055afcd2abfe137b67f615f0bf</appSecret>
  <customer>
    <email>customer@theirdomain.com</email>
    <name>Customer Name</name>
    <phoneNumber>03841XXXX</phoneNumber>
    <mobileNumber>080102XXXX</mobileNumber>
    <company>Customer Company</company>
    <extRef>V001</extRef>
  </customer>
  <journey>
    <datetimePickup>03-03-2016 05:00</datetimePickup>
    <datetimeReturn>04-03-2016 16:00</datetimeReturn>
    <collection>
      <address>Alderbury, Salisbury, Wiltshire SP5 3EN, UK</address>
      <note>Note1</note>
      <latitude>51.0550733</latitude>
      <longitude>-1.7381232000000182</longitude>
    </collection>
    <destination>
      <address>LEEDS HILTON, NEVILLE STREET, LEEDS, LS14</address>
      <note>Note2</note>
      <latitude>52.4836536</latitude>
      <longitude>-1.8926380999999992</longitude>
    </destination>
    <totalPassenger>2</totalPassenger>
    <vehicle>3</vehicle>
    <luggage>23</luggage>
    <journeyType>42</journeyType>
  </journey>
  <passenger>
    <email>passenger@theirdomain.com</email>
    <name>Pax Name</name>
    <phoneNumber>03841XXXX</phoneNumber>
  </passenger>
</JobFile>

Most of these tags have been covered in previous sections.  However, please note other tags as outlined below;

Tag Format Notes
<customer>   Header tag for customer details
<email> email
The customer email address - required
<name>
string
Customer Name - required
<phoneNumber> string Customer Phone - Optional
<mobileNumber> string Customer Mobile - Optional
<company> string Customer Mobile - Optional
<extRef> string Your Reference - Optional (does not need to be unique)
<passenger>   Header tag for passenger details
<email> email The passenger email address - required
<name> string Passenger Name - required

Data Returned - Insert Booking:

The return code of 200 confirms the booking was successfully added. Where an online price can not be calculated, you will get a message of Insert False and a reason. These bookings will have to be manually dealt with at the present time and the quote is not inserted.

Callback : { 
    "code":530,
    "message":"Insert False",
    "quoteId":0,
    "price":0,
    "error":[
       "WARNING - Maybe over driver hours.",
       "WARNING - Maybe require driver accommodation",
       "WARNING - Maybe over driver hours. (maximum limit is:2)"
    ]
}
Callback : {
    "code":200,
    "message":
    "Insert Finish",
    "quoteId":292407,
    "price":445,
    "error":[]
}

Function: Update Booking

At present you may only amend the customer and passenger details on a booking.  Any change to the journey is likely to require a price change and is not available in the initial release

<?xml version='1.0' encoding='utf-8'?>
<JobFile>
  <appID>23423413</appID>
  <appSecret>abe1f4dc775a5a055afcd2abfe137b67f615f0bf</appSecret>
  <quoteId>292405</quoteId> 
  <customer>
    <email>customer@theirdomain.com</email>
    <name>Customer Name</name>
    <phoneNumber>03841XXXX</phoneNumber>
    <mobileNumber>080102XXXX</mobileNumber>
    <company>Customer Company</company>
    <extRef>V001</extRef>
  </customer>
  <passenger>
    <email>passenger@theirdomain.com</email>
    <name>Pax Name</name>
    <phoneNumber>03841XXXX</phoneNumber>
  </passenger>
</JobFile>

Data Returned - Update Booking

All of these tags have been previously explained in the function Insert Booking.  The API will then return the following notice on success:

Callback : {
    "code":200,
    "message":
    "Update Finish."
}

Function: Get Pricing

The Coach Hire system uses set locations.

<?xml version='1.0' encoding='utf-8'?>
   <JobFile>
     <appID>23423411</appID>
     <appSecret>9a83d44f4cc7067d20f8f2f060be3ab6848e6d23</appSecret>
     <username>Sandbox User</username>
     <getAjaxData>
        <getFor>Location</getFor>
     </getAjaxData>
   </JobFile>

To break this down: Let's look at each tag and what is required;

Tag Format Notes
<username> string Name of User making request (optional)
<getAjaxData> N/A This says the API is requesting some data be returned
<getFor> string This value indicates the data requested is for Location

Data Returned - Pricing:

Here the return.

Callback : {
  "code": 200,
  "count": 1,
  "data": [{
    "place_name": " Aintree Racecourse",
    "place_desc": "",
    "place_addr": "",
    "lat": "53.4750268",
    "lng": "-2.952388",
    "miles": "5",
    "pre_arrival": "0",
    "post_arrival": "0",
    "category": "Sporting Venues"
  }]
}