▪ Cluster Series Compare
Cluster Series Compare API returns two, time-based cluster data series 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 time-based data series between the two data series are returned as well.
Request
Endpoint
GET
/v4/{billing_plan}/account/{account_id}/locations/clusters/overall/series/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 | AreaGeometryIDCircle | |
| *from | Start date of actual timeframe. | date | 2020-01-01 | |
| *to | End date of actual timeframe. | date | 2020-12-31 | |
| *period | Time unit of the series. | string | weekmonth | |
| {ComparisonLocation} | Comparison location identifier. | Comparison |
ComparisonAreaComparisonGeometryIDComparisonCircle | 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. |
| ⓝ topic | Filter by topic. | string | 2 starsdinner | |
| ⓝ cluster | Filter by cluster. | string | Dictionary | |
| ⓝ 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 | |
| language | Translate cluster names in the specified language.It also allows the user to filter by cluster parameter by setting its value in the specified language. |
string | itfr | en |
| ⓝ 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 | itde | |
| ⓝ content_languageⓝ compare_content_language | Filter by contents language in ISO_639-1 standard format. | string | enfr | |
| ⓝ content_typeⓝ compare_content_type | Filter by type of content. | string | postreviewtaggedpost | review && taggedpost |
| 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 period
- week
- month
Supported values for language
- en
- it
- fr
- es
- de
Example
curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/clusters/overall/series/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&compare_from=2020-11-01&compare_to=2020-12-31&period=month&page_size=2' \
-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/clusters/overall/series/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&compare_from=2020-11-01&compare_to=2020-12-31&period=month&page_size=2' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \
Response
Status
| Status | Description |
|---|---|
| 200 | Cluster Series Compare data has been successfully returned. |
Body
LocationComparedSeriesClusters
| Name | Description | Type |
|---|---|---|
| *results | Paginated compared clusters data series. | LocationComparedSeriesClustersResults |
| paging | Response pagination. | Paging |
LocationComparedSeriesClustersResults
| Field | Description | Type |
|---|---|---|
| actual | Clusters data series for the actual timeframe. | LocationComparableSeriesClusters |
| comparison | Clusters data series for the comparison timeframe. | LocationComparableSeriesClusters |
| variation | Calculated difference between actual and comparison. |
array[LocationSeriesClustersVariation] |
LocationComparableSeriesClusters
| Field | Description | Type |
|---|---|---|
| timeframe | Reference date range. | Timeframe |
| value | Clusters data series for the corresponding timeframe. |
LocationSeriesCluster |
Timeframe
| Field | Description | Type |
|---|---|---|
| *from | Start date of timeframe. | date |
| *to | End date of timeframe. | date |
LocationSeriesCluster
| Field | Description | Type |
|---|---|---|
| *cluster | Descriptive identifier of the cluster. | string |
| *series | Cluster data series. | array[LocationSeriesClusterElement] |
LocationSeriesClusterElement
| Field | Description | Type |
|---|---|---|
| *period | Date representing the requested period, corresponding to the first day of the period.week: first day of the corresponding week.month: first day of the corresponding month. |
date |
| *value | Cluster data of corresponding period. |
LocationSemantics |
LocationSemantics
| Field | Description | Type |
|---|---|---|
| contents | Total count of contents. | Total |
| opinions | Total and grouped by polarity count of opinions. | PolarizedCount |
| sentiment | KPI which indicates users global satisfaction. | PolarizedValue |
Total
| Field | Description | Type |
|---|---|---|
| total | Total count of elements. | int |
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 |
LocationSeriesClustersVariation
| Field | Description | Type |
|---|---|---|
| *cluster | Descriptive identifier of the cluster. | string |
| *series | Cluster data variation series for the requested timeframe and period. | array[LocationSeriesSemanticsVariationElement] |
LocationSeriesSemanticsVariationElement
| Field | Description | Type |
|---|---|---|
| *actual_period | Date representing the actual period, corresponding to the first day of the period.week: first day of the corresponding week.month: first day of the corresponding month. |
date |
| *comparison_period | Date representing the comparison period, corresponding to the first day of the period.week: first day of the corresponding week.month: first day of the corresponding month. |
date |
| *value | Cluster variation data between actual_period and comparison_period. |
LocationSemanticsVariation |
LocationSemanticsVariation
| Field | Description | Type |
|---|---|---|
| *opinions | Grouped by polarity opinions variation. | PolarizedVariation |
| *contents | Grouped by polarity contents variation. | TotalVariation |
| *sentiment | Sentiment variation. | Variation |
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 |
TotalVariation
| Field | Description | Type |
|---|---|---|
| total | Total elements count 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 |
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": {
"timeframe": {
"from": "2021-01-01",
"to": "2021-02-28"
},
"value": [
{
"cluster": "atmosphere",
"series": [
{
"period": "2021-01-01",
"value": {
"contents": {
"total": 3049
},
"opinions": {
"positive": 5169,
"negative": 608,
"neutral": 0,
"total": 5777
},
"sentiment": {
"value": 89.48,
"polarity": "POSITIVE"
}
}
},
{
"period": "2021-02-01",
"value": {
"contents": {
"total": 3064
},
"opinions": {
"positive": 4821,
"negative": 611,
"neutral": 0,
"total": 5432
},
"sentiment": {
"value": 88.75,
"polarity": "POSITIVE"
}
}
}
]
},
{
"cluster": "food quality",
"series": [
{
"period": "2021-01-01",
"value": {
"contents": {
"total": 1676
},
"opinions": {
"positive": 2471,
"negative": 275,
"neutral": 0,
"total": 2746
},
"sentiment": {
"value": 89.99,
"polarity": "POSITIVE"
}
}
},
{
"period": "2021-02-01",
"value": {
"contents": {
"total": 1715
},
"opinions": {
"positive": 2537,
"negative": 301,
"neutral": 0,
"total": 2838
},
"sentiment": {
"value": 89.39,
"polarity": "POSITIVE"
}
}
}
]
}
]
},
"comparison": {
"timeframe": {
"from": "2020-11-01",
"to": "2020-12-31"
},
"value": [
{
"cluster": "atmosphere",
"series": [
{
"period": "2020-11-01",
"value": {
"contents": {
"total": 3223
},
"opinions": {
"positive": 5393,
"negative": 654,
"neutral": 0,
"total": 6047
},
"sentiment": {
"value": 89.18,
"polarity": "POSITIVE"
}
}
},
{
"period": "2020-12-01",
"value": {
"contents": {
"total": 1658
},
"opinions": {
"positive": 2804,
"negative": 461,
"neutral": 0,
"total": 3265
},
"sentiment": {
"value": 85.88,
"polarity": "POSITIVE"
}
}
}
]
},
{
"cluster": "food quality",
"series": [
{
"period": "2020-11-01",
"value": {
"contents": {
"total": 1624
},
"opinions": {
"positive": 2387,
"negative": 252,
"neutral": 0,
"total": 2639
},
"sentiment": {
"value": 90.45,
"polarity": "POSITIVE"
}
}
},
{
"period": "2020-12-01",
"value": {
"contents": {
"total": 948
},
"opinions": {
"positive": 1338,
"negative": 134,
"neutral": 0,
"total": 1472
},
"sentiment": {
"value": 90.9,
"polarity": "POSITIVE"
}
}
}
]
}
]
},
"variation": [
{
"cluster": "atmosphere",
"series": [
{
"actual_period": "2021-01-01",
"comparison_period": "2020-11-01",
"value": {
"opinions": {
"positive": {
"value": -224,
"variation": "NEGATIVE"
},
"negative": {
"value": -46,
"variation": "POSITIVE"
},
"neutral": {
"value": 0,
"variation": "NEUTRAL"
},
"total": {
"value": -270,
"variation": "NEGATIVE"
}
},
"contents": {
"total": {
"value": -174,
"variation": "NEGATIVE"
}
},
"sentiment": {
"value": 0.3,
"variation": "POSITIVE"
}
}
},
{
"actual_period": "2021-02-01",
"comparison_period": "2020-12-01",
"value": {
"opinions": {
"positive": {
"value": 2017,
"variation": "POSITIVE"
},
"negative": {
"value": 150,
"variation": "NEGATIVE"
},
"neutral": {
"value": 0,
"variation": "NEUTRAL"
},
"total": {
"value": 2167,
"variation": "POSITIVE"
}
},
"contents": {
"total": {
"value": 1406,
"variation": "POSITIVE"
}
},
"sentiment": {
"value": 2.87,
"variation": "POSITIVE"
}
}
}
]
},
{
"cluster": "food quality",
"series": [
{
"actual_period": "2021-01-01",
"comparison_period": "2020-11-01",
"value": {
"opinions": {
"positive": {
"value": 84,
"variation": "POSITIVE"
},
"negative": {
"value": 23,
"variation": "NEGATIVE"
},
"neutral": {
"value": 0,
"variation": "NEUTRAL"
},
"total": {
"value": 107,
"variation": "POSITIVE"
}
},
"contents": {
"total": {
"value": 52,
"variation": "POSITIVE"
}
},
"sentiment": {
"value": -0.46,
"variation": "NEGATIVE"
}
}
},
{
"actual_period": "2021-02-01",
"comparison_period": "2020-12-01",
"value": {
"opinions": {
"positive": {
"value": 1199,
"variation": "POSITIVE"
},
"negative": {
"value": 167,
"variation": "NEGATIVE"
},
"neutral": {
"value": 0,
"variation": "NEUTRAL"
},
"total": {
"value": 1366,
"variation": "POSITIVE"
}
},
"contents": {
"total": {
"value": 767,
"variation": "POSITIVE"
}
},
"sentiment": {
"value": -1.51,
"variation": "NEGATIVE"
}
}
}
]
}
]
},
"paging": {
"last": "/clusters/overall/series/compare?page=18&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-11-01&from=2021-01-01&to=2021-02-28&compare_to=2020-12-31",
"first": "/clusters/overall/series/compare?page=1&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-11-01&from=2021-01-01&to=2021-02-28&compare_to=2020-12-31",
"prev": null,
"next": "/clusters/overall/series/compare?page=2&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-11-01&from=2021-01-01&to=2021-02-28&compare_to=2020-12-31",
"current": "/clusters/overall/series/compare?page=1&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-11-01&from=2021-01-01&to=2021-02-28&compare_to=2020-12-31",
"pages": [
{
"number": 1,
"uri": "/clusters/overall/series/compare?page=1&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-11-01&from=2021-01-01&to=2021-02-28&compare_to=2020-12-31"
},
{
"number": 2,
"uri": "/clusters/overall/series/compare?page=2&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-11-01&from=2021-01-01&to=2021-02-28&compare_to=2020-12-31"
},
{
"number": 3,
"uri": "/clusters/overall/series/compare?page=3&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-11-01&from=2021-01-01&to=2021-02-28&compare_to=2020-12-31"
},
{
"number": 4,
"uri": "/clusters/overall/series/compare?page=4&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-11-01&from=2021-01-01&to=2021-02-28&compare_to=2020-12-31"
},
{
"number": 5,
"uri": "/clusters/overall/series/compare?page=5&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&compare_from=2020-11-01&from=2021-01-01&to=2021-02-28&compare_to=2020-12-31"
}
],
"elements": [
1,
2
],
"total": 36,
"size": 2
}
}