Yacht Charter API Documentation
CIDS does not provide any facility to update information on Charter Index Online. The data flow is purely one way. There is, however, support for the Retail Yacht Inquiry System which allows your customers to e-mail you about any and all of the yachts that they may be interested in chartering. E-mails are sent directly to you so that you can act on them immediately.
Essential information
When making a request don’t forget:
Your request must provide authentication (user/pass)
You must have an “Accept” header set to “application/xml”
All requests should be made using HTTP GET except inquiry for which HTTP POST is required
Argument errors should be reported back to you. Example: search?featured=1&page=0&size=2
Page numbering uses a 0 based index. Where pages=”63″ the first page is 0 and the last page is 62.
PHP example
The follwing example PHP page is just for demonstration purposes and is not production grade code.
<?php
//Your RysType required for management and inquiry e-mails
$rysType = 'your-rys-type';
//Username
$username = 'your-rys-username';
//Password
$password = 'Your-rys-password';
//The base CIDS URL
$cidsUrl = 'https://www.charterindexonline.com/rest/';
//Request the 2nd page of yachts with 30 yachts to a page
$request = $cidsUrl.'yacht?page=2&size=30&rysType='.$rysType;
//Initiate the session
$session = curl_init($request);
//Include the header in the output
curl_setopt($session, CURLOPT_HEADER, true);
//Only e-mail inquiry requires post
curl_setopt($session, CURLOPT_POST, false);
//Grab return as a String instead of outputting directly
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
//CIDS requires an appropriate Accept header
curl_setopt($session,CURLOPT_HTTPHEADER, array("Accept: application/xml"));
curl_setopt($session, CURLOPT_USERPWD, $username.':'.$password);
//Execute the request and grab the output
$response = curl_exec($session);
curl_close($session);
$status_code = array();
preg_match('/\d\d\d/', $response, $status_code);
// Check the HTTP Status code
switch( $status_code[0] ) {
case 200://Success
break;
default:
die('Your call to Charter Index Data Services returned an unexpected HTTP status of:' . $status_code[0]);
}
//Get the response XML
if (!($xml = strstr($response, '<?xml'))) {
$xml = null;
}
//Use a library to simplify XML handling
$ciXml = simplexml_load_string($xml);
echo $ciXml->yachts['size'].' yachts';
if($ciXml->yachts['page']) {
echo ' on page '.$ciXml->yachts['page'].' of '.$ciXml->yachts['pages'];
}
?>/search
The search API represents the most flexible and useful part of CIDS. It allows for the creation of a set of standard pages, for example:
Caribbean power yachts
search?areaKey=1&type=power&page=0&size=5
West Mediterranean sailing yachts
search?areaKey=6&type=sail&page=0&size=5
As well as for more specific user generated queries.
Usage
Path
/rest/search
Method
GET
Standard parameters
size (int)
The number of results to be displayed per page.
Requesting fewer results will improve service response times.
page (int)
The page number you want returned e.g. (3rd page of 5).
currencyCode (ISO 4217)
The currency to be used based on ISO 4217 codes. We only use a limited set provided by the /currency service.
rysType (String)
Your RYS Type so that we can determine which are your featured yachts.
Search parameters
areaKey (int)
The area that the yacht operates in. The /area service can be used to match the areaKey to a description.
type (all,power,sail)
The type of yacht.
name (String)
The name or partial name of a specific yacht.
guests (int)
Minimum number of guests the yacht can accommodate.
windsurf (true,false)
Yacht must have windsurfing equipment.
kayak (true,false)
Yacht must have kayaking equipment.
waverunner (true,false)
Yacht must have wave runners available.
startDate (yyyy-dd)
Approximate charter start month to check availability and rates.
rate (int)
Approximate charter weekly rate.
rateHigh (int,”inf”)
Approximate charter weekly rate – uses rate to create a specific range of rates. If this is not specified 20% either side of rate will be used. Specifying “inf” denotes no upper limit.
startsWith (0,a-z)
Allows for alpha numeric separation easy navigation by users. List Sailing Yachts starting with A, for example.
featured (true/false)
Only yachts selected as featured for this RYS Type will be returned. rysType must be set correctly to use this feature or you may get unexpected results. If you do not get any results you should check to see that you have some featured yachts selected here.
fleet (true/false)
Only return yachts that are in the fleet of the company linked to the given rysType. If no rysType is provided or the company does not have a fleet no yachts are returned.
Examples
Caribbean sailing yachts
search?areaKey=1&type=sail&page=0&size=2
Name begins with ‘b’, 8 guests and kayak
search?startsWith=b&guests=8&kayak=true&page=1&size=2
Available in Jan 2017 with wave runner and 12 guests
search?startDate=2017-01&waverunner=true&guests=12&page=2&size=3
Featured yachts for given RYS type
search?featured=true&rysType=charterindextest&page=1&size=2
Fleet yachts for given RYS type
search?fleet=true&rysType=charterindextest&page=1&size=2
/inquiry
The inquiry service allows you to quickly and easily build a customer feedback system into your site.
Usage
Path
/rest/inquiry
Method
POST
Standard parameters
currencyCode (ISO 4217)
The currency to be used based on ISO 4217 codes. We only use a limited set provided by the /currency service.
Inquiry parameters
yachtKeys (int[:int:int….])*
Colon separated list of between 1 and 10 yacht keys. yachtKeys=111:1123:3516
name (string)*
The user’s name.
emailAddress (example@example.com)*
The user’s email address.
phoneNumber (string)**
The user’s phone number.
inquiryText (string)**
Any additional specific message added by the user.
rysSearchCriteria (string)
This should be a human readable query that includes the yachts inquired about. It is added to the email so that you know how the yachts were found.
* these fields are mandatory.
** parameter must be present but can be empty (“”).
/yacht
The yacht service provides REST list and show access to yacht information.
List usage
Path:
/rest/yacht
Method:
GET
Standard parameters
size (int)
The number of results to be displayed per page.
Requesting fewer results will improve service response times.
page (int)
The page number you want returned e.g. (3rd page of 5).
currencyCode (ISO 4217)
The currency to be used based on ISO 4217 codes. We only use a limited set provided by the /currency service.
rysType (String)
Your RYS Type so that we can determine which are your featured yachts.
Examples
Full yacht list
yacht?page=2&size=2
Show usage
The yacht key and URN (Unique Resource Name) are attributes on the yacht tag in the xml.
Path:
/rest/yacht/{key}
/rest/yacht/urn/{URN}
Method:
GET
Standard parameters
currencyCode (ISO 4217)
The currency to be used based on ISO 4217 codes. We only use a limited set provided by the /currency service.
rysType (String)
Your RYS Type so that we can determine which are your featured yachts.
Examples
Yacht by key
yacht/4818?rysType=charterindextest¤cyCode=USD
Yacht by URN
yacht/urn/polarstar?rysType=Yourcharterindextest¤cyCode=USD
/currency
The currency service provides REST list and show access to the currencies currently used by CIDS.
List usage
Path
/rest/currency
Method
GET
Examples
All currencies
currency
Show usage
Path
/rest/currency/{code}
Method
GET
Examples
Canadian dollars
currency/CAD