Nights Compare

Nights Compare API returns two different rating data sets 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 data between the two data sets is returned as well.

Request

Endpoint

GET/v4/licence/{licence_id}/territorial/reputation/nights/compare

Path Parameters

Name	Description	Type	Examples
*{licence_id}	Identifier of the licence.	string

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	2025-01-01
*to	End date of actual timeframe.	date	2025-07-01
{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	2025-01-01	One year before to.
ⓝ topic ⓝ compare_topic	Filter by topic.	string	food location
ⓝ 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
ⓝ network ⓝ compare_network	Filter by network.	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
user_resident compare_user_resident	Filter by whether the user's origin falls within the requested location.	boolean	true false

Example

curl -X GET 'https://api.datappeal.io/v4/licence/{licence_id}/territorial/nights/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2025-01-01&to=2025-07-01&compare_from=2020-07-01&compare_to=2025-01-01' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status	Description
200	Nights Compare data has been successfully returned.

Body

LocationComparedRatings

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

LocationComparableRatings

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

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

Timeframe

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

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": {
        "value": {
            "average": 2.1,
            "contents": 181223
        },
        "timeframe": {
            "from": "2020-01-01",
            "to": "2020-02-29"
        }
    },
    "comparison": {
        "value": {
            "average": 8.61,
            "contents": 161223
        },
        "timeframe": {
            "from": "2019-01-01",
            "to": "2019-02-28"
        }
    },
    "variation": {
        "average": {
            "value": -0.40,
            "variation": "NEGATIVE"
        },
        "contents": {
            "value": 24,
            "variation": "POSITIVE"
        }
    }
}