Skip to content

▪ Overall Series Compare

Pricing Tier Licence Type

Overall Series Compare API returns two, time-based overall data series 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 time-based data series between the two timeframes are returned as well.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/poi/{poi_id}/overall/series/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
*period Time unit of the series. string day
week
month
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
Supported values for period
  • day
  • week
  • month
Example 
curl -X GET 'https://api.datappeal.io/v4/licence/account/{account_id}/poi/HF8xjSQW4W43NGr56denSh/overall/series/compare?from=2020-01-01&to=2020-02-29&period=month&page_size=2' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

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

Body

ComparedSeriesOverall

Field Description Type
actual Overall data for the requested timeframe. ComparableSeriesOverall
comparison Overall data for the self-calculated past timeframe. ComparableSeriesOverall
variation Calculated difference between actual and comparison. SeriesOverallVariation
ComparableSeriesOverall
Field Description Type
value Overall data series for the corresponding timeframe. SeriesOverall
timeframe Reference date range. Timeframe
SeriesOverall
Field Description Type
series Overall Series data for the requested timeframe and period. array[SeriesOverallElement]
SeriesOverallElement
Field Description Type
*period Date representing the requested period, corresponding to the first day of the period.
day: the day itself.
week: first day of the corresponding week.
month: first day of the corresponding month.		 date
*value Overall grouped data of corresponding period. Overall
Overall
Field Description Type
sentiment KPI which indicates users global satisfaction. PolarizedValue
contents Total and grouped by polarity count of contents. PolarizedCount
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
Timeframe
Field Description Type
*from Start date of timeframe. date
*to End date of timeframe. date
SeriesOverallVariation
Field Description Type
series Overall Series data for the requested timeframe and period. array[SeriesOverallVariationElement]
SeriesOverallVariationElement
Field Description Type
*value Overall variation data between actual_period and previous_period. OverallVariation
*actual_period Date representing the actual period, corresponding to the first day of the period.
day: the day itself.
week: first day of the corresponding week.
month: first day of the corresponding month.		 date
*previous_period Date representing the previous period, corresponding to the first day of the period.
day: the day itself.
week: first day of the corresponding week.
month: first day of the corresponding month.		 date
OverallVariation
Field Description Type
sentiment Sentiment variation. Variation
contents Grouped by polarity variation of contents. PolarizedVariation
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
Example 
{
    "actual": {
        "value": {
            "series": [
                {
                    "period": "2020-01-01",
                    "value": {
                        "sentiment": {
                            "value": 79.36,
                            "polarity": "POSITIVE"
                        },
                        "contents": {
                            "positive": 266,
                            "negative": 50,
                            "neutral": 0,
                            "total": 316
                        }
                    }
                },
                {
                    "period": "2020-02-01",
                    "value": {
                        "sentiment": {
                            "value": 74.07,
                            "polarity": "POSITIVE"
                        },
                        "contents": {
                            "positive": 206,
                            "negative": 68,
                            "neutral": 0,
                            "total": 274
                        }
                    }
                }
            ]
        },
        "timeframe": {
            "from": "2020-01-01",
            "to": "2020-02-29"
        }
    },
    "comparison": {
        "value": {
            "series": [
                {
                    "period": "2019-01-01",
                    "value": {
                        "sentiment": {
                            "value": 80.08,
                            "polarity": "POSITIVE"
                        },
                        "contents": {
                            "positive": 239,
                            "negative": 50,
                            "neutral": 0,
                            "total": 289
                        }
                    }
                },
                {
                    "period": "2019-02-01",
                    "value": {
                        "sentiment": {
                            "value": 79.59,
                            "polarity": "POSITIVE"
                        },
                        "contents": {
                            "positive": 232,
                            "negative": 45,
                            "neutral": 0,
                            "total": 277
                        }
                    }
                }
            ]
        },
        "timeframe": {
            "from": "2019-01-01",
            "to": "2019-02-28"
        }
    },
    "variation": {
        "series": [
            {
                "value": {
                    "sentiment": {
                        "value": -0.72,
                        "variation": "NEGATIVE"
                    },
                    "contents": {
                        "positive": {
                            "value": 27,
                            "variation": "POSITIVE"
                        },
                        "negative": {
                            "value": 0,
                            "variation": "NEUTRAL"
                        },
                        "neutral": {
                            "value": 0,
                            "variation": "NEUTRAL"
                        },
                        "total": {
                            "value": 27,
                            "variation": "POSITIVE"
                        }
                    }
                },
                "actual_period": "2020-01-01",
                "previous_period": "2019-01-01"
            },
            {
                "value": {
                    "sentiment": {
                        "value": -5.52,
                        "variation": "NEGATIVE"
                    },
                    "contents": {
                        "positive": {
                            "value": -26,
                            "variation": "NEGATIVE"
                        },
                        "negative": {
                            "value": 23,
                            "variation": "NEGATIVE"
                        },
                        "neutral": {
                            "value": 0,
                            "variation": "NEUTRAL"
                        },
                        "total": {
                            "value": -3,
                            "variation": "NEGATIVE"
                        }
                    }
                },
                "actual_period": "2020-02-01",
                "previous_period": "2019-02-01"
            }
        ]
    }
}