This API implements a REST interface to Guestcentric web-services. The exposed methods should be called via HTTP POST methods, and should get a JSON document in return.
All API methods are called via unencrypted HTTP (port 80), with the exception of the booking method, that goes through ssl HTTPS (port 443).
All methods should be authenticated via a "key" parameter (please request your private key from support@guestcentric.com).
Note: The API expects all data to be UTF-8 encoded.
Use the api endpoint followed by the method path to issue a POST request (ie: http://api.guestcentric.net/example/test).
curl http://api.guestcentric.net/example/test -d key=your_api_key
{"error":false,"response":"ok"}
Note: The "key" field parameter is mandatory in every request.
The method should return a json structure with the result. This structure consists in:
curl http://api.guestcentric.net/example/test -d key=wrongKey
Returns:
{"error":true,"error_message":"Invalid key."}
All the examples in this documentation are using json as the output format, this is the default format.
If you prefer, you might receive the output in either XML or PHP (serialized array) format. You just need to
pass an (optional) parameter "format".
curl http://api.guestcentric.net/example/test -d key=your_api_key -d format=xml or curl http://api.guestcentric.net/example/test -d key=your_api_key -d format=php
Return:
<?xml version="1.0"?>
<gc><response>ok</response><error></error></gc>
and
a:3:{s:8:"response";s:2:"ok";s:4:"time";s:6:"0.004s";s:5:"error";b:0;}
These methods return global values to use with the api.
global/is_up
This returns true if the service is up.
Example:
curl http://api.guestcentric.net/global/is_up -d key=your_api_key
Returns:
{
"response": true,
"error": false
}
global/list_amenities
This returns a list of all the possible amenities. Takes no params.
Example:
curl http://api.guestcentric.net/global/list_amenities -d key=your_api_key
Returns:
{
"response": [
{
"name": "Internet access - wireless",
"id": "70"
},
{
"name": "Premium TV channel(s)",
"id": "71"
},
{
"name": "Air conditioning",
"id": "73"
},
{
"name": "Television",
"id": "82"
}
],
"error": false
}
global/list_currencies
This returns a list of all the available currencies. Takes no params.
Example:
curl http://api.guestcentric.net/global/list_currencies -d key=your_api_key
Returns:
{
"response": [
{
"name": "Euro",
"code": "EUR"
},
{
"name": "British Pound Sterling",
"code": "GBP"
},
{
"name": "Japanese Yen",
"code": "JPY"
},
{
"name": "Brazilian Real",
"code": "BRL"
},
...
{
"name": "East Caribbean Dollar",
"code": "XCD"
},
{
"name": "West African CFA franc",
"code": "XOF"
}
],
"error": false
}
global/list_property_types
This returns a list of all the possible property types. Takes no params.
Example:
curl http://api.guestcentric.net/global/list_property_types -d key=your_api_key
Returns:
{"response":["Hotel","Motel","B&B","Resort"],"error":false}
global/list_states
This returns a list of all the possible states (for USA). Takes no params.
Example:
curl http://api.guestcentric.net/global/list_states -d key=your_api_key
Returns:
{
"response": {
"us": [
{
"stateCode": "ak",
"stateName": "AK"
},
{
"stateCode": "al",
"stateName": "AL"
},
{
"stateCode": "ar",
"stateName": "AR"
},
{
"stateCode": "az",
"stateName": "AZ"
},
...
{
"stateCode": "wv",
"stateName": "WV"
},
{
"stateCode": "wy",
"stateName": "WY"
}
]
},
"error": false
}
global/list_countries
This returns a list of all the countries and respective shorthand codes (ISO-3166-1 alpha 2). Takes no params.
Example:
curl http://api.guestcentric.net/global/list_countries -d key=your_api_key
Returns:
{
"response": [
{
"countryCode": "af",
"countryName": "Afghanistan"
},
{
"countryCode": "ax",
"countryName": "Aland Islands"
},
{
"countryCode": "al",
"countryName": "Albania"
},
{
"countryCode": "dz",
"countryName": "Algeria"
},
{
"countryCode": "as",
"countryName": "American Samoa"
},
{
"countryCode": "ad",
"countryName": "Andorra"
},
{
"countryCode": "ao",
"countryName": "Angola"
},
...
{
"countryCode": "zm",
"countryName": "Zambia"
},
{
"countryCode": "zw",
"countryName": "Zimbabwe"
}
],
"error": false
}
global/list_languages
This returns a list of all the supported languages and their respective ISO-639-1 shorthand code. Takes no params.
Example:
curl http://api.guestcentric.net/global/list_languages -d key=your_api_key
Returns:
{
"response": [
{
"name": "English",
"code": "en"
},
{
"name": "French",
"code": "fr"
},
{
"name": "German",
"code": "de"
},
{
"name": "Portuguese",
"code": "pt"
},
{
"name": "Spanish",
"code": "es"
},
{
"name": "Catalan",
"code": "ca"
}
],
"error": false
}
Note: Every method on this namespace expects a mandatory hotelId argument.
hotel/find_offers
Returns a list of offers for the given hotel.
Parameters (all mandatory unless stated otherwise):
curl http://api.guestcentric.net/hotel/find_offers -d key=your_api_key / -d hotelId=ZZZ34 -d currency=EUR -d checkIn='2012-05-22' -d nrNights=2 -d nrRooms=1 -d nrAdults=2 / -d nrChildren=1 -d languageCode=en
Returns:
{
"response": {
"count": 1,
"hotels": [
{
"hotelId": "ZZZ34",
"info": {
"hotelName": "Your Hotel",
"hotelClass": 4,
"hotelDescription": "<p>Nicest hotel around</p>",
"hotelAddress": "Baker street, 23",
"hotelCity": "Lisbon",
"hotelZipCode": "1900",
"hotelState": "State",
"propertyType": "Hotel",
"reservationsPhoneNumber": "342343423",
"reservationsEmail": "reservations@yourhotel.com",
"groupEventsPhoneNumber": "2345252345",
"website": "http:\/\/www.hotelwebsite.com",
"timezone": "Europe\/Lisbon",
"country": "Portugal",
"countryCode": "PT",
"hotelCurrencyCode": "EUR",
"hotelLatitude": "38.62691239577911",
"hotelLongitude": "-9.200513362884521",
"hotelDistance": "10.9367884577599",
"distanceUnit": "Km"
},
"offers": [
{
"offer": "4.2",
"isPromotion": false,
"price": "9",
"name": "double room",
"defaultImage": "https:\/\/secure.guestcentric.com\/bin\/bg\/notDefined.png",
"shortDescription": "romantic room",
"longDescription": "<p>for couples only<\/p>",
"total": 21.6,
"avgPrice": "9",
"tax": "3.60",
"netValue": "18",
},
{
"name": "Cool promotion",
"isPromotion": true,
"price": "11",
"oldprice": "22",
"shortDescription": "cheap double rooms",
"longDescription": "perfect for a relaxing weekend that won't break your wallet",
"defaultImage": "https:\/\/secure.guestcentric.com\/bin\/bg\/notDefined.png",
"offers": [
{
"avgPrice": "11",
"tax": "4.40",
"netValue": "22",
"total": 26.4,
"defaultImage": "https:\/\/secure.guestcentric.com\/bin\/bg\/notDefined.png",
"offer": "6.1",
"name": null,
"shortDescription": null,
"longDescription": "<p>nice room<\/p>"
}
]
},
],
"minPriceForStay": "18"
}
]
},
"error": false
}
hotel/list_rates
Returns a list of best available rates for a given offer, period and hotel.
Parameters (all mandatory unless stated otherwise):
curl http://api.guestcentric.net/hotel/list_rates -d key=your_api_key / -d hotelId=ZZZ34 -d offer=1.1 -d offer=1.1 -d startDate=2012-05-21 -d endDate=2012-06-05 -d nrChildren=1 / -d nrAdults=2 -d currency=EURReturn:
{
"response": [
{
"value": 23,
"day": "2010-01-08"
},
{
"value": 23,
"day": "2010-01-09"
},
{
"value": 23,
"day": "2010-01-10"
},
{
"value": 23,
"day": "2010-01-11"
},
{
"value": 23,
"day": "2010-01-12"
}
],
"error": false
}
hotel/list_amenities
Returns a list of all the available amenities for the given hotel.
curl http://api.guestcentric.net/hotel/list_amenities -d key=your_api_key -d hotelId=ZZZ34
Returns:
{
"response": [
{
"name": "Internet access - wireless",
"id": "70"
},
{
"name": "Premium TV channel(s)",
"id": "71"
},
{
"name": "Air conditioning",
"id": "73"
},
{
"name": "Television",
"id": "82"
}
],
"error": false
}
hotel/list_add_ons
Returns a list of all the available add-ons for the given hotel.
curl http://api.guestcentric.net/hotel/list_add_ons -d key=your_api_key -d hotelId=ZZZ34
Returns:
{
"response": [
{
"addOnId": "2",
"name": "champagne",
"price": "123",
"type": "stay"
},
{
"addOnId": "1",
"name": "breakfast",
"price": "33",
"type": "night"
},
{
"addOnId": "3",
"name": "extra bed",
"price": "33",
"type": "unit"
}
],
"time": "0.017s",
"error": false
}
hotels/find_offers
Returns a list of offers for the matching hotels.
Parameters (all mandatory unless stated otherwise):
curl http://api.guestcentric.net/hotels/find_offers -d key=your_api_key / -d hoteName="Your" -d cityName="Lisbon" -d countryCode="pt" -d currency=EUR / -d checkIn='2012-05-22' -d nrNights=2 -d nrRooms=1 -d nrAdults=2 / -d nrChildren=1 -d languageCode=en
Returns:
{
"response": {
"count": 1,
"hotels": [
{
"hotelId": "ZZZ34",
"info": {
"hotelName": "Your Hotel",
"hotelClass": 4,
"hotelDescription": "<p>Nicest hotel around</p>",
"hotelAddress": "Baker street, 23",
"hotelCity": "Lisbon",
"hotelZipCode": "1900",
"hotelState": "State",
"propertyType": "Hotel",
"reservationsPhoneNumber": "342343423",
"reservationsEmail": "reservations@yourhotel.com",
"groupEventsPhoneNumber": "2345252345",
"website": "http:\/\/www.hotelwebsite.com",
"timezone": "Europe\/Lisbon",
"country": "Portugal",
"countryCode": "PT",
"hotelCurrencyCode": "EUR",
"hotelLatitude": "38.62691239577911",
"hotelLongitude": "-9.200513362884521",
"hotelDistance": "10.9367884577599",
"distanceUnit": "Km"
},
"offers": [
{
"offer": "4.2",
"isPromotion": false,
"price": "9",
"name": "double room",
"defaultImage": "https:\/\/secure.guestcentric.com\/bin\/bg\/notDefined.png",
"shortDescription": "romantic room",
"longDescription": "<p>for couples only<\/p>",
"total": 21.6,
"avgPrice": "9",
"tax": "3.60",
"netValue": "18",
},
{
"name": "Cool promotion",
"isPromotion": true,
"price": "11",
"oldprice": "22",
"shortDescription": "cheap double rooms",
"longDescription": "perfect for a relaxing weekend that won't break your wallet",
"defaultImage": "https:\/\/secure.guestcentric.com\/bin\/bg\/notDefined.png",
"offers": [
{
"avgPrice": "11",
"tax": "4.40",
"netValue": "22",
"total": 26.4,
"defaultImage": "https:\/\/secure.guestcentric.com\/bin\/bg\/notDefined.png",
"offer": "6.1",
"name": null,
"shortDescription": null,
"longDescription": "<p>nice room<\/p>"
}
]
},
],
"minPriceForStay": "18"
}
]
},
"error": false
}
hotels/list_hotels
Returns a list of hotel names and respective info.
Parameters (all optional unless stated otherwise):
curl http://api.guestcentric.net/hotels/list_hotels -d key=your_api_key -d hoteName="Your" -d cityName="Lisbon"
Returns:
{"response":[{"id":"ZZZ34","name":"Your Hotel"}]
or (with extendedInfo=true):
{
"response": {
"hotels": [
{
"info": {
"hotelName": "Your Hotel",
"hotelLatitude": "38.62691239577911",
"hotelLongitude": "-9.200513362884521",
"hotelCity": "Lisbon",
"groupEventsPhoneNumber": "234523345",
"reservationsEmail": "reservations@guestcentric.com",
"hotelAddress": "Lisbon",
"country": "Portugal",
"countryCode": "PT",
"propertyType": "Hotel",
"website": "http:\/\/yourhotel.guestcentric.com",
"timezone": "Europe\/Lisbon",
"hotelDistance": "5.25311",
"distanceUnit": "Km",
"hotelZipCode": "1900",
"hotelClass": "4",
"reservationsPhoneNumber": "324244423",
"hotelState": "State",
"hotelDescription": "Coolest hotel in town"
},
"hotelId": "ZZZ34"
}
],
"count": 1
},
"error": false
}
hotels/list_portal_hotels
Returns a list of hotel names and respective info by portal.
Parameters (all optional unless stated otherwise):
curl http://api.guestcentric.net/hotels/list_hotels -d key=your_api_key -d hotelIds="["cli1","cli2","cli4"]" -d countryCode="pt"
Returns:
"response": {
"hotels": [
{
"hotelName": "Your Hotel",
"hotelClass": "--",
"shortDescription": "",
"longDescription": "",
"currency": "EUR",
"todayBAR": "",
"website": "http:\/\/www.yourhotel.com",
"bookUrl": "https:\/\/secure.guestcentric.com\/\/api\/bg\/book.php?apikey=your_api_key&s=default&l=pt_PT",
"hotelThumbImg": "",
"coordinates": [
null,
null
]
}
],
"countryCode": "",
"languageCode": "en",
"labels": {
"from": "from",
"viewWebsite": "see website",
"streetView": "Street view",
"book": "Book now",
"noaddressfound": "No address found",
"nostreetview": "Street view is not available for this location"
}
},
"time": "0.048s",
"error": false
}
hotels/find_hotels_by_tags
Returns a list of hotel names and respective info by search tags.
Parameters (all optional unless stated otherwise):
curl http://api.guestcentric.net/hotels/find_hotels_by_tags -d key=your_api_key -d search="keyword1,keyword2,keyword3" -d page="2" -d total="25"
Returns:
{
"response": {
"hotels": [
{
"info": {
"hotelName": "Your Hotel",
"hotelLatitude": "38.62691239577911",
"hotelLongitude": "-9.200513362884521",
"hotelCity": "Lisbon",
"groupEventsPhoneNumber": "234523345",
"reservationsEmail": "reservations@guestcentric.com",
"hotelAddress": "Lisbon",
"country": "Portugal",
"countryCode": "PT",
"propertyType": "Hotel",
"website": "http:\/\/yourhotel.guestcentric.com",
"timezone": "Europe\/Lisbon",
"hotelDistance": "5.25311",
"distanceUnit": "Km",
"hotelZipCode": "1900",
"hotelClass": "4",
"reservationsPhoneNumber": "324244423",
"hotelState": "State",
"hotelDescription": "Coolest hotel in town"
},
"hotelId": "ZZZ34"
}
],
"amenities": [
{
"id": "29",
"label": "Concierge desk",
"count": "1"
},
{
"id": "32",
"label": "Bar\/lounge",
"count": "2"
},
{
"id": "35",
"label": "Coffee shop or caffe",
"count": "1"
}
],
"count": 1
},
"error": false
}
hotels/list_geotags_and_experiencetags
Returns a list of hotels geo and experience tags.
Parameters (all optional unless stated otherwise):
curl http://api.guestcentric.net/hotels/list_geotags_and_experiencetags -d key=your_api_key -d languageCode="en"
Returns:
{
"response": {
"geoTags": "{\"Douro\":\"Douro\",\"Lake Placid\":\"Lake Placid\",\"Midlands\":\"Midlands\",\"Napa Valley\":\"Napa Valley\",\"Sierra Nevada\":\"Sierra Nevada\",\"Tristate area\":\"Tristate area\"}",
"experienceTags": "{\"city break\":\"city break\",\"design\":\"design\",\"fishing\":\"fishing\",\"hiking\":\"hiking\",\"romantic\":\"romantic\"}"
},
"time": "0.134s",
"error": false
}
All API methods in this namespace are called via encrypted HTTPS (port 443).
The API endpoint for these methods should be https://secure.guestcentric.net/api/secure/
hotel/validate
Validates the booking data.
Parameters (all mandatory unless stated otherwise):
curl https://secure.guestcentric.net/api/secure/hotel/validate -d key=your_api_key -d hotelId=ZZZ34 / -d checkIn='2012-05-22' -d checkOut='2012-05-23' -d nrRooms=1 -d offer=3.1 -d firstName="John" / -d lastName="Doe" -d countryCode=pt -d creditCardHolderName="John Doe" / -d creditCardNumber="4111111111111111" -d creditCardMonth=12 -d creditCardYear=2013 / -d email="email@domain.com" -d phone="567456345" -d address="Somewhere, 123" / -d city="Bissau" -d zipCode="1234" -d nrAdults=2 -d nrChildren=1 -d creditCardType=Visa -k
Returns:
{"response":"Valid input","error":false}
or
{
"error_list": {
"city": "missing",
"zipCode": "missing",
"creditCardNumber": "invalid"
},
"error_message": "Invalid input.",
"error": true
}
hotel/book
Inserts a booking
NOTE: the booking will be charged in the hotel currency.
Parameters (all mandatory unless stated otherwise):
curl https://secure.guestcentric.net/api/secure/hotel/book -d key=your_api_key -d hotelId=ZZZ34 / -d checkIn='2012-05-22' -d checkOut='2012-05-23' -d nrRooms=1 -d offer=3.1 -d firstName="John" / -d lastName="Doe" -d countryCode=pt -d creditCardHolderName="John Doe" / -d creditCardNumber="4111111111111111" -d creditCardMonth=12 -d creditCardYear=2013 / -d email="email@domain.com" -d phone="3245234524" -d address="Somewhere, 123" / -d city="Bissau" -d zipCode="1234" -d nrAdults=2 -d nrChildren=2 -d creditCardType=Visa -d childrenAges=0,3 / -d currency=EUR -d total=23 -d groupReservation=true -d groupCode=0000200003 -k
Returns:
{"response":{"bookingCode":"0000600035"},"error":false}
hotel/cancel_booking
Cancels a booking
Parameters (all mandatory):
curl https://secure.guestcentric.net/api/secure/hotel/cancel_booking -d key=your_api_key -d hotelId=ZZZ34 / -d lastName="Doe" -d bookingCode=9000001234 -d secureKey=your_secure_key -k
Returns:
TODO...