XML API endpoints

You will need a ReviewSubject (hash) and an API key for authorising your requests. You can request them from our Customer Support team. 

Reviews

https://api.customer-alliance.com/reviews/list?version=4&id={reviewSubject}&access_key={apiKey}

This endpoint allow access to your Customer Alliance-collected reviews on your website. There are some additional parameters you can add to the URL to customize which reviews you receive. 

Parameters

Name
Default value
Type
Description
Name
Default value
Type
Description

id

Mandatory

string

Review Config Hash, the Review Subject for which subject you would like to retrieve data, provided by Customer Alliance.

access_key

Mandatory

string

Access Key to authorize the request, ask our Customer Care Team for it.

limit

50

number

This is the number of reviews per request.  The maximum allowed value is 1000. If left empty, this will automatically be set to 50.

offset

0

number

This corresponds to the &limit parameter. By default, this is 0. So, if &limit is 50 and &offset is 0 and there are 300 possible reviews, this means that it will show the first 50 results. I.e.

&limit=50&offset=0 results 0.50 of 300

&limit=50&offset=50 results 50, 100 of 300

&limit=50&offset=100 results 100, 150 of 300

order

DESC

ASC|DESC

This is the order of the reviews, i.e. the reviews are ordered by date ASCending or DESCending. By default, the order is set to descending so that the latest reviews will be displayed first unless you set the &orderBy parameter.

orderBy

date

date|rating

By default, this is set to date. You can use this parameter to sort reviews by DATE or by the RATING. The order is specified by the &order parameter, which is DESC by default.

monthsAgo

none

number

If you want to view all reviews since 2 years ago, you could use this parameter. Simply append &monthsAgo to the URL and the reviews will be from the last 2 years (24 months). There is no default value for this parameter. If you send this value,  &start and &end will be ignored.

start

none

ISO 8601 (Y-m-d)
Note: all dates are in timezone Europe/Berlin

By default, this is blank. If &monthsAgo is set, any value for this parameter will be ignored&start is used to specify a date range. If you wanted to view all reviews since or after 2013-08-26, you would set the start date to this value and leave &end empty. Both &start and &end must follow the date format Y-m-d. That is year (YYYY), month (MM), and date (DD). &start is the earliest date/farthest date in the past.

end

none

ISO 8601 (Y-m-d)
Note: all dates are in timezone Europe/Berlin

Please see also the description for &start.

&end is the latest date or the closest date to the present. To see reviews before a certain date, you would use &end on its own (leave &start empty). To see reviews between two dates, set both &start and &end. Be sure that &end is greater than &start otherwise you will receive an error.

language

none

ISO 639-1 code

By this parameter you can filter reviews to a certain language

_locale

en

ISO 639-1 code

By &_locale you can specify the language for the translatable categories, such as rating categories. If not specified a language will be guessed based on the request headers (Accept-Language). If this header is missing or cannot be used to guess, the language fallback, "en", will be used.

Examples

Shell

curl --location --request GET 'https://api.customer-alliance.com/reviews/list?version=4&id={reviewSubject}&access_key={accessKey}&limit=100&offset=0&order=ASC'

Response

<?xml version="1.0" encoding="UTF-8"?> <root> <business> <name>Hotel XYZ</name> <street>123 fake street</street> <city>Fakeville</city> <postCode>123456</postCode> <country>New Country</country> <bookingUrls> <!-- This is a list of your booking urls --> <bookingUrl lang="de">https://de.hotelxyz.web</bookingUrl> <bookingUrl lang="en">https://en.hotelxyz.web</bookingUrl> <bookingUrl lang="fr">https://fr.hotelxyz.web</bookingUrl> <bookingUrl lang="es">https://es.hotelxyz.web</bookingUrl> <bookingUrl lang="nl">https://nl.hotelxyz.web</bookingUrl> <bookingUrl lang="it">https://it.hotelxyz.web</bookingUrl> </bookingUrls> <ratingPositivePercent>98.3</ratingPositivePercent> <reviewCount>2000</reviewCount> <overallRating scale="5">4.4</overallRating> <subcategoryRatings> <subcategoryRating> <category id="price">Price</category> <averageRating scale="5">4.2</averageRating> </subcategoryRating> <subcategoryRating> <category id="room">Room</category> <averageRating scale="5">4.2</averageRating> </subcategoryRating> <subcategoryRating> <category id="location">Location</category> <averageRating scale="5">4.3</averageRating> </subcategoryRating> <subcategoryRating> <category id="clean">Cleanliness</category> <averageRating scale="5">4.5</averageRating> </subcategoryRating> <subcategoryRating> <category id="service">Service</category> <averageRating scale="5">4.6</averageRating> </subcategoryRating> <subcategoryRating> <category id="break">Breakfast</category> <averageRating scale="5">4.5</averageRating> </subcategoryRating> </subcategoryRatings> </business> <reviews> <!-- Each returned review is encapsulated in a review tag --> <review> <id>13942327791</id> <author>Joe Bloggs</author> <date>2017-02-22 21:47:09</date> <arrivalDate>2018-06-28</arrivalDate> <departureDate>2018-06-29</departureDate> <dateOfExperience>2017-04</dateOfExperience> <netPromoterScore>9</netPromoterScore> <reviewerAge>40</reviewerAge> <reviewerType>private</reviewerType> <yourComment>Your review reply</yourComment> <language>de</language> <overallRating scale="5">4.2</overallRating> <overallComment>A Nice review comment</overallComment> <subcategoryRatings> <subcategoryRating> <category id="price">Price</category> <rating scale="5">5</rating> <comment>A comment about the price</comment> </subcategoryRating> <subcategoryRating> <category id="room">Room</category> <rating scale="5">4</rating> <comment>A comment about the room</comment> </subcategoryRating> <subcategoryRating> <category id="location">Location</category> <rating scale="5">4</rating> <comment>A comment about the location</comment> </subcategoryRating> <subcategoryRating> <category id="clean">Cleanliness</category> <rating scale="5">4</rating> <comment>A comment about the cleanliness</comment> </subcategoryRating> <subcategoryRating> <category id="service">Service</category> <rating scale="5">4</rating> <comment>A comment about the service</comment> </subcategoryRating> </subcategoryRatings> </review> </reviews> </root>

Potential Errors

error_message
Further information
error_message
Further information

The option "&limit" has the value "a", which is invalid

This can also apply to:

  • "&offset" parameter

  • "&monthsAgo" parameter

This means the values entered are not valid

The option "&order" has the value "322", but is expected to be either "ASC" or "DESC"

The "&order" parameter can only be ASC or DESC



The option "&end" has the value "", which it is invalid ||| Start date: (2014-05-08) must be farther in the past than End date: (2014-02-08)

This means that the start date is greater than or equal to the end date.

The start date must be farther in the past than the end date.

The option "&start" has the value "2014-05-082" which is invalid

This can also apply to the end date

This means one of the entered dates does not match the expected format Y-d-m, e.g. 2014-02-03

The option "&orderBy" has the value "rating2", but is expected to be either "rating" or "date"

The "&orderBy" value must be either rating or date

The default is date

Sample Error Response

<?xml version="1.0" encoding="UTF-8"?> <root> <error>The option "start" with value "" is expected to be of type "null", "string" |||| 20132-02-03 Not of format Y-m-d</error> </root>

Statistics

https://api.customer-alliance.com/statistics?id={reviewSubject}&access_key={apiKey}

The Statistics API will retrieve your global statistics. These statistics include portal ratings, total reviews, total portals, and average rating.

Note: The data is refreshed every 2 hours.

Parameters

Name
Default value
Type
Description
Name
Default value
Type
Description

id

Mandatory

string

Review Subject, ask our Customer Care team for this value.

access_key

Mandatory

string

Access Key to authorise the request, provided by Customer alliance.

_locale

en

ISO 639-1 code

Through &_locale you can specify the language for the translatable categories, such as rating categories. If not specified, then a language will be guessed based on the request headers (Accept-Language). If this header is missing or cannot be used to guess, the language fallback, "en", will be used.

Examples

Shell

Response