Metrics

Metrics group LLM outputs into concise signals you can monitor and act on. Use them to understand how often a hotel is mentioned, why it shows up, how travelers perceive it, and which competitors dominate the conversation.

The metrics model

Each metric rolls up LLM responses into visibility, perception, or opportunity insights for a given hotel. Metric keys stay consistent across personas, locations, and time windows so you can compare like-for-like.

Properties

Name
mention_rate
Type
number
Description
AI Visibility — share of analyzed responses that mention the hotel.
Name
average_rank
Type
number
Description
AI Visibility — average position when the hotel appears in ranked lists.
Name
mention_reasons
Type
array
Description
AI Visibility — reasons and themes behind why the hotel was mentioned.
Name
competitors
Type
array
Description
AI Visibility / Opportunities — top competitors co-mentioned with the hotel or leading within an opportunity space.
Name
strengths
Type
array
Description
AI Perception — common positive themes or attributes surfaced for the hotel.
Name
weaknesses
Type
array
Description
AI Perception — common negative themes or gaps attributed to the hotel.

Call parameters

All metric calls accept the same parameters so you can slice results by persona, location, or time window.

Name
hotel_id
Type
integer
Description
Hotel identifier the metrics should be scoped to.
Name
filters
Type
object
Description
Optional filters applied to the analysis inputs (e.g., prompt or model constraints).
Name
model
Type
string
Description
Model identifier used for the underlying analysis.
Name
persona
Type
string
Description
Persona context to slice the metrics by.
Name
location
Type
string
Description
Location context to slice the metrics by.
Name
date
Type
string
Description
Date or date range for the analysis window.
Name
group_by
Type
string
Description
Dimension to aggregate on (e.g., persona or location).

GET/v1/metrics

List metrics

Retrieve visibility, perception, and opportunity metrics for a hotel. Pass personas, locations, and date windows to slice the rollups returned.

Required query params

Name
hotel_id
Type
integer
Description
Hotel identifier to scope the metrics to.

Optional query params

Name
filters
Type
object
Description
Optional filters applied to the analysis inputs (e.g., prompt or model constraints).
Name
model
Type
string
Description
Model identifier used for the underlying analysis.
Name
persona
Type
string
Description
Persona context to slice the metrics by.
Name
location
Type
string
Description
Location context to slice the metrics by.
Name
date
Type
string
Description
Date or date range for the analysis window (e.g., 2024-05-01..2024-05-31).
Name
group_by
Type
string
Description
Dimension to aggregate on (e.g., persona or location).

Request

GET

/v1/metrics

curl -G https://api.hotelrank.ai/v1/metrics \
  -H "Authorization: Bearer {token}" \
  -d hotel_id=88 \
  -d persona="digital nomad" \
  -d location="Lisbon" \
  -d model="gpt-4o-mini" \
  -d date="2024-05-01..2024-05-31" \
  -d group_by=persona

Response

{
  "data": [
    {
      "hotel_id": 88,
      "persona": "digital nomad",
      "location": "Lisbon",
      "date": "2024-05-01..2024-05-31",
      "model": "gpt-4o-mini",
      "group_by": "persona",
      "metrics": {
        "mention_rate": 0.42,
        "average_rank": 2.1,
        "mention_reasons": [
          "fast wifi and coworking nearby",
          "central to cafes and nightlife"
        ],
        "competitors": [
          "LX Loft Hotel",
          "Ribeira Suites",
          "Praça Rooms"
        ],
        "strengths": [
          "reliable wifi",
          "walkable to downtown",
          "good value for location"
        ],
        "weaknesses": [
          "limited parking",
          "small gym"
        ]
      }
    }
  ]
}