▪ Rating Series Compare

Rating Series Compare API returns two, time-based rating data series at once: one defined by the specified {Location} and [from,to] query parameters and another defined by compare_ prefixed query parameters (or auto-calculated with default values where specified).
Additional comparative time-based data series between the two data series are returned as well.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/locations/ratings/series/compare

Path Parameters

Name	Description	Type	Examples
*{billing_plan}	Billing plan to be applied to the call.	string	ondemand
*{account_id}	Provided identifier of the account.	string
/sample	Filter data for POIs that are included in the sample (subset of POIs that statistically replicates the population of the corresponding location).	string

/sample optional path parameter

Inserting optional path parameter /sample in the following position:

• /v4/{billing_plan}/account/{account_id}/locations/sample/…

will filter data for POIs that are included in the sample (subset of POIs that statistically replicates the population of the corresponding location).

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
*{Location}	Actual location identifier.	Geospatial	Area GeometryID Circle
*from	Start date of actual timeframe.	date	2021-01-01
*to	End date of actual timeframe.	date	2021-07-01
*period	Time unit of the series.	string	week month
{ComparisonLocation}	Comparison location identifier.	ComparisonGeospatial	ComparisonArea ComparisonGeometryID ComparisonCircle	Same as {Location}.
compare_from	Start date of comparison timeframe.	date	2020-07-01	One year before from.
compare_to	End date of comparison timeframe.	date	2021-01-01	One year before to.
ⓝ network ⓝ compare_network	Filter by network.	string	Dictionary
ⓝ poi_class ⓝ compare_poi_class	Filter POIs with "category": "hotel" by stars rating in the range [1,5].	int	4
ⓝ poi_industry ⓝ compare_poi_industry	Filter by POI Industry.	string	Dictionary
ⓝ poi_category ⓝ compare_poi_category	Filter by POI Category.	string	Dictionary
ⓝ user_type ⓝ compare_user_type	Filter by reviewer type.	string	Dictionary
ⓝ user_country ⓝ compare_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 ⓝ compare_content_language	Filter by contents language in ISO_639-1 standard format.	string	en fr
ⓝ content_type ⓝ compare_content_type	Filter by type of content.	string	post review taggedpost	review && taggedpost

Supported values for period

• week
• month

Example

curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/ratings/series/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&compare_from=2020-11-01&compare_to=2020-12-31&period=month' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Example /sample

curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/sample/ratings/series/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&compare_from=2020-11-01&compare_to=2020-12-31&period=month' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status	Description
200	Rating Series Compare data has been successfully returned.

Body

LocationComparedSeriesRatings

Field	Description	Type
actual	Ratings data for the actual timeframe.	LocationComparableSeriesRatings
comparison	Ratings data for the comparison timeframe.	LocationComparableSeriesRatings
variation	Calculated difference between actual and comparison.	LocationSeriesRatingsVariation

LocationComparableSeriesRatings

Field	Description	Type
timeframe	Reference date range.	Timeframe
value	Rating data series for the corresponding timeframe.	LocationSeriesRatings

Timeframe

Field	Description	Type
*from	Start date of timeframe.	date
*to	End date of timeframe.	date

LocationSeriesRatings

Field	Description	Type
series	Rating Series data for the requested timeframe and period.	array[LocationSeriesRatingsElement]

LocationSeriesRatingsElement

Field	Description	Type
*period	Date representing the requested period, corresponding to the first day of the period. week: first day of the corresponding week. month: first day of the corresponding month.	date
*value	Ratings data of corresponding period.	LocationRatings

LocationRatings

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

LocationSeriesRatingsVariation

Field	Description	Type
series	Rating data series for the requested timeframe and period.	array[LocationSeriesRatingsVariationElement]

LocationSeriesRatingsVariationElement

Field	Description	Type
*actual_period	Date representing the actual period, corresponding to the first day of the period. week: first day of the corresponding week. month: first day of the corresponding month.	date
*comparison_period	Date representing the comparison period, corresponding to the first day of the period. week: first day of the corresponding week. month: first day of the corresponding month.	date
*value	Rating variation data between actual_period and comparison_period.	LocationRatingsVariation

LocationRatingsVariation

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": {
        "timeframe": {
            "from": "2021-01-01",
            "to": "2021-02-28"
        },
        "value": {
            "series": [
                {
                    "period": "2021-01-01",
                    "value": {
                        "contents": {
                            "total": 15723
                        },
                        "rating": {
                            "average": 8.88,
                            "cap": 10
                        }
                    }
                },
                {
                    "period": "2021-02-01",
                    "value": {
                        "contents": {
                            "total": 16514
                        },
                        "rating": {
                            "average": 8.86,
                            "cap": 10
                        }
                    }
                }
            ]
        }
    },
    "comparison": {
        "timeframe": {
            "from": "2020-11-01",
            "to": "2020-12-31"
        },
        "value": {
            "series": [
                {
                    "period": "2020-11-01",
                    "value": {
                        "contents": {
                            "total": 16262
                        },
                        "rating": {
                            "average": 8.8,
                            "cap": 10
                        }
                    }
                },
                {
                    "period": "2020-12-01",
                    "value": {
                        "contents": {
                            "total": 10980
                        },
                        "rating": {
                            "average": 8.84,
                            "cap": 10
                        }
                    }
                }
            ]
        }
    },
    "variation": {
        "series": [
            {
                "actual_period": "2021-01-01",
                "comparison_period": "2020-11-01",
                "value": {
                    "contents": {
                        "value": -539,
                        "variation": "NEGATIVE"
                    },
                    "rating": {
                        "value": 0.08,
                        "variation": "POSITIVE"
                    }
                }
            },
            {
                "actual_period": "2021-02-01",
                "comparison_period": "2020-12-01",
                "value": {
                    "contents": {
                        "value": 5534,
                        "variation": "POSITIVE"
                    },
                    "rating": {
                        "value": 0.02,
                        "variation": "POSITIVE"
                    }
                }
            }
        ]
    }
}