Method	Path
GET	https://agora.olery.com/v3/destination/:country_code/ratings

Returns per rating average and review count (as time series and/or grouped by traveler segment)

Output Format

The meta field contains general information about the API call.

The aggregated data is returned as an Array of JSON objects in the data field. Each object has the following fields:

Field	Data Types	Description
date	Date	Start date of each time period, if per parameter is used
segment	String	Segment, if segment parameter is used
subsegment	String	Segment, if subsegment parameter is used
value	Float	Rating value on a scale 0-100
topic	String	Topic of the rating
review_count	Integer	Count of reviews the ratings are from

The data is found in the ratings object for each group.

Parameters

Parameter	Parameter Type	Data Types	Required	Description
country_code	path	Integer	true	ISO alpha-2 country code
start_date	query	Date	true	Start date in ISO 8601 format
end_date	query	Date	true	End date in ISO 8601 format
per	query	String	false	Date grouping (day, week, month, quarter, year)
segment	query	String	false	Segment grouping (origin-country, composition, language and hotel fields, see below)
subsegment	query	String	false	Subsegment grouping (origin-country, composition, language and hotel fields, see below)
topics	query	String	false	Filter the output by list of comma-separated rating categories
sources	query	Array	false	Filter the data by list of comma-separated sources names
countries	query	Array	false	Filter the data by list of comma-separated countries codes
languages	query	Array	false	Filter the data by list of comma-separated languages codes
compositions	query	Array	false	Filter the data by list of comma-separated compositions codes
exclude_sources	query	Array	false	Filter out the data by list of comma-separated sources names
exclude_countries	query	Array	false	Filter out the data by list of comma-separated countries codes
exclude_languages	query	Array	false	Filter out the data by list of comma-separated languages codes
exclude_compositions	query	Array	false	Filter out the data by list of comma-separated compositions codes

Segmentation

There are 3 segmentation possible. The first is a time series data grouping specified by the per parameter, which accepts the following values:

• day
• week
• month
• quarter
• year

For the subsegment and the subsegment, review data or property fields can be used for per group analysis. Review data fields include:

• origin-country: origin of the reviewer
• composition: travel composition of the reviewer
• language: language of review text (title and comments)

Property fields are listed below

• property_type
• stars
• county
• region
• province
• state
• nation

Example Call

https://agora.olery.com/v3/destination/NL/ratings?start_date=2020-01-01&end_date=2021-12-31&segment=composition&auth_token=XXX

Example Output

{
  "meta": {
    "per": null,
    "segment": "travel_composition",
    "subsegment": null
  },
  "data": [
    {
      "date": null,
      "segment": "Couples",
      "subsegment": null,
      "ratings": [
        {
          "value": 85.72090628218332,
          "topic": "overall",
          "review_count": 971
        },
        {
          "value": 80.37837837837836,
          "topic": "service",
          "review_count": 111
        },
        {
          "value": 90.95454545454545,
          "topic": "location",
          "review_count": 110
        },
        {
          "value": 84.16822429906541,
          "topic": "room",
          "review_count": 107
        },
        {
          "value": 86.66666666666667,
          "topic": "cleanliness",
          "review_count": 15
        },
        {
          "value": 84.0,
          "topic": "value",
          "review_count": 15
        },
        {
          "value": 88.33333333333333,
          "topic": "facilities",
          "review_count": 15
        },
        {
          "value": 80.69230769230771,
          "topic": "food",
          "review_count": 13
        }
      ]
    }
  ]
}

Response Statuses

Status Code	Reason
200	OK
404	Company not found
403	No access, no authentication token
400	Missing or incorrect dates