Skip to content

Overall Compare

Overall Compare API returns two different overall 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/{billing_plan}/account/{account_id}/locations/overall/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
{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 content_type
  • review
  • post
  • taggedpost
Example
curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/overall/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01&compare_from=2020-07-01&compare_to=2021-01-01' \
-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/overall/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01&compare_from=2020-07-01&compare_to=2021-01-01' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status Description
200 Overall Compare data has been successfully returned.

Body

LocationComparedOverall

Field Description Type
actual Overall data for the actual timeframe. LocationComparableOverall
comparison Overall data for the comparison timeframe. LocationComparableOverall
variation Calculated difference between actual and comparison. LocationOverallVariation
LocationComparableOverall
Field Description Type
timeframe Reference date range. Timeframe
value Overall data for the corresponding timeframe. LocationOverall
Timeframe
Field Description Type
*from Start date of timeframe. date
*to End date of timeframe. date
LocationOverall
Field Description Type
sentiment KPI which indicates users global satisfaction. PolarizedValue
contents Total and grouped by polarity count of contents. PolarizedCount
poi Count of POIs within the group. PartitionCount
PolarizedValue
Field Description Type Examples
value Value of the including field in the range [0,100]. decimal 60.3
59.7
polarity Polarity of the corresponding value. string POSITIVE
NEGATIVE
PolarizedCount
Field Description Type
positive Positive elements count. int
negative Negative elements count. int
neutral Neutral elements count. int
total Total elements count. int
PartitionCount
Field Description Type
partition Count incidence percentage of the group's elements over total elements. int
count Total elements of the group. int
LocationOverallVariation
Field Description Type
sentiment Sentiment variation. Variation
contents Grouped by polarity variation of contents. PolarizedVariation
poi Variation of POIs within the location. PartitionVariation
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
PolarizedVariation
Field Description Type
positive Positive elements count variation. Variation
negative Negative elements count variation. Variation
neutral Neutral elements count variation. Variation
total Total elements count variation. Variation
PartitionVariation
Field Description Type
partition Count incidence percentage variation of the group's elements over total elements. Variation
count Total elements variation of the group. Variation
Value of $.actual,comparison.value.poi.partition

For non-grouped API calls, this value will always be 100.0: since no grouping is taking place, the total is considered as one whole group.

Example
{
    "actual": {
        "timeframe": {
            "from": "2021-01-01",
            "to": "2021-07-01"
        },
        "value": {
            "sentiment": {
                "value": 89.44,
                "polarity": "POSITIVE"
            },
            "contents": {
                "positive": 172922,
                "negative": 12342,
                "neutral": 3265,
                "total": 188529
            },
            "poi": {
                "partition": 100.0,
                "count": 10304
            }
        }
    },
    "comparison": {
        "timeframe": {
            "from": "2020-07-01",
            "to": "2021-01-01"
        },
        "value": {
            "sentiment": {
                "value": 88.53,
                "polarity": "POSITIVE"
            },
            "contents": {
                "positive": 333753,
                "negative": 25376,
                "neutral": 3908,
                "total": 363037
            },
            "poi": {
                "partition": 100.0,
                "count": 15874
            }
        }
    },
    "variation": {
        "sentiment": {
            "value": 0.91,
            "variation": "POSITIVE"
        },
        "contents": {
            "positive": {
                "value": -160831,
                "variation": "NEGATIVE"
            },
            "negative": {
                "value": -13034,
                "variation": "POSITIVE"
            },
            "neutral": {
                "value": -643,
                "variation": "NEGATIVE"
            },
            "total": {
                "value": -174508,
                "variation": "NEGATIVE"
            }
        },
        "poi": {
            "partition": {
                "value": 0.0,
                "variation": "NEUTRAL"
            },
            "count": {
                "value": -5570,
                "variation": "NEGATIVE"
            }
        }
    }
}