▪ Ratings Compare

Ratings Compare API returns ratings data for the selected POI for two different timeframes at once: one defined by [from,to] query parameters and another auto-calculated for the same duration in the past.
Additional comparative data between the two timeframes is returned as well.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/poi/{poi_id}/ratings/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
*from	Start date of timeframe.	date	2020-01-01
*to	End date of timeframe.	date	2020-12-31
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

Example

curl -X GET 'https://api.datappeal.io/v4/licence/account/{account_id}/poi/HF8xjSQW4W43NGr56denSh/ratings/compare?from=2020-01-01&to=2020-02-29' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status	Description
200	Ratings Compare data has been successfully returned.

Body

ComparedRatings

Field	Description	Type
actual	Ratings data for the requested timeframe.	ComparableRatings
comparison	Ratings data for the self-calculated past timeframe.	ComparableRatings
variation	Calculated difference between actual and comparison.	RatingsVariation

ComparableRatings

Field	Description	Type
value	Ratings data for the corresponding timeframe.	Ratings
timeframe	Reference date range.	Timeframe

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

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

Example

{
    "actual": {
        "value": {
            "contents": {
                "total": 590
            },
            "rating": {
                "average": 7.37,
                "cap": 10
            }
        },
        "timeframe": {
            "from": "2020-01-01",
            "to": "2020-02-29"
        }
    },
    "comparison": {
        "value": {
            "contents": {
                "total": 566
            },
            "rating": {
                "average": 7.77,
                "cap": 10
            }
        },
        "timeframe": {
            "from": "2019-01-01",
            "to": "2019-02-28"
        }
    },
    "variation": {
        "contents": {
            "value": 24,
            "variation": "POSITIVE"
        },
        "rating": {
            "value": -0.40,
            "variation": "NEGATIVE"
        }
    }
}