Yacht Charter API Documentation
Charter Index Data Services (CIDS) provides a REST-like API to allow the searching and retrieval of yacht information as XML. This allows user to build a complete search system into their own web sites for use by their customers. CIDS provides enough information to create a brochure for every yacht with images served directly by Charter Index Online to keep your bandwidth costs down and ensure a fast effective response to requests.

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.

In order to connect to CIDS you will need to request a Username and Password from Charter Index and have a basic knowledge of server to server communication using an http library of your choice.

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&#91;0&#93; ) {
    case 200://Success
 
        break;
    default:
        die('Your call to Charter Index Data Services returned an unexpected HTTP status of:' . $status_code&#91;0&#93;);
}

//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&currencyCode=USD

Yacht by URN
yacht/urn/polarstar?rysType=Yourcharterindextest&currencyCode=USD

/area


The area service provides REST list and show access to area information.

List usage

Path
/rest/area

Method
GET

Examples

All areas
area

Show usage

Path
/rest/area/{key}

Method
GET

Examples

West Mediterranean area
area/6

/type


The type service provides REST list and show access to type information.

List usage

Path
/rest/type

Method
GET

Examples

All types
type

Show usage

Path:
/rest/type/{key}

Method:
GET

Examples

Sail type
type/2

/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