Skip to content

▪ Ratings Grouped Compare

Pricing Tier Licence Type

Ratings Grouped Compare API returns two, time-based ratings grouped data sets along with a comparative calculation.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/poi/{poi_id}/ratings/grouped/compare

Path Parameters

Name                       Description Type Examples
*{billing_plan} Billing plan to be applied to the call. string licence
ondemand
*{account_id} Provided identifier of the account. string
*{poi_id} Identifier of the POI to retrieve data for.
Value obtainable either :
- if {billing_plan}= licence, from $.results[*].resource.id field of List Licences Response Body
- if {billing_plan}= ondemand, from $.results.pois[*].id field of any Search API Response Body.		 string XXeUNbmtYZTsH7UGvNfXWo

Header Parameters

Name                          Description Type Examples                         
*x-api-key Provided API key {x_api_key} that allows authentication. string
*Authorization Provided token {jwt_bearer} that allows authorization. string Bearer {jwt_bearer}

Query Parameters

Name                         Description Type Examples Default
*from Start date of timeframe. date 2020-01-01
*to End date of timeframe. date 2020-12-31
*group_type Field for which perform grouping. string network
user_country
content_language
user_type
reply_received Filter by contents with a reply. boolean true
false
ⓝ network Filter by network. string Dictionary
ⓝ user_country Filter by reviewer's country of origin in ISO 3166-1 alpha-2 standard format (in lower case). string it
de
ⓝ content_language Filter by contents language in ISO_639-1 standard format. string en
fr
ⓝ user_type Filter by user type. string Dictionary
② order_by Order results by specifying:
      ±{order_value}
Results in ascending order:
      {order_value} or +{order_value}
Results in descending order:
      -{order_value}		 string +contents.total
-contents.positive
contents.negative
+contents.neutral
page Requested page number for paginated results. int 1
page_size Requested page size for paginated results in the range [1, 100]. int 25
Supported values for group_type
  • network
  • user_country
  • content_language
  • user_type
Supported values for {order_by}
  • contents.total, +contents.total, -contents.total
  • contents.positive, +contents.positive, -contents.positive
  • contents.negative, +contents.negative, -contents.negative
  • contents.neutral, +contents.neutral, -contents.neutral
Example 
curl -X GET 'https://api.datappeal.io/v4/licence/account/{account_id}/poi/HF8xjSQW4W43NGr56denSh/ratings/grouped/compare?from=2020-01-01&to=2020-02-29&group_type=network&page_size=2' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status Description
200 Ratings Grouped Compare data has been successfully returned.

Body

GroupedComparedRatings

Field Description Type
*results Paginated grouped compared ratings data. GroupedComparedRatingsResults
paging Response pagination. Paging
GroupedComparedRatingsResults
Field Description Type
actual Ratings grouped data for the requested timeframe. GroupedComparableRatings
comparison Ratings grouped data for the self-calculated past timeframe. GroupedComparableRatings
variation Calculated difference between actual and comparison. array[GroupedRatingsVariation]
GroupedComparableRatings
Field Description Type
value Rating grouped data for the corresponding timeframe. array[GroupedRatingsElement]
timeframe Reference date range. Timeframe
GroupedRatingsElement
Field Description Type
*group Field value within the requested grouping by field. string
*rating Ratings data of corresponding group. Ratings
Ratings
Field Description Type
contents Total count of contents. Total
rating Average rating score. AverageCap
Total
Field Description Type
total Total count of elements. int
AverageCap
Field Description Type
average Average value in the range [0,cap]. decimal
cap Max possible value. int
Timeframe
Field Description Type
*from Start date of timeframe. date
*to End date of timeframe. date
GroupedRatingsVariation
Field Description Type
*group Field value within the requested grouping by field. string
*compare Ratings variation data of corresponding group. RatingsVariation
RatingsVariation
Field Description Type
contents Contents variation. Variation
rating Rating variation. Variation
Variation
Field Description Type Examples
value Difference between actual value and comparison value. decimal 1.12
variation The explicit variation polarity.
It is null when values are not available in both timeframes.		 string POSITIVE
NEUTRAL
NEGATIVE
Paging
Field Description Type
last A relative URI to the last page. string
first A relative URI to the first page. string
prev A relative URI to the previous page. string
next A relative URI to the next page. string
current A relative URI to the current page. string
pages A set of relative URIs calculated around the current page. Page
elements All indexes shown on the current page. array[int]
total The number of all elements that API can retrieve. int
size The selected page size. int
Page
Field Description Type
number Number of the page. int
uri URI of the page. string
Example 
{
    "results": {
        "actual": {
            "value": [
                {
                    "group": "agoda",
                    "rating": {
                        "contents": {
                            "total": 2
                        },
                        "rating": {
                            "average": 5.80,
                            "cap": 10
                        }
                    }
                },
                {
                    "group": "booking",
                    "rating": {
                        "contents": {
                            "total": 381
                        },
                        "rating": {
                            "average": 7.50,
                            "cap": 10
                        }
                    }
                }
            ],
            "timeframe": {
                "from": "2020-01-01",
                "to": "2020-02-29"
            }
        },
        "comparison": {
            "value": [
                {
                    "group": "booking",
                    "rating": {
                        "contents": {
                            "total": 415
                        },
                        "rating": {
                            "average": 7.88,
                            "cap": 10
                        }
                    }
                }
            ],
            "timeframe": {
                "from": "2019-01-01",
                "to": "2019-02-28"
            }
        },
        "variation": [
            {
                "group": "agoda",
                "contents": {
                    "value": null,
                    "variation": null
                },
                "rating": {
                    "value": null,
                    "variation": null
                }
            },
            {
                "group": "booking",
                "contents": {
                    "value": -34,
                    "variation": "NEGATIVE"
                },
                "rating": {
                    "value": -0.38,
                    "variation": "NEGATIVE"
                }
            }
        ]
    },
    "paging": {
        "last": "/ratings/grouped/compare?page=3&page_size=2&from=2020-01-01&group_type=network&to=2020-02-29",
        "first": "/ratings/grouped/compare?page=1&page_size=2&from=2020-01-01&group_type=network&to=2020-02-29",
        "prev": null,
        "next": "/ratings/grouped/compare?page=2&page_size=2&from=2020-01-01&group_type=network&to=2020-02-29",
        "current": "/ratings/grouped/compare?page=1&page_size=2&from=2020-01-01&group_type=network&to=2020-02-29",
        "pages": [
            {
                "number": 1,
                "uri": "/ratings/grouped/compare?page=1&page_size=2&from=2020-01-01&group_type=network&to=2020-02-29"
            },
            {
                "number": 2,
                "uri": "/ratings/grouped/compare?page=2&page_size=2&from=2020-01-01&group_type=network&to=2020-02-29"
            },
            {
                "number": 3,
                "uri": "/ratings/grouped/compare?page=3&page_size=2&from=2020-01-01&group_type=network&to=2020-02-29"
            }
        ],
        "elements": [
            1,
            2
        ],
        "total": 6,
        "size": 2
    }
}