Skip to content

Topics Compare

Pricing Tier Licence Type

Topics Compare API returns topics data of 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}/topics/overall/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 Default
*from Start date of timeframe. date 2020-01-01
*to End date of timeframe. date 2020-12-31
cluster Filter by cluster. string Dictionary
topic Filter by topic. string 2 stars
dinner
language Translate topic names in the specified language.
It also allows the user to filter by topic and cluster parameter by setting its value in the specified language.
string it
fr
en
reply_received Filter by contents with a reply. boolean true
false
sentiment.value.eq Filter by sentiment equal to the specified value. decimal
sentiment.value.gt Filter by sentiment greater than the specified value. decimal
sentiment.value.gte Filter by sentiment greater than or equal to the specified value. decimal
sentiment.value.lt Filter by sentiment less than the specified value. decimal
sentiment.value.lte Filter by sentiment less than or equal to the specified value. decimal
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
order_by Order results by specifying:
      ±{order_value}
Results in ascending order:
      {order_value} or +{order_value}
Results in descending order:
      -{order_value}
string sentiment
+contents.total
-contents.positive
contents.negative
+contents.neutral
page Requested page number for paginated results. int 1
page_size Requested page size for paginated results in the range [1, 100]. int 25
Supported values for language
  • en
  • it
  • fr
  • es
  • de
Supported values for {order_by}
  • sentiment, +sentiment, -sentiment
  • contents.total, +contents.total, -contents.total
  • contents.positive, +contents.positive, -contents.positive
  • contents.negative, +contents.negative, -contents.negative
  • contents.neutral, +contents.neutral, -contents.neutral
Example
curl -X GET 'https://api.datappeal.io/v4/licence/account/{account_id}/poi/HF8xjSQW4W43NGr56denSh/topics/overall/compare?from=2020-01-01&to=2020-02-29&page_size=2' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status Description
200 Topics Compare data has been successfully returned.

Body

ComparedTopics

Field Description Type
*results Paginated compared topic data. ComparedTopicsResults
paging Response pagination. Paging
ComparedTopicsResults
Field Description Type
actual Ratings grouped data for the requested timeframe. ComparableTopics
comparison Ratings grouped data for the self-calculated past timeframe. ComparableTopics
variation Calculated difference between actual and comparison. array[TopicVariationElement]
ComparableTopics
Field Description Type
value Clusters data for the corresponding timeframe. array[Topic]
timeframe Reference date range. Timeframe
Topic
Field Description Type
topic Descriptive identifier of the topic. string
contents Total and grouped by polarity count of contents. PolarizedCount
opinions Total and grouped by polarity count of opinions. PolarizedCount
sentiment KPI which indicates users global satisfaction. PolarizedValue
PolarizedCount
Field Description Type
positive Positive elements count. int
negative Negative elements count. int
neutral Neutral elements count. int
total Total elements count. int
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
Timeframe
Field Description Type
*from Start date of timeframe. date
*to End date of timeframe. date
TopicVariationElement
Field Description Type
*group Descriptive identifier of the topic. string
*value Topic variation data. FullVariation
FullVariation
Field Description Type
sentiment Sentiment variation. Variation
contents Grouped by polarity contents variation. PolarizedVariation
opinions Grouped by polarity opinions variation. 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
Paging
Field Description Type
last A relative URI to the last page. string
first A relative URI to the first page. string
prev A relative URI to the previous page. string
next A relative URI to the next page. string
current A relative URI to the current page. string
pages A set of relative URIs calculated around the current page. Page
elements All indexes shown on the current page. array[int]
total The number of all elements that API can retrieve. int
size The selected page size. int
Page
Field Description Type
number Number of the page. int
uri URI of the page. string
Example
{
    "results": {
        "actual": {
            "value": [
                {
                    "topic": "2 stars",
                    "sentiment": {
                        "value": 12.49,
                        "polarity": "NEGATIVE"
                    },
                    "opinions": {
                        "positive": 1,
                        "negative": 3,
                        "neutral": 0,
                        "total": 4
                    },
                    "contents": {
                        "positive": 0,
                        "negative": 3,
                        "neutral": 0,
                        "total": 3
                    }
                },
                {
                    "topic": "4 stars",
                    "sentiment": {
                        "value": 47.03,
                        "polarity": "NEGATIVE"
                    },
                    "opinions": {
                        "positive": 2,
                        "negative": 9,
                        "neutral": 0,
                        "total": 11
                    },
                    "contents": {
                        "positive": 3,
                        "negative": 5,
                        "neutral": 0,
                        "total": 8
                    }
                }
            ],
            "timeframe": {
                "from": "2020-01-01",
                "to": "2020-02-29"
            }
        },
        "comparison": {
            "value": [
                {
                    "topic": "2 stars",
                    "sentiment": {
                        "value": 24.39,
                        "polarity": "NEGATIVE"
                    },
                    "opinions": {
                        "positive": 1,
                        "negative": 2,
                        "neutral": 0,
                        "total": 3
                    },
                    "contents": {
                        "positive": 0,
                        "negative": 2,
                        "neutral": 0,
                        "total": 2
                    }
                },
                {
                    "topic": "4 stars",
                    "sentiment": {
                        "value": 77.14,
                        "polarity": "POSITIVE"
                    },
                    "opinions": {
                        "positive": 4,
                        "negative": 1,
                        "neutral": 0,
                        "total": 5
                    },
                    "contents": {
                        "positive": 4,
                        "negative": 0,
                        "neutral": 0,
                        "total": 4
                    }
                }
            ],
            "timeframe": {
                "from": "2019-01-01",
                "to": "2019-02-28"
            }
        },
        "variation": [
            {
                "group": "2 stars",
                "value": {
                    "sentiment": {
                        "value": -11.90,
                        "variation": "NEGATIVE"
                    },
                    "opinions": {
                        "positive": {
                            "value": 0,
                            "variation": "NEUTRAL"
                        },
                        "negative": {
                            "value": 1,
                            "variation": "NEGATIVE"
                        },
                        "neutral": {
                            "value": 0,
                            "variation": "NEUTRAL"
                        },
                        "total": {
                            "value": 1,
                            "variation": "POSITIVE"
                        }
                    },
                    "contents": {
                        "positive": {
                            "value": 0,
                            "variation": "NEUTRAL"
                        },
                        "negative": {
                            "value": 1,
                            "variation": "NEGATIVE"
                        },
                        "neutral": {
                            "value": 0,
                            "variation": "NEUTRAL"
                        },
                        "total": {
                            "value": 1,
                            "variation": "POSITIVE"
                        }
                    }
                }
            },
            {
                "group": "4 stars",
                "value": {
                    "sentiment": {
                        "value": -30.11,
                        "variation": "NEGATIVE"
                    },
                    "opinions": {
                        "positive": {
                            "value": -2,
                            "variation": "NEGATIVE"
                        },
                        "negative": {
                            "value": 8,
                            "variation": "NEGATIVE"
                        },
                        "neutral": {
                            "value": 0,
                            "variation": "NEUTRAL"
                        },
                        "total": {
                            "value": 6,
                            "variation": "POSITIVE"
                        }
                    },
                    "contents": {
                        "positive": {
                            "value": -1,
                            "variation": "NEGATIVE"
                        },
                        "negative": {
                            "value": 5,
                            "variation": "NEGATIVE"
                        },
                        "neutral": {
                            "value": 0,
                            "variation": "NEUTRAL"
                        },
                        "total": {
                            "value": 4,
                            "variation": "POSITIVE"
                        }
                    }
                }
            }
        ]
    },
    "paging": {
        "last": "/topics/overall/compare?page=76&page_size=2&from=2020-01-01&to=2020-02-29",
        "first": "/topics/overall/compare?page=1&page_size=2&from=2020-01-01&to=2020-02-29",
        "prev": null,
        "next": "/topics/overall/compare?page=2&page_size=2&from=2020-01-01&to=2020-02-29",
        "current": "/topics/overall/compare?page=1&page_size=2&from=2020-01-01&to=2020-02-29",
        "pages": [
            {
                "number": 1,
                "uri": "/topics/overall/compare?page=1&page_size=2&from=2020-01-01&to=2020-02-29"
            },
            {
                "number": 2,
                "uri": "/topics/overall/compare?page=2&page_size=2&from=2020-01-01&to=2020-02-29"
            },
            {
                "number": 3,
                "uri": "/topics/overall/compare?page=3&page_size=2&from=2020-01-01&to=2020-02-29"
            },
            {
                "number": 4,
                "uri": "/topics/overall/compare?page=4&page_size=2&from=2020-01-01&to=2020-02-29"
            },
            {
                "number": 5,
                "uri": "/topics/overall/compare?page=5&page_size=2&from=2020-01-01&to=2020-02-29"
            }
        ],
        "elements": [
            1,
            2
        ],
        "total": 151,
        "size": 2
    }
}