▪ Clusters

Clusters API returns general information about clusters for a POI.
A cluster identifies a super-set of topics which have a similar argument pertinence.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/poi/{poi_id}/clusters/overall

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
topic	Filter by topic.	string	2 stars dinner
cluster	Filter by cluster.	string	Dictionary
language	Translate cluster names in the specified language. It also allows the user to filter by `cluster` and `topic` parameter by setting its value in the specified language.	string	it fr	en
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
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

Example

curl -X GET 'https://api.datappeal.io/v4/licence/account/{account_id}/poi/HF8xjSQW4W43NGr56denSh/clusters/overall?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	Clusters data has been successfully returned.

Body

Clusters

Field	Description	Type
*results	Paginated list of clusters.	array[Cluster]
paging	Response pagination.	Paging

Cluster

Field	Description	Type
:fontawesome-solid-exclamation-circle: ~~name~~	~~Descriptive identifier of the cluster.~~	~~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
:fontawesome-solid-sync-alt: cluster	Descriptive identifier of the cluster.	string

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": [
        {
            "name": "atmosphere",
            "contents": {
                "positive": 335,
                "negative": 57,
                "neutral": 0,
                "total": 392
            },
            "opinions": {
                "positive": 439,
                "negative": 117,
                "neutral": 0,
                "total": 556
            },
            "sentiment": {
                "value": 78.96,
                "polarity": "POSITIVE"
            }
        },
        {
            "name": "room",
            "contents": {
                "positive": 60,
                "negative": 59,
                "neutral": 0,
                "total": 119
            },
            "opinions": {
                "positive": 112,
                "negative": 154,
                "neutral": 0,
                "total": 266
            },
            "sentiment": {
                "value": 42.11,
                "polarity": "NEGATIVE"
            }
        }
    ],
    "paging": {
        "last": "/clusters/overall?page=8&page_size=2&from=2020-01-01&to=2020-02-29",
        "first": "/clusters/overall?page=1&page_size=2&from=2020-01-01&to=2020-02-29",
        "prev": null,
        "next": "/clusters/overall?page=2&page_size=2&from=2020-01-01&to=2020-02-29",
        "current": "/clusters/overall?page=1&page_size=2&from=2020-01-01&to=2020-02-29",
        "pages": [
            {
                "number": 1,
                "uri": "/clusters/overall?page=1&page_size=2&from=2020-01-01&to=2020-02-29"
            },
            {
                "number": 2,
                "uri": "/clusters/overall?page=2&page_size=2&from=2020-01-01&to=2020-02-29"
            },
            {
                "number": 3,
                "uri": "/clusters/overall?page=3&page_size=2&from=2020-01-01&to=2020-02-29"
            },
            {
                "number": 4,
                "uri": "/clusters/overall?page=4&page_size=2&from=2020-01-01&to=2020-02-29"
            },
            {
                "number": 5,
                "uri": "/clusters/overall?page=5&page_size=2&from=2020-01-01&to=2020-02-29"
            }
        ],
        "elements": [
            1,
            2
        ],
        "total": 16,
        "size": 2
    }
}