▪ Topics Compare
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 starsdinner | |
| 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 | itfr | en |
| reply_received | Filter by contents with a reply. | boolean | truefalse | |
| 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 | itde | |
| ⓝ content_language | Filter by contents language in ISO_639-1 standard format. | string | enfr | |
| ⓝ 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.positivecontents.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 |
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
}
}