Skip to content

▪ Topics Compare

Topics Compare API returns two different topic data sets 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 data between the two data sets is returned as well.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/locations/semantics/topics/overall/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 Area
GeometryID
Circle
*from Start date of actual timeframe. date 2020-01-01
*to End date of actual timeframe. date 2020-12-31
{ComparisonLocation} Comparison location identifier. ComparisonGeospatial ComparisonArea
ComparisonGeometryID
ComparisonCircle		 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.
ⓝ 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
ⓝ network
ⓝ compare_network		 Filter by network. string Dictionary
ⓝ 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 it
de
ⓝ content_language
ⓝ compare_content_language		 Filter by contents language in ISO_639-1 standard format. string en
fr
ⓝ content_type
ⓝ compare_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 topic

Booking process & access

  • check-in_check-out
  • reservation

Economic factors & time management

  • costs
  • waiting_times

Facilities & services

  • apartment_host
  • beach
  • cultural
  • entertainment
  • hospitality
  • parking
  • pool_spa
  • services
  • sports
  • staff
  • transportation
  • wifi_connection

Food & dining experience

  • aperitif
  • appetizer
  • beverages
  • breakfast
  • desserts
  • first_courses
  • food
  • main_courses
  • menu

Experience quality & comfort

  • atmosphere
  • cleanliness
  • emotional
  • location
  • safety

Inclusivity & sustainability

  • accessibility
  • family-friendly
  • inclusivity
  • sustainability

Hospitality & accommodation quality

  • bathroom
  • kitchen
  • room

Products & brands

  • brand
  • products
Supported values for content_type
  • review
  • post
  • taggedpost
Example 
curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/locations/semantics/topics/overall/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01&compare_from=2020-07-01&compare_to=2021-01-01&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/semantics/sample/topics/overall/compare?geometry_id=379c730942e570d586a5520770c0a65d&from=2021-01-01&to=2021-07-01&compare_from=2020-07-01&compare_to=2021-01-01&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

LocationComparedSemanticsTopics

Field Description Type
*results Paginated compared topics data. LocationComparedTopicsResults
paging Response pagination. Paging
LocationComparedSemanticsTopicsResults
Field Description Type
actual Topics grouped data for the requested timeframe. LocationComparableSemanticsTopics
comparison Topics grouped data for comparison timeframe. LocationComparableSemanticsTopics
variation Calculated difference between actual and comparison. array[LocationSemanticsTopicVariation]
LocationComparableSemanticsTopics
Field Description Type
timeframe Reference date range. Timeframe
value Clusters data for the corresponding timeframe. array[LocationSemanticsTopic]
Timeframe
Field Description Type
*from Start date of timeframe. date
*to End date of timeframe. date
LocationSemanticsTopic
Field Description Type
topic Descriptive identifier of the topic. string
sentiment KPI which indicates users global satisfaction. PolarizedValue
semantic_rating KPI calculated by correlating sentiment and n_segments. PolarizedValue
n_contents Total count of contents. int
n_segments Total count of segments in contents. 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
LocationSemanticsTopicVariation
Field Description Type
*topic Descriptive identifier of the topic. string
*sentiment Sentiment variation. Variation
*semantic_rating Semantic rating variation. Variation
*n_contents Number of contents variation. Variation
*n_segments NUmber of segments 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": "2025-01-01",
                "to": "2025-07-01"
            },
            "value": [
                {
                    "topic": "food",
                    "sentiment": {
                        "value": 80.9,
                        "polarity": "POSITIVE"
                    },
                    "semantic_rating": {
                        "value": 80.9,
                        "polarity": "POSITIVE"
                    },
                    "n_contents": 692467,
                    "n_segments": 893152
                },
                {
                    "topic": "location",
                    "sentiment": {
                        "value": 83.01,
                        "polarity": "POSITIVE"
                    },
                    "semantic_rating": {
                        "value": 79.67,
                        "polarity": "POSITIVE"
                    },
                    "n_contents": 664478,
                    "n_segments": 721564
                }
            ]
        },
        "comparison": {
            "timeframe": {
                "from": "2024-01-01",
                "to": "2024-07-01"
            },
            "value": [
                {
                    "topic": "food",
                    "sentiment": {
                        "value": 80.12,
                        "polarity": "POSITIVE"
                    },
                    "semantic_rating": {
                        "value": 80.12,
                        "polarity": "POSITIVE"
                    },
                    "n_contents": 806164,
                    "n_segments": 1046467
                },
                {
                    "topic": "location",
                    "sentiment": {
                        "value": 82.52,
                        "polarity": "POSITIVE"
                    },
                    "semantic_rating": {
                        "value": 77.42,
                        "polarity": "POSITIVE"
                    },
                    "n_contents": 685575,
                    "n_segments": 743628
                }
            ]
        },
        "variation": [
            {
                "topic": "food",
                "sentiment": {
                    "value": 0.78,
                    "variation": "POSITIVE"
                },
                "semantic_rating": {
                    "value": 0.78,
                    "variation": "POSITIVE"
                },
                "n_contents": {
                    "value": -113697,
                    "variation": "NEGATIVE"
                },
                "n_segments": {
                    "value": -153315,
                    "variation": "NEGATIVE"
                }
            },
            {
                "topic": "location",
                "sentiment": {
                    "value": 0.49,
                    "variation": "POSITIVE"
                },
                "semantic_rating": {
                    "value": 2.25,
                    "variation": "POSITIVE"
                },
                "n_contents": {
                    "value": -21097,
                    "variation": "NEGATIVE"
                },
                "n_segments": {
                    "value": -22064,
                    "variation": "NEGATIVE"
                }
            }
        ]
    },
    "paging": {
        "last": "/semantics/topics/overall/compare?page=20&page_size=2&geometry_id=b3d342ed8d59afa70aebee0de21b79c3598ceb98c19cf060c9adeed1157fdccd&from=2025-01-01&to=2025-07-01",
        "first": "/semantics/topics/overall/compare?page=1&page_size=2&geometry_id=b3d342ed8d59afa70aebee0de21b79c3598ceb98c19cf060c9adeed1157fdccd&from=2025-01-01&to=2025-07-01",
        "prev": null,
        "next": "/semantics/topics/overall/compare?page=2&page_size=2&geometry_id=b3d342ed8d59afa70aebee0de21b79c3598ceb98c19cf060c9adeed1157fdccd&from=2025-01-01&to=2025-07-01",
        "current": "/semantics/topics/overall/compare?page=1&page_size=2&geometry_id=b3d342ed8d59afa70aebee0de21b79c3598ceb98c19cf060c9adeed1157fdccd&from=2025-01-01&to=2025-07-01",
        "pages": [
            {
                "number": 1,
                "uri": "/semantics/topics/overall/compare?page=1&page_size=2&geometry_id=b3d342ed8d59afa70aebee0de21b79c3598ceb98c19cf060c9adeed1157fdccd&from=2025-01-01&to=2025-07-01"
            },
            {
                "number": 2,
                "uri": "/semantics/topics/overall/compare?page=2&page_size=2&geometry_id=b3d342ed8d59afa70aebee0de21b79c3598ceb98c19cf060c9adeed1157fdccd&from=2025-01-01&to=2025-07-01"
            },
            {
                "number": 3,
                "uri": "/semantics/topics/overall/compare?page=3&page_size=2&geometry_id=b3d342ed8d59afa70aebee0de21b79c3598ceb98c19cf060c9adeed1157fdccd&from=2025-01-01&to=2025-07-01"
            },
            {
                "number": 4,
                "uri": "/semantics/topics/overall/compare?page=4&page_size=2&geometry_id=b3d342ed8d59afa70aebee0de21b79c3598ceb98c19cf060c9adeed1157fdccd&from=2025-01-01&to=2025-07-01"
            },
            {
                "number": 5,
                "uri": "/semantics/topics/overall/compare?page=5&page_size=2&geometry_id=b3d342ed8d59afa70aebee0de21b79c3598ceb98c19cf060c9adeed1157fdccd&from=2025-01-01&to=2025-07-01"
            }
        ],
        "elements": [
            1,
            2
        ],
        "total": 39,
        "size": 2
    }
}