API Reference

The Travel Appeal API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP methods, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, so you can convert responses to appropriate language-specific objects.

The API endpoint is https://apibeta.travelappeal.com/api/ for single property access and https://apibeta.travelappeal.com/groups-api/ for groups access. It will be referred to as TABASEURL. Travel Appeal APIs are restricted for Partners usage. In order to access them, you need to have a special secret Access Token which can only be released and licensed by Travel Appeal, here in after referred to as APIKEY.

If you or your company would like to access Travel Appeal API set, please fill in the form at http://travelappeal.com/api. This will get the partnership process started and after certification you will be sent a private access token. At the time of delivery of APIKEY, only the features required by the partner will be enabled, according with the purchased license. It is up to the Partner to request the activation of additional features.

All API requests must be made over HTTPS. Calls made over plain HTTP will be redirected to HTTPS protocol. API requests without authentication will fail.

API Content List

Property

This API belong to property management, search and discovery. A property is the set of information regarding any restaurant, hotel venue or cultural property anywhere in the world.

Search

curl '<TABASEURL>/propertySearch' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "channel_name": "google",
  "channel_id": "..."
}
BODY

The search response is the following:

{
    "properties": [
        {
            "name": "My restaurant",
            "address": "My address",
            "type": "venue",
            "category": "restaurant",
            "stars": null,
            "rooms": null,
            "latitude": 33.0000,
            "longitude": 35.0000,
            "channels": {
                "tripadvisor": [
                  "https://www.tripadvisor.com/trip/myrestaurant"
                ]
            }
        }
    ]
}

This API allows to search properties inside the Travel Appeal database starting from a channel identifier and retrieve in response all the properties found that match the input channel identifier.

A channel identifier can match with multiple properties, for example with Google channel you can use the Place ID as channel identifier and it is possible that multiple properties have that identifier.

In the case that there are no property found, we recommend you to use the discovery call.

The output contains information such as: id, name, address, type, category, stars, rooms, latitude, longitude and channels. Every field can be nullable except of name, type and category.

Parameters

Channel name and identifier

Param	Type	Required	Description
channel_name	string	yes	Name of the channel (e.g. tripadvisor)
channel_id	string	yes	Channel identifier.

Discover

curl '<TABASEURL>/propertyDiscover' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "name": "Restaurant",
  "location": {
    "full_address": "108 W 32nd St, New York, NY 10001, United States",
    "latitude": 43.7699,
    "longitude": 11.2556
  },
  "channels": {
    "tripadvisor": [
      "https://www.tripadvisor.com/trip/myrestaurant"
    ]
  },
  "placeId":"google_place_id",
  "excludeChannels":["website"]
}
BODY

The discover response is the following:

{
  "name": "Restaurant",
  "type": "venue",
  "category": "restaurant",
  "location": {
    "full_address": "108 W 32nd St, New York, NY 10001, United States",
    "latitude": 43.7699,
    "longitude": 11.2556
  },
  "channels": {
    "tripadvisor": [
      "https://www.tripadvisor.com/trip/myrestaurant"
    ]
  },  
  "id": 1
}

This API allows to discover the information regarding a property from an url (Tripadvisor or Booking.com) or a google place id (more info here). Inside the discover response the id field will contain the property id if the property already exists in the Travel Appeal database, otherwise the id field will be empty. The returned json could be used as the input to create a new property using property API call. You can also specify an additional parameter called excludeChannels that allow the procedure to skip a single channel.

The discovery process can take a long time to complete, in order to avoid requests wait for a long time, we implemented a long polling system, that is described step by step.

1. Start discover process

The first step is to make a POST API request to the discover endpoint with the request body showed on the right and documented below. This API call will return a response with a 202 Accepted HTTP code and a Location header in which is contained the endpoint of the discover request status.

POST <TABASEURL>/propertyDiscover

Parameters

Tripadvisor/Booking url

Param	Type	Required	Description
channels	object	yes	Array of channels urls. Tripadvisor or Booking url is mandatory. See configurations for more details.

Google place id

Param	Type	Required	Description
placeId	string	yes	Google place id. Must be a valid google place id.

Exclude channels

Param	Type	Required	Description
excludeChannels	array	no	Array of channels. See the networks section.

2. Check discover status

To check the discover request status, make an API request at the endpoint given by the step 1, as shown:

GET <TABASEURL>/propertyDiscoverQueue?id=<REQUESTID>

If the discover process is not finished, this API returns a JSON with a status parameter with one of the following values:

• pending the discover process is not started yet
• processing the discover process is in progress
• error the discover process is failed

When the discover process is finished this API call returns a 303 - See Other HTTP code and a Location header in which is contained the discover response.

3. Get discover response

Finally the discover response, as shown in the right panel, is available at the endpoint given by the step 2, e.g.

GET <TABASEURL>/propertyDiscover?id=<REQUESTID>

Note: the discover response will be available for 1 day after its completion, it will be deleted and a 404 Not Found HTTP code will be returned.

Add

curl '<TABASEURL>/property' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "name": "Restaurant",
  "type": "venue",
  "category": "restaurant",
  "location": {
    "full_address": "108 W 32nd St, New York, NY 10001, United States",
    "latitude": 43.7699,
    "longitude": 11.2556
  },
  "channels": {
    "tripadvisor": [
      "https://www.tripadvisor.com/trip/myrestaurant"
    ],
    "facebook": [
      "https://www.facebook.com/myrestaurant"
    ],
    "autoDiscoverPlaceId":"google_place_id"
  }
}
BODY

If everything is fine the above command returns the following output:

{
    "id": 1234567890,
    "verified": false,
    ...    
}

This API allows to add or modify a property. Once added, a property maintains the “unverified” status until it is checked and confirmed by Travel Appeal. If the optional parameter autoDiscoverPlaceId is specified, the API will automatically trigger discovery process in order to retrieve the additional missing channels.

HTTPS Request

POST <TABASEURL>/property

Parameters

Param	Type	Required	Description
name	string	yes	Property name.
type	string	yes	Type of the property. See configurations for more details.
category	string	yes	Category of the property. See configurations for more details.
channels	object	yes	Array of channels urls. At least one must be valorized. See configurations for more details.
location	object	yes	Property address information. The full address (full_address) is mandatory if latitude and longitude are not specified.
autoDiscoverPlaceId	string	no	Google place id. Must be a valid google place id.

Modify channels urls

curl '<TABASEURL>/property' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "id": 1234567890,
  "channels": {
    "tripadvisor": [
      "https://www.tripadvisor.com/trip/myrestaurant"
    ],
    "facebook": [
      "https://www.facebook.com/myrestaurant"
    ]
  }
}
BODY

If everything is fine the above command returns the following output:

{
    "id": 1234567890,
    "verified": false,
    ...    
}

This API allows to modify the channels urls of a property or a competitor. The urls can be modified until the property, or the competitor, maintains the “unverified” status - as it is checked and confirmed by Travel Appeal. If the property is verified, only the partner who added it, can modify its channels.

HTTPS Request

PUT <TABASEURL>/property

Parameters

Param	Type	Required	Description
id	int/string	yes	If referred to a property the id must be int; otherwise it must be string.
channels	object	yes	Array of channels urls. At least one must be valorized. See configurations for more details.

Activate / Deactivate

-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "id": 1,
  "enabled": true
}
BODY

If everything is fine the above command returns:

{
  "enabled": true
}

This API allows to enable or disable a license for a single property.

Note: Property activation may take some time, it is possible that the first API requests after the activation shows the property not enabled error.

HTTPS Request

POST <TABASEURL>/activation

Parameters

Param	Type	Required	Description
id	int	yes	Property id.
enabled	bool	yes	Flag to enable or disable the property license.

Add a Competitor

curl '<TABASEURL>/competitor' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "id": 1,
  "competitor_id": 2
}
BODY

If everything is fine the above command returns:

{
    "competitor_id": "c:1:2"
}

This API allows to add a competitor to a property. The property must be connected to an active license and you must not have reached the maximum competitor number allowed by your level of agreement with Travel Appeal.

Note: In order to view competitors data, you must use the value competitor_id of this response (e.g. c:1:2) in all the data-related API requests inside the monitor_ids field.

HTTPS Request

POST <TABASEURL>/competitor`

Parameters

Param	Type	Required	Description
id	int	yes	Property id.
competitor_id	int	yes	Property competitor id.

Remove a Competitor

curl -X DELETE '<TABASEURL>/competitor' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "id": 1,
  "competitor_id": "c:1:2"
}
BODY

If everything is fine the above command returns:

true

This API allows to remove a competitor from a property. The property must be connected to an active license. You can remove a competitor only after the time limit specified in your license has expired.

HTTPS Request

DELETE <TABASEURL>/competitor

Parameters

Param	Type	Required	Description
id	int	yes	Property id.
competitor_id	int	yes	Property competitor id.

Health Check

curl '<TABASEURL>/propertyCheck' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "id": 1
}
BODY

If everything is fine the above command return the following output:

{
  "property": {
    "ready": true,
    "channels": {
      "tripadvisor": "ready",
      "booking": "ready"
    }
  },
  "competitors": {
    "c:1:2": {
      "ready": true,
      "channels": {
        "tripadvisor": "pending",
        "booking": "pending"
      }
    }
  }
}

This API allows to check the status of a property and its competitor(s). The property must be connected to an active license. If the ready field is set as true then the data is available for consulting. In the channels object is specified the status for each inserted channel. The status for each channel can have three different values:

• ready: the data is available for consulting.
• pending: the data is going to be retrieved from the channel.
• error: the data is not available for the specified channel or it was not possibile to process the channel for three hours after its insertion.

HTTPS Request

POST <TABASEURL>/propertyCheck

Parameters

Param	Type	Required	Description
id	int	yes	Property id.

Info

curl '<TABASEURL>/propertyInfo' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "id": 1
}
BODY

If everything is fine the above command return the following output:

{
    "property": {
        "name": "My restaurant",
        "address": "My city, 50, My country",
        "type": "venue",
        "category": "restaurant",
        "stars": null,
        "rooms": null,
        "latitude": 33.0000,
        "longitude": 35.0000,
        "channels": {
            "tripadvisor": [
              "https://www.tripadvisor.com/trip/myrestaurant"
            ]
        },
        "channels_info": {
            "tripadvisor": [
              {
                "crawling":1539851952
              }
            ]
        },
        "location": {
            "l0": "Location 0",
            "l1": "Location 1",
            "l2": "Location 2",
            "l3": "Location 3",
            "l4": "Location 4",
            "l5": "Location 5",
            "town": "Town",
            "street": "Street",
            "street_number": "Street number",
            "street_name": "Street name",
            "zip": "Zip code"
        }
    },
    "competitors": {
        "c:1:1": {
            "name": "My competitor 1",
            "address": "My city 2, My country2",
            "type": "venue",
            "category": "restaurant",
            "stars": null,
            "rooms": null,
            "latitude": 33.5000,
            "longitude": 35.5000,
            "location": {
                "l0": "Location 0",
                "l1": "Location 1",
                "l2": "Location 2",
                "l3": "Location 3",
                "l4": "Location 4",
                "l5": "Location 5",
                "town": "Town",
                "street": "Street",
                "street_number": "Street number",
                "street_name": "Street name",
                "zip": "Zip code"
            }
        },
        "c:1:2": {
            "name": "My competitor 2",
            "address": "My city 3, 54567 ,My country2",
            "type": "venue",
            "category": "restaurant",
            "stars": null,
            "rooms": null,
            "latitude": null,
            "longitude": null,            
            "location": {
                "l0": "Location 0",
                "l1": "Location 1",
                "l2": "Location 2",
                "l3": "Location 3",
                "l4": "Location 4",
                "l5": "Location 5",
                "town": "Town",
                "street": "Street",
                "street_number": "Street number",
                "street_name": "Street name",
                "zip": "Zip code"
            }
        },
         "c:1:3": {
             "name": "My competitor 3",
             "address": null,
             "type": "venue",
             "category": "restaurant",
             "stars": null,
             "rooms": null,
             "latitude": null,
             "longitude": null,             
             "location": {
                 "l0": "Location 0",
                 "l1": "Location 1",
                 "l2": "Location 2",
                 "l3": "Location 3",
                 "l4": "Location 4",
                 "l5": "Location 5",
                 "town": "Town",
                 "street": "Street",
                 "street_number": "Street number",
                 "street_name": "Street name",
                 "zip": "Zip code"
             }
         }
    }
}

This API allows to get the information of a property and its competitor(s). The property must be connected to an active license. The output contains information such as: name, address, type, category, stars, rooms, latitude, longitude and, for the property, the channels array and channels_info array. Every field can be nullable except of name, type and category.

Channels Info

If valorized the channels_info array will contain information about the relative channel. The only information available is the crawling unix timestamp.

HTTPS Request

POST <TABASEURL>/propertyInfo

Parameters

Param	Type	Required	Description
id	int	yes	Property id.

Billing

This API call belongs to property license handling.

Licences

curl '<TABASEURL>/licences' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json'

If everything is fine the above command returns:

{
    "licences": [
        {
            "id": 1234567890,
            "billable": true,
            "started_at": 1508928768
        }
    ]
}

This API returns all the enabled licences for a specific partner. For each licence the API returns wether the property license is already billable, the starting date of the license and the property associated to that license.

HTTPS Request

GET <TABASEURL>/licences

Contents Statistics

This API retrieves statistic data about the contents of a property. This API allows to compute different kind of statistics, based on the filters combinations detailed below.

The Contents Statistics API endpoint is the following:

POST <TABASEURL>/contentsData

Parameters

curl '<TABASEURL>/contentsData' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
    "filters": {
        "branches": ["reviews"],
        "from": 1493157600,
        "to": 1493244000,
        "monitor_ids": [1],
        "compute": ["count", "sentiment"],
        "orderBy": "date"
    }
}
BODY

If everything is fine the above command returns:

{
  "count": 41,
  "sentiment": 92.3,
  "_timestamps": [ ... ],
  "_aggregation": { ... }
}

Input Parameters

This callname accepts the following input parameters.

Param	Type	Required	Description
branches	array	no	All contents will be retrieved if not specified. Possible values are: reviews for contents from review networks; tagged_posts for user contents from social networks; posts for proprietary contents from social networks.
orderBy	string	yes	Specify in which order you want to retrieve contentsID, choose one of the following: date, influence, sentiment.
monitor_ids	array	yes	An array of property or competitors IDs.
networks	array	no	An array of networks, if it is an empty array then all networks will be considered.
from	int	yes	"From" date timestamp in seconds, the oldest date.
to	int	yes	"To" date timestamp in seconds, the newest date.
keywords	array	no	An array of string terms. If specified it will act as filter for the contents based on the chosen keyword_strategy.
keyword_strategy	string	no	The term search strategy. It can be AND or OR. If no strategy is specified the default value will be AND. With the AND strategy only the contents that contain all the searched terms will be retrieved. With the OR strategy the contents with at least one of the specified keywords will be retrieved.
compute	array	no	You can put in this field multiple compute keys. The supported compute keys are documented in compute section.
groupBy	string	no	These parameter is needed to optimize the computation, for more details see optimization section.
common parameters	...	...	See this section for details.

Output Parameters

This callname always returns the following output parameters.

Param	Type	Description
_timestamp	array	Contains all the timestamps the computation has been made with. In the case the output contains historical series, then this array indicates the timestamps of the series.
_aggregation	array	See section Aggregations.

Compute parameters

curl '<TABASEURL>/contentsData' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
    "filters": {
        ...
        <common params*>
        ...
        "from": 1493157600,
        "to": 1493244000,
        "monitor_ids": [1],
        "compute": ["contentPositivitySeries", "contentsID", "count", "countReplies", "dishes", "sentiment", "sentimentSerie", "unanswerCounter"]
    }
}
BODY

If everything is fine the above command returns:

{
  "answerPercentage": 45.2,
  "contentPositivitySeries": {
    "neg" : [ 0, 9, ... ],
    "nil" : [ 4, 3, ... ],
    "pos" : [ 1, 2, ... ]
  },
  "contentsID": [ ... ],
  "count": 10,
  "countReplies": 10,
  "countOpinions": {
    "pos": 10,
    "neg": 7
  },
  "dishes": {
    "appetizer" : 1,
    "fois gras" : 4,
    ...
  },
  "sentiment": 80.12,
  "sentimentSerie": [ 79.83, 80.12, ... ],
  "trends": {
    "bar" : {
      "p": 10,
      "n": 3,
      "cp": 7,
      "cn": 1
    },
    ...
  },
  "unanswerCounter": 2,
  "_timestamps": [ ... ],
  "_aggregations": { ... }
}

An example of the body is on the right, the compute parameter is used to specify which output data you need. Below there is the list of all the possible values that can be used into the compute array. There is no limitation on the number of compute values that can be requested with a single API call, please consider that the more they are the longer it takes to response.

Compute values

Compute	Return Type	Description
answerPercentage	number	Contains the response rate, computed excluding the reviews that are not respondable.
count	number	Total number of contents.
countReplies	number	Total number of contents with replies.
countOpinions	object	Contains the following fields: pos number of positive opinions and neg number of negative opinions.
contentsID	array	Contains all the contents ids that can be used in the Contents List callname.
contentPositivitySeries	object	Contains the following time series: pos contents with positive sentiment, neg contents with negative sentiment, nil contents without sentiment.
dishes	object	Number of mentions for each dish. Dishes are indicated as keys, mentions as values.
sentiment	number	Global sentiment.
sentimentSerie	array	Contains the sentiment time serie.
trends	object	Contains an object with trends data for each argument. Arguments are indicated as keys, trend data is an object with the following keys: p (or n) number of positive (or negative) mentions, cp (or cn) number of contents in which the argument is positively (or negatively) mentioned.
unanswerCounter	number	Number of unanswered contents.

Aggregations

curl '<TABASEURL>/contentsData' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
    "filters": {
        ...
        <common params*>
        ...
        "from": 1493157600,
        "to": 1493244000,
        "monitor_ids": [1],
        "compute": ["aggregation.sentimentSerie"],
        "aggregationPeriod": "week"
    }
}
BODY

If everything is fine the above command returns:

{
  "aggregation.answerPercentage": [ 40.2, 31, 67.22 ],
  "aggregation.contentPositivity": {
    "neg" : [ 1, 0, 1 ],
    "nil" : [ 0, 0, 3 ],
    "pos" : [ 1, 1, 0 ]
  },
  "aggregation.count": [ 2, 1, 4 ],
  "aggregation.countReplies": [ 0, 1, 2 ],
  "aggregation.countOpinions": {
    "pos": [ 3, 5, 1 ],
    "neg": [ 1, 0, 2 ]
  },
  "aggregation.sentimentSerie": [ 95.68, 83.75, 87.24 ],
  "_timestamps": [ 1482793200, 1482879600, 1482966000, ... ],
  "_aggregation": {
    "period": "week",
    "names": [ "2016-W52", "2017-W01", "2017-W02" ],
    "timestamps": [ 1482706800, 1483311600, 1483916400 ]
  }
}

Aggregations are special kinds of compute, in which the output is aggregated into days, weeks, months or quarters according to the input parameter aggregationPeriod. The output will be aggregated into the selected period as shown in the example.

Aggregation period

The aggregation period can be specified into the aggregationPeriod input field and can accept the following values:

Value	Description
day	This is the default value, output will be aggregated by days.
week	The output will be aggregated by weeks, according to ISO-8601 standard (e.g. 2017-W02).
month	The output will be aggregated by months.
quarter	The output will be aggregated by quarters (e.g. 2017-Q1).

Aggregation parameters

Aggregations can be specified inside compute input field, as they are special kinds of compute.

Compute	Return Type	Description
aggregation.answerPercentage	array	Contains the response rate time serie, computed excluding the reviews that are not respondable.
aggregation.contentPositivity	object	Contains the following time series: pos contents with positive sentiment, neg contents with negative sentiment, nil contents without sentiment.
aggregation.count	array	Contains the contents counter time serie.
aggregation.countOpinions	object	Contains the following time series: pos containing positive opinions and neg containing negative opinions.
aggregation.countReplies	array	Contains the contents with replies counter time serie.
aggregation.sentimentSerie	array	Contains the sentiment time serie.

Note: each time serie in this section is computed in according to the aggregation period, this means it contains the same number of elements of the output fields names, timestamps inside the _aggregation object.

Output parameters

In the output parameters there is the _aggregation object that contains information about the aggregation that has been done. It contains the following:

Key	Type	Description
period	string	This is the aggregation period, can be day, week, month or quarter.
names	array	Contains all the period identifiers (e.g. 2017-W01 for weeks).
timestamps	array	Contains all the timestamps corresponding to the period start.

Note: The first period start timestamp can be lower than the requested timestamp range as specified into the from and to input parameters.

Optimizations

curl '<TABASEURL>/contentsData' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
    "filters": {
        ...
        <common params*>
        ...
        "branches": ["reviews"],
        "networks": ["booking", "tripadvisor"],
        "clusters": [ 102, 104 ],
        "from": 1493157600,
        "to": 1493244000,
        "monitor_ids": [1, 107],
        "compute": ["count", "sentiment"],
        "groupBy": GROUPBY-VALUE
    }
}
BODY

If everything is fine the above command returns:

{
  "groups": {
    "GROUPBY-KEY-1": {
      "count": 41,
      "sentiment": 92.3,
    },
    "GROUPBY-KEY-2": {
      "count": 41,
      "sentiment": 92.3,
    }
  }
  "_timestamps": [ ... ]
}

To optimize and speed up the Contents Statistics retrieval in case you need to request data for multiple properties/competitors, you can put all their ids into the monitorIDs input field (this feature is not available for single property management API). By default this callname returns the overall statistics.

The example on the right contains the following 3 placeholders:

• GROUPBY-VALUE the groupBy criteria, specified in the input parameters
• GROUPBY-KEY-1 the first group key, returned in the output response
• GROUPBY-KEY-2 the second group key, returned in the output response

Below there are the different use cases with examples about these placeholders.

Multiple Property/Competitors

If you add the groupBy parameter to the Contents Statistics callname with value monitor, then it will return all the statistics for each input property/competitor as shown on the right. The groups object contains the response for each property/competitor indexed by their keys.

Placeholder	Value	Description
GROUPBY-VALUE	monitor	Requests to group results by property/competitor.
GROUPBY-KEY-1	1	Contains the results about property with id 1.
GROUPBY-KEY-2	107	Contains the results about property with id 107.

Group analysis by user country

If you add the groupBy parameter to the Contents Statistics callname with value country, then it will return all the statistics grouped by user country as shown on the right. The groups object contains the response for each country.

Placeholder	Value	Description
GROUPBY-VALUE	country	Requests to group results by network.
GROUPBY-KEY-1	us	Contains the results about US users.
GROUPBY-KEY-2	it	Contains the results about Italian users.

Note: It is possible that this API callname returns n/a keys, which means that the information is not available from the source. For a complete list of available countries please refer to ISO 3166-1 alpha-2 standard.

Group analysis by language

If you add the groupBy parameter to the Contents Statistics callname with value language, then it will return all the statistics grouped by user language as shown on the right. The groups object contains the response for each language.

Placeholder	Value	Description
GROUPBY-VALUE	language	Requests to group results by network.
GROUPBY-KEY-1	en	Contains the results about English users.
GROUPBY-KEY-2	it	Contains the results about Italian users.

Note: It is possible that this API callname returns n/a keys, which means that the information is not available from the source. For a complete list of available user languages please refer to ISO 639-1 standard.

Group analysis by network

If you add the groupBy parameter to the Contents Statistics callname with value network, then it will return all the statistics grouped by network as shown on the right. The groups object contains the response for each network.

Placeholder	Value	Description
GROUPBY-VALUE	network	Requests to group results by network.
GROUPBY-KEY-1	booking	Contains the results about network booking.
GROUPBY-KEY-2	tripadvisor	Contains the results about network tripadvisor.

Group analysis by sentiment clusters

If you add the groupBy parameter to the Contents Statistics callname with value cluster, then it will return all the statistics grouped by sentiment cluster as shown on the right. The groups object contains the response for each sentiment cluster.

Placeholder	Value	Description
GROUPBY-VALUE	cluster	Requests to group results by network.
GROUPBY-KEY-1	102	Contains the results about sentiment cluster 102 (Rooms).
GROUPBY-KEY-2	104	Contains the results about sentiment cluster 104 (Services).

Group analysis by user types (e.g. Family, Business, ...)

If you add the groupBy parameter to the Contents Statistics callname with value userTypes, then it will return all the statistics grouped by user type as shown on the right. The groups object contains the response for each network.

Placeholder	Value	Description
GROUPBY-VALUE	userTypes	Requests to group results by network.
GROUPBY-KEY-1	f	Contains the results about user type f (family).
GROUPBY-KEY-2	b	Contains the results about user type b (business).

Note: It is possible that this API callname returns n/a keys, which means that the information is not available from the source. For a complete list of available user types please refer to configurations.

Ratings

Guest Ratings

curl '<TABASEURL>/guestRatings' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
    "filters": {
        "from": 1493157600,
        "to": 1493244000,
        "monitor_ids": [1],
        "networks": ["<network>"]
    }
}
BODY

If everything is fine the above command returns a list of ratings with their associated score indexed by the _timestamps value:

*single network*
{
    "gen": {
        "scores": [4.5, 4.5]        
    },
    "pos": {
        "scores": [4.5, 4.5]    
    },
    "roo": {
        "scores": [4.5, 4.5]        
    },
    "sle": {
        "scores": [4.5, 4.5]        
    },
    "ser": {
        "scores": [4.5, 4.5]        
    },
    "cle": {
        "scores": [4.5, 4.5]
    },
    "pri": {
        "scores": [4, 4]
    },
    "coo": {
        "scores": [null, 3]
    },
    "seo": {
        "scores": [null, null]
    },
    "qpr": {
        "scores": [null, null]
    },
    "atm": {
        "scores": [null, null]
    },
    "leg": {
        "scores": [null, null]
    },
    "cus": {
        "scores": [null, null]  
    },
    "che": {
        "scores": [null, null]
    },
    "ent": {
        "scores": [5, null]
    },
    "sea": {
        "scores": [null, null]          
    },
    "_timestamps": [1493157600, 1493244000]
}

*multiple network*
{
    "networks": {
        "google": {
            "gen": {
                "scores": [
                    3.8                    
                ]
            }
        },
        "facebook": {
            "gen": {
                "scores": [
                    3.7                   
                ]
            }
        }
    },
    "_timestamps": [
        1511132400,
    ]
}

This API allows to retrieve the ratings of a specified network in a specified interval of time. The complete list of the ratings and their description can be found here. If more than one network is specified the result will be grouped by the corresponding network.

HTTPS Request

POST <TABASEURL>/guestRatings

Parameters

Param	Type	Required	Description
monitor_ids	array	yes	An array of property or competitors IDs.
from	int	yes	"From" date timestamp in seconds.
to	int	yes	"To" date timestamp in seconds.
networks	array	yes	An array of networks.

Rankings

Rankings

curl '<TABASEURL>/channelsRanking' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
    "filters": {
        "from": 1493157600,
        "to": 1493244000,
        "monitor_ids": [1],
        "networks": ["<network>"]
    }
}
BODY

If everything is fine the above command returns a list of rankings, with their associated ranking over the total of the properties, in the locality specified in the location field indexed by the _timestamps value:

{
    "<network>": {
        "ranking": [1,1],
        "total": [3,3],
        "type": "Hotels",
        "location": "Florence"
    },
    "_timestamps": [1493157600,1493244000]
}

This API allows to retrieve the rankings of a specified network in a specified interval of time.

HTTPS Request

POST <TABASEURL>/channelsRanking

Parameters

Param	Type	Required	Description
monitor_ids	array	yes	An array of property or competitors IDs.
from	int	yes	"From" date timestamp in seconds.
to	int	yes	"To" date timestamp in seconds.
networks	array	yes	An array of networks. You can specify only one network per call.

TAI Scores

Global TAI Score

curl '<TABASEURL>/taiScores' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "filters": {
    "monitor_ids": [...],
    "from": <timestamp>,
    "to": <timestamp>
  }
}
BODY

If everything is fine the above command returns:

{
     "tai": [ 88.7, 88.6, ... ],
     "_timestamps": [ ... ]
}

This API allows to retrieve the global TAI scores in a specified interval of time for the input property/competitor monitorIDs.

The output is shown on the left, it contains an array of timestamps (_timestamps) and an array of global TAI scores (tai).

HTTPS Request

POST <TABASEURL>/taiScores

Parameters

Param	Type	Required	Description
monitor_ids	array	yes	An array of property or competitors IDs.
from	int	yes	"From" date timestamp in seconds.
to	int	yes	"To" date timestamp in seconds.
groupBy	string	no	See Optimization section.

Optimizations

curl '<TABASEURL>/taiScores' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "filters": {
    "monitorIDs": [ 1, 2 ],
    "from": <timestamp>,
    "to": <timestamp>,
    "groupBy": "monitor"
  }
}
BODY

If everything is fine the above command returns:

{
     "groups": {
        1: {
          "tai": [ 88.7, 88.6, ... ]
        },
        2: {
          "tai": [ 71.2, 71.9, ... ]
        }
     },
     "_timestamps": [ ... ]
}

To optimize and speed up the TAI scores retrieval in case you need to request data for multiple properties/competitors, you can put all their ids into the monitorIDs input field. By default this callname returns the overall TAI score.

If you add the groupBy parameter to the Global TAI Scores callname with value monitor, then it will return all the TAI score for each input property/competitor as shown on the right. The groups object contains the response for each property/competitor indexed by their keys.

Note: This feature is not available for single property management API.

Prices

Get

curl '<TABASEURL>/prices' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
  "filters": {
    "monitor_ids": [...],
    "from": <timestamp>,
    "to": <timestamp>
  }
}
BODY

If everything is fine the above command returns:

{
     "prices": [
          {
               "date_checkin": 1550530800,
               "date_detection": 1550158721,
               "avail": 2,
               "minstay": 1,
               "price": 108,
               "refundable": true,
               "description": "Superior Room"
          },
          ...
     ]
}

This API allows the user to retrieve the price detections in a specified interval of time for the input of property/competitor monitorIDs.

The output is shown on the left. Inside the array prices, there are the last price detections available for the requested property/competitor. Each object inside the array contains the following fields:

• date_checkin the timestamp of the check-in day
• stay the length of stay in days
• date_detection the timestamp in which the prices were detected (e.g. the time in which the customer is looking for prices)
• avail the number of rooms available
• price the price of the room in EUR
• refundable a boolean indicating if the offer is refundable or not
• description the description of the room

For example, for the check-in day 2019-02-19 CET, there are 2 refundable Superior Rooms with a price of 108 EUR and a minimum stay of 1 day, detected on 2019-02-14 04:38:41pm CET.

Note: in case the date_detection field is null, there are no prices detected for the specified date_checkin. Consequently all the other fields are null.

HTTPS Request

POST <TABASEURL>/prices

Parameters

Param	Type	Required	Description
monitor_ids	array	yes	An array of property or competitors IDs.
from	int	yes	"From" date timestamp in seconds.
to	int	yes	"To" date timestamp in seconds.

Configurations

The configurations parameters are required in order to do the query call on a property.

Get

curl '<TABASEURL>/configurations' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json'

If everything is fine the above command returns:

{
  "networks": [
    "tripadvisor",
    "booking",
    "holidaycheck",
    "zoover",
    "yelp",
    "agoda",
    "airbnb",
    "foursquare",
    "expedia",
    "venere",
    "hotels",
    "ebookers",
    "orbitz",
    "homeaway",
    "homelidays",
    "hotwire",
    "travelocity",
    "wotif",
    "2spaghi",
    "thefork",
    "opentable",
    "bookatable",
    "viator",
    "musement",
    "getyourguide",
    "vayable",
    "hostelworld",
    "budgetplaces",
    "hostelbookers",
    "hostelsclub",
    "hotelclub",
    "cheaptickets",
    "mrjet",
    "wimdu",
    "hrs",
    "justeat",
    "laterooms",
    "misiedo",
    "quandoo",
    "zomato",
    "qualitando",
    "facebook",
    "twitter",
    "instagram",
    "pinterest",
    "google",
    "youtube",
    "vimeo",
    "tripadvisorforum",
    "search",
    "website"
  ],
  "types": {
    "hotel": {
      "categories": [
        "hotel",
        "resort",
        "motel",
        "residence",
        "historic_residence"
      ]
    },
    "country_house": {
      "categories": [
        "b&b",
        "farm_house",
        "camping",
        "holiday_village",
        "hostel",
        "house_flat",
        "room_rental",
        "mountain_lodge",
        "lodge"
      ]
    },
    "venue": {
      "categories": [
        "restaurant",
        "pizzeria",
        "tavern",
        "pub",
        "bar",
        "icecream_shop",
        "bakery",
        "sandwich_shop",
        "beach"
      ]
    }
  },
  "user_types": [
    "e",
    "o",
    "f",
    "c",
    "g",
    "a",
    "b",
    "r"
  ],
  "languages": [
    "af",
    "am",
    "an",
    "ar",
    "as",
    "az",
    "be",
    "bg",
    "bn",
    "br",
    "bs",
    "ca",
    "cs",
    "cy",
    "da",
    "de",
    "dz",
    "el",
    "en",
    "eo",
    "es",
    "et",
    "eu",
    "fa",
    "fi",
    "fo",
    "fr",
    "ga",
    "gl",
    "gu",
    "he",
    "hi",
    "hr",
    "ht",
    "hu",
    "hy",
    "id",
    "is",
    "it",
    "ja",
    "jv",
    "ka",
    "kk",
    "km",
    "kn",
    "ko",
    "ku",
    "ky",
    "la",
    "lb",
    "lo",
    "lt",
    "lv",
    "mg",
    "mk",
    "ml",
    "mn",
    "mr",
    "ms",
    "mt",
    "nb",
    "ne",
    "nl",
    "nn",
    "no",
    "oc",
    "or",
    "pa",
    "pl",
    "ps",
    "pt",
    "qu",
    "ro",
    "ru",
    "rw",
    "se",
    "si",
    "sk",
    "sl",
    "sq",
    "sr",
    "sv",
    "sw",
    "ta",
    "te",
    "th",
    "tl",
    "tr",
    "ug",
    "uk",
    "ur",
    "vi",
    "vo",
    "wa",
    "xh",
    "zh",
    "zu"
  ],
  "countries": [
    "ax",
    "af",
    "al",
    "dz",
    "as",
    "ad",
    "ao",
    "ai",
    "aq",
    "ag",
    "ar",
    "am",
    "aw",
    "au",
    "at",
    "az",
    "bs",
    "bh",
    "bd",
    "bb",
    "by",
    "be",
    "bz",
    "bj",
    "bm",
    "bt",
    "bo",
    "ba",
    "bw",
    "bv",
    "br",
    "io",
    "bn",
    "bg",
    "bf",
    "bi",
    "kh",
    "cm",
    "ca",
    "cv",
    "ky",
    "cf",
    "td",
    "cl",
    "cn",
    "cx",
    "cc",
    "co",
    "km",
    "cd",
    "cg",
    "ck",
    "cr",
    "ci",
    "hr",
    "cu",
    "cy",
    "cz",
    "dk",
    "dj",
    "dm",
    "do",
    "ec",
    "eg",
    "sv",
    "gq",
    "er",
    "ee",
    "et",
    "fk",
    "fo",
    "fj",
    "fi",
    "fr",
    "gf",
    "pf",
    "tf",
    "ga",
    "gm",
    "ge",
    "de",
    "gh",
    "gi",
    "gr",
    "gl",
    "gd",
    "gp",
    "gu",
    "gt",
    "gn",
    "gw",
    "gy",
    "ht",
    "hm",
    "hn",
    "hk",
    "hu",
    "is",
    "in",
    "id",
    "ir",
    "iq",
    "ie",
    "il",
    "it",
    "jm",
    "jp",
    "jo",
    "kz",
    "ke",
    "ki",
    "kp",
    "kr",
    "kv",
    "kw",
    "kg",
    "la",
    "lv",
    "lb",
    "ls",
    "lr",
    "ly",
    "li",
    "lt",
    "lu",
    "mo",
    "mk",
    "mg",
    "mw",
    "my",
    "mv",
    "ml",
    "mt",
    "mh",
    "mq",
    "mr",
    "mu",
    "yt",
    "mx",
    "fm",
    "md",
    "mc",
    "mn",
    "ms",
    "ma",
    "mz",
    "mm",
    "na",
    "nr",
    "np",
    "nl",
    "an",
    "nc",
    "nz",
    "ni",
    "ne",
    "ng",
    "nu",
    "nf",
    "mp",
    "no",
    "om",
    "pk",
    "pw",
    "ps",
    "pa",
    "pg",
    "py",
    "pe",
    "ph",
    "pn",
    "pl",
    "pt",
    "pr",
    "qa",
    "re",
    "ro",
    "ru",
    "rw",
    "sh",
    "kn",
    "lc",
    "pm",
    "vc",
    "ws",
    "sm",
    "st",
    "sa",
    "sn",
    "cs",
    "sc",
    "sl",
    "sg",
    "sk",
    "si",
    "sb",
    "so",
    "za",
    "gs",
    "es",
    "lk",
    "sd",
    "sr",
    "sj",
    "sz",
    "se",
    "ch",
    "sy",
    "tw",
    "tj",
    "tz",
    "th",
    "tl",
    "tg",
    "tk",
    "to",
    "tt",
    "tn",
    "tr",
    "tm",
    "tc",
    "tv",
    "ug",
    "ua",
    "ae",
    "gb",
    "us",
    "um",
    "uy",
    "uz",
    "vu",
    "va",
    "ve",
    "vn",
    "vg",
    "vi",
    "wf",
    "eh",
    "ye",
    "zm",
    "zw"
  ],
  "clusters": {
    "hotel": {
      "101": {
        "label": "sentiment_cluster_hotel_general",
        "icon": "fa fa-building-o",
        "subclusters": [
          "struttura - arredi",
          "struttura - fisica",
          "struttura - luoghi interni",
          "struttura - luoghi esterni",
          "struttura - ambientazione",
          "*generale*",
          "hotel"
        ]
      },
      "102": {
        "label": "sentiment_cluster_hotel_rooms",
        "icon": "fa fa-key",
        "subclusters": [
          "struttura - camere",
          "camera - arredi",
          "camera - bagno",
          "camera - struttura",
          "camera - letto",
          "letto - struttura",
          "letto - accessori",
          "bagno - struttura",
          "bagno - accessori",
          "bagno - servizi"
        ]
      },
      "103": {
        "label": "sentiment_cluster_hotel_position",
        "icon": "fa fa-map-marker"
      },
      "104": {
        "label": "sentiment_cluster_hotel_services",
        "icon": "fa fa-puzzle-piece",
        "subclusters": [
          "struttura - servizi",
          "struttura - servizi ricreativi",
          "camera - servizi intrattenimento",
          "camera - servizi di comunicazione",
          "camera - servizi di climatizzazione"
        ]
      },
      "105": {
        "label": "sentiment_cluster_hotel_food",
        "icon": "fa fa-cutlery",
        "subclusters": [
          "struttura - ristorazione",
          "ristorazione - tipologia",
          "ristorazione - qualita",
          "ristorazione - struttura"
        ]
      },
      "106": {
        "label": "sentiment_cluster_hotel_hospitality",
        "icon": "fa fa-gift",
        "subclusters": [
          "struttura - personale",
          "ristorazione - personale"
        ]
      },
      "107": {
        "label": "sentiment_cluster_hotel_cleanliness",
        "icon": "fa fa-tint"
      },
      "108": {
        "label": "sentiment_cluster_hotel_costs",
        "icon": "fa fa-money"
      },
      "109": {
        "label": "sentiment_cluster_hotel_internet",
        "icon": "fa fa-wifi"
      }
    },
    "country_house": {
      "101": {
        "label": "sentiment_cluster_country_house_general",
        "icon": "fa fa-building-o",
        "subclusters": [
          "struttura - arredi",
          "struttura - fisica",
          "struttura - luoghi interni",
          "struttura - luoghi esterni",
          "struttura - ambientazione",
          "camera - arredi"
        ]
      },
      "102": {
        "label": "sentiment_cluster_country_house_rooms",
        "icon": "fa fa-key",
        "subclusters": [
          "struttura - camere",
          "camera - arredi",
          "camera - bagno",
          "camera - struttura",
          "camera - letto",
          "letto - struttura",
          "letto - accessori",
          "bagno - struttura",
          "bagno - accessori",
          "bagno - servizi"
        ]
      },
      "103": {
        "label": "sentiment_cluster_country_house_position",
        "icon": "fa fa-map-marker"
      },
      "104": {
        "label": "sentiment_cluster_country_house_services",
        "icon": "fa fa-puzzle-piece",
        "subclusters": [
          "struttura - servizi",
          "struttura - servizi ricreativi",
          "camera - servizi intrattenimento",
          "camera - servizi di comunicazione",
          "camera - servizi di climatizzazione"
        ]
      },
      "105": {
        "label": "sentiment_cluster_country_house_food",
        "icon": "fa fa-cutlery",
        "subclusters": [
          "struttura - ristorazione",
          "ristorazione - tipologia",
          "ristorazione - qualita",
          "ristorazione - struttura"
        ]
      },
      "106": {
        "label": "sentiment_cluster_country_house_hospitality",
        "icon": "fa fa-gift",
        "subclusters": [
          "struttura - personale",
          "ristorazione - personale"
        ]
      },
      "107": {
        "label": "sentiment_cluster_country_house_cleanliness",
        "icon": "fa fa-tint"
      },
      "108": {
        "label": "sentiment_cluster_country_house_costs",
        "icon": "fa fa-money"
      },
      "109": {
        "label": "sentiment_cluster_country_house_internet",
        "icon": "fa fa-wifi"
      }
    },
    "venue": {
      "301": {
        "label": "sentiment_cluster_venue_general",
        "icon": "fa fa-building-o",
        "subclusters": [
          "*generale*",
          "struttura",
          "struttura - accessori"
        ]
      },
      "302": {
        "label": "sentiment_cluster_venue_food_quality",
        "icon": "fa fa-cutlery",
        "subclusters": [
          "aperitivo",
          "antipasti",
          "primi - piatti",
          "secondi - piatti",
          "contorni - verdure",
          "prodotti - bar",
          "dolci",
          "frutta",
          "altri - alimenti",
          "bevande",
          "brand - citati"
        ]
      },
      "303": {
        "label": "sentiment_cluster_venue_position",
        "icon": "fa fa-map-marker"
      },
      "304": {
        "label": "sentiment_cluster_venue_services",
        "icon": "fa fa-puzzle-piece",
        "subclusters": [
          "struttura - bagno",
          "struttura - servizi ricreativi"
        ]
      },
      "305": {
        "label": "sentiment_cluster_venue_beauty",
        "icon": "fa fa-eye",
        "subclusters": [
          "struttura - elementi",
          "struttura - arredi",
          "struttura - ambientazione"
        ]
      },
      "306": {
        "label": "sentiment_cluster_venue_hospitality",
        "icon": "fa fa-gift"
      },
      "307": {
        "label": "sentiment_cluster_venue_cleanliness",
        "icon": "fa fa-tint"
      },
      "308": {
        "label": "sentiment_cluster_venue_costs",
        "icon": "fa fa-money"
      },
      "309": {
        "label": "sentiment_cluster_venue_internet",
        "icon": "fa fa-wifi"
      }
    }
  }
}

This API returns all the configuration fields needed in order to query the data for a property. See the parameters section for more information.

HTTPS Request

GET <TABASEURL>/configurations

Clusters

curl '<TABASEURL>/clustersInfo' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
    "filters": {
        "monitor_ids": [1234567890]
    }
}
BODY

If everything is fine the above command returns:

{
    "clusters": {
        "101": "General",
        "102": "Rooms",
        "103": "Position",
        "104": "Services",
        "105": "Food",
        "106": "Hospitality",
        "107": "Cleanliness",
        "108": "Costs",
        "109": "Internet"
    }
}

This API returns the cluster info for a specific property. It returns the clusters ids with their corresponding label. See the parameters section for more information.

HTTPS Request

POST <TABASEURL>/clustersInfo

Parameters

Param	Type	Required	Description
monitor_ids	array	yes	An array of properties id. Only one value must be specified.

Channels

curl '<TABASEURL>/channelsInfo' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
    "filters": {
        "monitor_ids": [1234567890]
    }
}
BODY

If everything is fine the above command returns:

{
    "channels": {
        "tripadvisor": "TripAdvisor",
        "booking": "Booking.com",        
        "expedia": "Expedia",
        "facebook": "Facebook",
        "twitter": "Twitter",
        "instagram": "Instagram",
        "pinterest": "Pinterest",
        "google": "Google",        
        "youtube": "Youtube"        
    }
}

This API returns the channels info for a specific property. It returns the channels key with their corresponding name. See the parameters section for more information.

HTTPS Request

POST <TABASEURL>/channelsInfo

Parameters

Param	Type	Required	Description
monitor_ids	array	yes	An array of properties id. Only one value must be specified.

Guests

curl '<TABASEURL>/typeOfGuests' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json'

If everything is fine the above command returns:

{
    "e": "All",
    "o": "Other",
    "f": "Families",
    "c": "Couples",
    "g": "Friends/Groups",
    "a": "Solo travelers",
    "b": "Business trips",
    "r": "Romantic getaway"
}

This API returns the label for the type of guests. It returns the guest type with their corresponding name. See the parameters section for more information.

HTTPS Request

GET <TABASEURL>/typeOfGuests

Countries

curl '<TABASEURL>/availableCountries' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json'

If everything is fine the above command returns:

{
    "ax": "Aaland Islands",
    "af": "Afghanistan",
    "al": "Albania",
    "dz": "Algeria",
    "as": "American Samoa",
    "ad": "Andorra",
    "ao": "Angola",
    "ai": "Anguilla",
    "aq": "Antarctica",
    "ag": "Antigua And Barbuda",
    "ar": "Argentina",
    "am": "Armenia",
    "aw": "Aruba",
    "au": "Australia",
    "at": "Austria",
    "az": "Azerbaijan",
    "bs": "Bahamas",
    "bh": "Bahrain",
    "bd": "Bangladesh",
    "bb": "Barbados",
    "by": "Belarus",
    "be": "Belgium",
    "bz": "Belize",
    "bj": "Benin",
    "bm": "Bermuda",
    "bt": "Bhutan",
    "bo": "Bolivia",
    "ba": "Bosnia And Herzegowina",
    "bw": "Botswana",
    "br": "Brazil",
    "bn": "Brunei Darussalam",
    "bg": "Bulgaria",
    "bf": "Burkina Faso",
    "bi": "Burundi",
    "kh": "Cambodia",
    "cm": "Cameroon",
    "ca": "Canada",
    "cv": "Cape Verde",
    "ky": "Cayman Islands",
    "cf": "Central African Republic",
    "td": "Chad",
    "cl": "Chile",
    "cn": "China",
    "cx": "Christmas Island",
    "cc": "Cocos (Keeling) Islands",
    "co": "Colombia",
    "km": "Comoros",
    "cd": "Congo, Democratic Republic Of",
    "cg": "Congo, Republic Of",
    "ck": "Cook Islands",
    "cr": "Costa Rica",
    "ci": "Cote D'ivoire",
    "hr": "Croatia",
    "cu": "Cuba",
    "cy": "Cyprus",
    "cz": "Czech Republic",
    "dk": "Denmark",
    "dj": "Djibouti",
    "dm": "Dominica",
    "do": "Dominican Republic",
    "ec": "Ecuador",
    "eg": "Egypt",
    "sv": "El Salvador",
    "gq": "Equatorial Guinea",
    "er": "Eritrea",
    "ee": "Estonia",
    "et": "Ethiopia",
    "fk": "Falkland Islands (Malvinas)",
    "fo": "Faroe Islands",
    "fj": "Fiji",
    "fi": "Finland",
    "fr": "France",
    "gf": "French Guiana",
    "pf": "French Polynesia",
    "tf": "French Southern Territories",
    "ga": "Gabon",
    "gm": "Gambia",
    "ge": "Georgia",
    "de": "Germany",
    "gh": "Ghana",
    "gi": "Gibraltar",
    "gr": "Greece",
    "gl": "Greenland",
    "gd": "Grenada",
    "gp": "Guadeloupe",
    "gu": "Guam",
    "gt": "Guatemala",
    "gn": "Guinea",
    "gw": "Guinea-bissau",
    "gy": "Guyana",
    "ht": "Haiti",
    "hn": "Honduras",
    "hk": "Hong Kong",
    "hu": "Hungary",
    "is": "Iceland",
    "in": "India",
    "id": "Indonesia",
    "ir": "Iran (Islamic Republic Of)",
    "iq": "Iraq",
    "ie": "Ireland",
    "il": "Israel",
    "it": "Italy",
    "jm": "Jamaica",
    "jp": "Japan",
    "jo": "Jordan",
    "kz": "Kazakhstan",
    "ke": "Kenya",
    "ki": "Kiribati",
    "kp": "Korea, Democratic People's Republic Of",
    "kr": "Korea, Republic Of",
    "kw": "Kuwait",
    "kg": "Kyrgyzstan",
    "la": "Lao People's Democratic Republic",
    "lv": "Latvia",
    "lb": "Lebanon",
    "ls": "Lesotho",
    "lr": "Liberia",
    "ly": "Libyan Arab Jamahiriya",
    "li": "Liechtenstein",
    "lt": "Lithuania",
    "lu": "Luxembourg",
    "mo": "Macau",
    "mk": "Macedonia, The Former Yugoslav Republic Of",
    "mg": "Madagascar",
    "mw": "Malawi",
    "my": "Malaysia",
    "mv": "Maldives",
    "ml": "Mali",
    "mt": "Malta",
    "mh": "Marshall Islands",
    "mq": "Martinique",
    "mr": "Mauritania",
    "mu": "Mauritius",
    "yt": "Mayotte",
    "mx": "Mexico",
    "fm": "Micronesia, Federated States Of",
    "md": "Moldova, Republic Of",
    "mc": "Monaco",
    "mn": "Mongolia",
    "ms": "Montserrat",
    "ma": "Morocco",
    "mz": "Mozambique",
    "mm": "Myanmar",
    "na": "Namibia",
    "nr": "Nauru",
    "np": "Nepal",
    "nl": "Netherlands",
    "nc": "New Caledonia",
    "nz": "New Zealand",
    "ni": "Nicaragua",
    "ne": "Niger",
    "ng": "Nigeria",
    "nu": "Niue",
    "nf": "Norfolk Island",
    "mp": "Northern Mariana Islands",
    "no": "Norway",
    "om": "Oman",
    "pk": "Pakistan",
    "pw": "Palau",
    "ps": "Palestinian Territory, Occupied",
    "pa": "Panama",
    "pg": "Papua New Guinea",
    "py": "Paraguay",
    "pe": "Peru",
    "ph": "Philippines",
    "pn": "Pitcairn",
    "pl": "Poland",
    "pt": "Portugal",
    "pr": "Puerto Rico",
    "qa": "Qatar",
    "re": "Reunion",
    "ro": "Romania",
    "ru": "Russian Federation",
    "rw": "Rwanda",
    "sh": "Saint Helena",
    "kn": "Saint Kitts And Nevis",
    "lc": "Saint Lucia",
    "pm": "Saint Pierre And Miquelon",
    "vc": "Saint Vincent And The Grenadines",
    "ws": "Samoa",
    "sm": "San Marino",
    "st": "Sao Tome And Principe",
    "sa": "Saudi Arabia",
    "sn": "Senegal",
    "sc": "Seychelles",
    "sl": "Sierra Leone",
    "sg": "Singapore",
    "sk": "Slovakia",
    "si": "Slovenia",
    "sb": "Solomon Islands",
    "so": "Somalia",
    "za": "South Africa",
    "gs": "South Georgia And The South Sandwich Islands",
    "es": "Spain",
    "lk": "Sri Lanka",
    "sd": "Sudan",
    "sr": "Suriname",
    "sj": "Svalbard And Jan Mayen Islands",
    "sz": "Swaziland",
    "se": "Sweden",
    "ch": "Switzerland",
    "sy": "Syrian Arab Republic",
    "tw": "Taiwan",
    "tj": "Tajikistan",
    "tz": "Tanzania, United Republic Of",
    "th": "Thailand",
    "tl": "Timor-leste",
    "tg": "Togo",
    "tk": "Tokelau",
    "to": "Tonga",
    "tt": "Trinidad And Tobago",
    "tn": "Tunisia",
    "tr": "Turkey",
    "tm": "Turkmenistan",
    "tc": "Turks And Caicos Islands",
    "tv": "Tuvalu",
    "ug": "Uganda",
    "ua": "Ukraine",
    "ae": "United Arab Emirates",
    "gb": "United Kingdom",
    "us": "United States",
    "uy": "Uruguay",
    "uz": "Uzbekistan",
    "vu": "Vanuatu",
    "va": "Vatican City State (Holy See)",
    "ve": "Venezuela",
    "vn": "Vietnam",
    "vg": "Virgin Islands (British)",
    "vi": "Virgin Islands (U.s.)",
    "wf": "Wallis And Futuna Islands",
    "eh": "Western Sahara",
    "ye": "Yemen",
    "zm": "Zambia",
    "zw": "Zimbabwe"
}

This API returns the label for the countries. It returns the country code with their corresponding name. See the parameters section for more information.

HTTPS Request

GET <TABASEURL>/availableCountries

Languages

curl '<TABASEURL>/availableLanguages' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json'

If everything is fine the above command returns:

{
    "af": "Afrikaans",
    "am": "Amharic",
    "an": "Aragonese",
    "ar": "Arabic",
    "as": "Assamese",
    "az": "Azerbaijani",
    "be": "Belarusian",
    "bg": "Bulgarian",
    "bn": "Bengali",
    "br": "Breton",
    "bs": "Bosnian",
    "ca": "Catalan",
    "cs": "Czech",
    "cy": "Welsh",
    "da": "Danish",
    "de": "German",
    "dz": "Dzongkha",
    "el": "Greek",
    "en": "English",
    "eo": "Esperanto",
    "es": "Spanish",
    "et": "Estonian",
    "eu": "Basque",
    "fa": "Persian",
    "fi": "Finnish",
    "fo": "Faroese",
    "fr": "French",
    "ga": "Irish",
    "gl": "Galician",
    "gu": "Gujarati",
    "he": "Hebrew",
    "hi": "Hindi",
    "hr": "Croatian",
    "ht": "Haitian",
    "hu": "Hungarian",
    "hy": "Armenian",
    "id": "Indonesian",
    "is": "Icelandic",
    "it": "Italian",
    "ja": "Japanese",
    "jv": "Javanese",
    "ka": "Georgian",
    "kk": "Kazakh",
    "km": "Khmer",
    "kn": "Kannada",
    "ko": "Korean",
    "ku": "Kurdish",
    "ky": "Kyrgyz",
    "la": "Latin",
    "lb": "Luxembourgish",
    "lo": "Lao",
    "lt": "Lithuanian",
    "lv": "Latvian",
    "mg": "Malagasy",
    "mk": "Macedonian",
    "ml": "Malayalam",
    "mn": "Mongolian",
    "mr": "Marathi",
    "ms": "Malay",
    "mt": "Maltese",
    "nb": "Norwegian Bokmål",
    "ne": "Nepali",
    "nl": "Dutch",
    "nn": "Norwegian Nynorsk",
    "no": "Norwegian",
    "oc": "Occitan",
    "or": "Oriya",
    "pa": "Punjabi",
    "pl": "Polish",
    "ps": "Pashto",
    "pt": "Portuguese",
    "qu": "Quechua",
    "ro": "Romanian",
    "ru": "Russian",
    "rw": "Kinyarwanda",
    "se": "Northern Sami",
    "si": "Sinhala",
    "sk": "Slovak",
    "sl": "Slovenian",
    "sq": "Albanian",
    "sr": "Serbian",
    "sv": "Swedish",
    "sw": "Swahili",
    "ta": "Tamil",
    "te": "Telugu",
    "th": "Thai",
    "tl": "Tagalog",
    "tr": "Turkish",
    "ug": "Uyghur",
    "uk": "Ukrainian",
    "ur": "Urdu",
    "vi": "Vietnamese",
    "vo": "Volapük",
    "wa": "Walloon",
    "xh": "Xhosa",
    "zh": "Chinese",
    "zu": "Zulu"
}

This API returns the label for the languages. It returns the language code type with their corresponding name. See the parameters section for more information.

HTTPS Request

GET <TABASEURL>/availableLanguages

Common Parameters

Param	Type	Required	Description
clusters	array	no	An array of clusters.
countries	array	no	An array of countries (ISO code 2 digits format).
langs	array	no	An array of languages (ISO code 2 digits format).
competitor_ids	array	no	An array of competitor IDs.
networks	array	no	An array of networks.
responses	boolean	no	Content / Review with or without a reply.
sentiment_ranges	array	no	An array of sentiment ranges. For instance, get contents with sentiment from 0 to 30 AND contents with sentiment from 70 to 100, becomes [[0, 30], [70, 100]].
user_types	array	no	An array of user types.

Clusters

Param	Type	Description
clusters	array	An array of clusters: 101, 102, 103, ...

Hotel clusters details

Value	Description
101	General
102	Rooms
103	Position
104	Services
105	Food
106	Hospitality
107	Cleanliness
108	Costs
109	Internet

Venue clusters details

Value	Description
301	General
302	Food quality
303	Position
304	Services
305	Beauty
306	Hospitality
307	Cleanliness
308	Costs
309	Internet

Networks

Param	Type	Description
networks	array	An array of networks: 2spaghi, agoda, airbnb, bookatable, booking, budgetplaces, cheaptickets, ebookers, expedia, facebook, foursquare, getyourguide, google, holidaycheck, homeaway, homelidays, hostelbookers, hostelsclub, hostelworld, hotelclub, hotels, hotwire, hrs, instagram, justeat, laterooms, misiedo, mrjet, musement, opentable, orbitz, pinterest, qualitando, quandoo, search, thefork, travelocity, tripadvisor, tripadvisorforum, twitter, vayable, venere, viator, vimeo, website, wimdu, wotif, yelp, youtube, zomato, zoover

Ratings

Cluster	Description
gen	General
pos	Location
roo	Rooms
sle	Quality of sleep
ser	Services
cle	Cleanliness
pri	Price/quality
coo	Cooking
seo	Service
qpr	Price/quality
atm	Atmosphere
leg	Legroom
cus	Customer service
che	Checkin
ent	Entertainment
sea	Seat Comfort
bre	Breakfast
com	Comfort
sta	Staff
qua	Price/quality
wir	Internet
hot	Hotel
foo	Food
spo	Sports & Entertainment
sco	Score
chd	Suitable for children
con	Room comforts
apr	Price/quality
acc	Precision
cin	Check-in
val	Value
hal	Halflife
nei	Neighborhood
amb	Ambience
loc	Location
dri	Drinks
sic	Security
per	Personal
ove	Overall
gas	Gastronomy
rec	Reception
int	Internet
wel	Wellness
swi	Pool
bus	Business
dec	Decoration
fid	Fidelity

Traveller Types

Param	Type	Description
user_types	array	An array of traveller types: e, o, f, ...

Traveller Types details

Value	Description
e	All
o	Other
f	Families
c	Couples
g	Friends/Groups
a	Solo travelers
b	Business trips
r	Romantic getaway

Types

Param	Type	Description
type	string	It can be one of the following value: hotel, venue, country_house

Each type has a list of associated permitted categories

Categories

Type	Categories
hotel	hotel,resort,motel, residence,historic_residence
country_house	b&b,farm_house,camping, holiday_village,hostel, house_flat,room_rental, mountain_lodge,lodge
venue	restaurant,pizzeria,tavern, pub,bar,icecream_shop, bakery,sandwich_shop,beach

Semantic

This API belong to the TA semantic engine management.

Notify semantic errors

curl '<TABASEURL>/taiScores' \
-H 'Authorization: Token <APIKEY>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d @- << BODY
{
    "message": "Message to notify an error",
    "filters": {
        "contentsID": [ ... ]
    }
}
BODY

If everything is fine the above command returns:

true

This API allows to notify an error on the semantic engine for a single content.

HTTPS Request

POST <TABASEURL>/notifySemanticError

Parameters

Param	Type	Required	Description
message	string	yes	The explaination message related to the specified contents. It has a maximum size of 255 characters.
contentsID	array	yes	An array that contains a single content ID. See Content Statistics > Contents ID for retrieve this parameter first.q

Errors

Occasionally you might encounter errors when accessing the REST API. There are four possible types:

Error Code	Error Type
400 Bad Request	Invalid request.
403 Forbidden	You don't have the permission to access to the information requested.
404 Not Found	The resource you are searching for is not found.
405 Method Not Allowed	The requested method is not allowed.
447 Custom code	Cannot complete the operation requested.
500 Internal Server Error	Generic server error.
503 Service Unavailable	The service is temporary unavailable.