Skip to content

▪ Topic Insights

Licence Type

Please Note

This call will be authorized only if commercially agreed.
In such case, and additional {x_api_key_llm} parameter will be provided in order to perform this call.

Topic Insights API returns LLM generated insights about a {topic} for the specified {Location}.
A {topic} identifies a subject on which users express opinions.

Warning

If HTTP Response Status Code 202 is returned, the LLM request has already been submitted and is still processing.

In such case, performing the same call every polling_frequency for a maximum of polling_timeout is needed in order to obtain results.

If after polling_timeout the call still returns 202, it is deemed to be unsuccessful.
Otherwise, if the call returns 200 within polling_timeout, it is successful and results are contained in the Response Body.

Suggested values are:

  • polling_frequency: 30 seconds
  • polling_timeout: 5 minutes

However, such values can be freely modulated at the user's discretion depending on their use case.

Request

Endpoint

GET/llm/licence/{licence_id}/territorial/insights/topics/{topic}

Path Parameters

Name                       Description Type Examples
*{licence_id} Identifier of the licence. string
*{topic} Identifier of the topic. string

Header Parameters

Name                          Description Type Examples                          Default
*x-api-key Provided API key {x_api_key_llm} that allows authentication.
Please note that it is provided only upon specific agreement.		 string
*Authorization Provided token {jwt_bearer} that allows authorization. string Bearer {jwt_bearer}
Accept-Language Translates response texts in the language specified in in ISO_639-1 standard format. string it
fr		 en

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
ⓝ topic Filter by topic. string food
location
ⓝ 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
ⓝ network Filter by network. string Dictionary
ⓝ 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
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/licence/{licence_id}/territorial/llm/topics/food?geometry_id=379c730942e570d586a5520770c0a65d&from=2025-01-01&to=2025-07-01' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status Description
200 Topic Insights data has been successfully returned.
202 Topic Insights request is processing.

Body

TopicInsights

Field Description Type
*topic Identifier of the requested topic. string
*n_segments Number of segments used to build the insights. int
*aspects Positive and negative aspects about the requested topic. PolarizedAspects
PolarizedAspects
Field Description Type Examples
*positive List of positive aspects. array[Aspect]
*negative List of negative aspects. array[Aspect]
Aspect
Field Description Type Examples
*title Title of the insight. string High Quality and Delicious Food
*summary Summary of the insight. string Many reviews commend the high quality and delicious taste of various food items.
*relevance Estimated relevance of the insight in the range [0,100] . decimal 85.0
Example 
{
  "topic": "food",
  "n_segments": 8327,
  "aspects": {
    "positive": [
      {
        "title": "High Quality and Delicious Food",
        "summary": "Many reviews praise the high quality, freshness, and delicious taste of the food across various restaurants and cuisines.",
        "relevance": 90.0
      },
      {
        "title": "Wide Variety of Food Choices",
        "summary": "Customers appreciate the wide variety of dishes and ingredient options, including vegan, gluten-free and ethnic foods.",
        "relevance": 75.0
      },
      {
        "title": "Excellent and Friendly Service",
        "summary": "Service is frequently described as attentive, friendly, and professional, enhancing the dining experience.",
        "relevance": 70.0
      },
      {
        "title": "Generous Portions",
        "summary": "Several reviewers note that portions are sufficiently large and satisfying for the price.",
        "relevance": 55.0
      },
      {
        "title": "Good Value for Price",
        "summary": "Many customers feel that the food quality and portion justify the price, indicating strong value for money.",
        "relevance": 50.0
      },
      {
        "title": "Specific Highly Recommended Dishes",
        "summary": "Some specific dishes such as carbonara, risotto, pizza varieties, kebabs, and desserts like tiramisu and cannoli received exceptional praise.",
        "relevance": 45.0
      },
      {
        "title": "Pleasant Ambiance and Atmosphere",
        "summary": "Reviews mention cozy and friendly environments, with good atmospheres in many establishments.",
        "relevance": 40.0
      }
    ],
    "negative": [
      {
        "title": "Poor or Inconsistent Food Quality",
        "summary": "Some reviews complain about poor food quality, tastelessness, or overuse of oil and salt.",
        "relevance": 60.0
      },
      {
        "title": "Small or Insufficient Portions",
        "summary": "A number of customers find portions to be too small for the price or not satisfying.",
        "relevance": 55.0
      },
      {
        "title": "Poor or Rude Service",
        "summary": "Issues with rude, inattentive, or slow service were commonly noted.",
        "relevance": 50.0
      },
      {
        "title": "Food Served Cold or Not Properly Heated",
        "summary": "Multiple mentions of food being served cold or not freshly prepared, negatively impacting the experience.",
        "relevance": 45.0
      },
      {
        "title": "Concerns on Hygiene and Cleanliness",
        "summary": "Some mentions of food contamination (hair, foreign objects) and below-par hygiene standards.",
        "relevance": 30.0
      },
      {
        "title": "High Price for Quality",
        "summary": "Several complain that prices are too high relative to food quality or quantity.",
        "relevance": 35.0
      },
      {
        "title": "Lack of Freshness",
        "summary": "A few reviews point out the use of frozen or pre-made items lacking freshness and flavor.",
        "relevance": 40.0
      },
      {
        "title": "Incorrect or Missing Items in Orders",
        "summary": "There are reports of missing ingredients, wrong items delivered, or incomplete orders especially with takeout or delivery.",
        "relevance": 35.0
      }
    ]
  }
}