Skip to content

▪ Cluster Series

Cluster Series API returns a time-based cluster data series for the specified {Location}, grouped by a time period.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/locations/clusters/overall/series

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} Location identifier. Geospatial Area
GeometryID
Circle
*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 week
month
ⓝ network Filter by network. string Dictionary
ⓝ topic Filter by topic. string 2 stars
dinner
ⓝ cluster Filter by cluster. string Dictionary
ⓝ poi_class Filter POIs with "category": "hotel" by stars rating in the range [1,5]. int 4
ⓝ poi_industry Filter by POI Industry. string Dictionary
ⓝ 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 it
fr		 en
ⓝ user_type Filter by reviewer type. 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
ⓝ content_type Filter by type of content. string post
review
taggedpost		 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
Supported values for content_type
  • review
  • post
  • taggedpost
Example 
curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/clusters/overall/series?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&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?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28&period=month&page_size=2' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status Description
200 Cluster Series data has been successfully returned.

Body

LocationSeriesClusters

Name Description Type
*results Paginated clusters data series. array[LocationSeriesCluster]
paging Response pagination. Paging
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
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": [
        {
            "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"
                        }
                    }
                }
            ]
        }
    ],
    "paging": {
        "last": "/clusters/overall/series?page=18&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28",
        "first": "/clusters/overall/series?page=1&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28",
        "prev": null,
        "next": "/clusters/overall/series?page=2&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28",
        "current": "/clusters/overall/series?page=1&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28",
        "pages": [
            {
                "number": 1,
                "uri": "/clusters/overall/series?page=1&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28"
            },
            {
                "number": 2,
                "uri": "/clusters/overall/series?page=2&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28"
            },
            {
                "number": 3,
                "uri": "/clusters/overall/series?page=3&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28"
            },
            {
                "number": 4,
                "uri": "/clusters/overall/series?page=4&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28"
            },
            {
                "number": 5,
                "uri": "/clusters/overall/series?page=5&page_size=2&period=month&geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-02-28"
            }
        ],
        "elements": [
            1,
            2
        ],
        "total": 36,
        "size": 2
    }
}