Hotels

Hotels are the core records you manage in HotelRank. Each hotel captures the Google Places linkage, location context, and metadata your workspace needs before running an analysis. Google Place ID is the primary identifier for the Hotels API — you pass it to create, edit, and archive hotels. Use these endpoints to register the properties you track, keep their details up to date, and cleanly archive them when they are no longer relevant.

The hotel model

Hotel objects are scoped to a workspace and map a property to the identifiers and context needed for LLM visibility analysis.

Properties

Name
google_places_id
Type
string
Description
Primary identifier for the hotel in the API. Uniquely identifies a hotel per workspace.
Name
workspace_id
Type
integer
Description
Workspace that owns the hotel record. Defaults to the workspace on your token but can be specified.
Name
hotel_name
Type
string
Description
Display name for the property.
Name
hotel_website
Type
string
Description
Canonical website URL for the hotel or group.
Name
hotel_type
Type
string
Description
Category such as "boutique hotel", "resort", or "bnb".
Name
hotel_group
Type
string
Description
Group or chain affiliation, e.g., "Marriott" or "Accor".
Name
hotel_classification
Type
integer
Description
Official star classification (1-5).
Name
street_address
Type
string
Description
Full street address for the property.
Name
postcode
Type
string
Description
Postal code portion of the address.
Name
city
Type
string
Description
City the hotel is located in.
Name
country
Type
string
Description
Country for the property.
Name
location
Type
string
Description
Traveller-facing location context (e.g., neighborhood or district).
Name
created_at
Type
timestamp
Description
Timestamp of when the hotel was created.
Name
updated_at
Type
timestamp
Description
Timestamp of the most recent update to the hotel record.
Name
target_personas
Type
array
Description
Optional list of personas you are targeting for this property.
Name
locations
Type
array
Description
Optional list of location contexts you care about (cities, neighborhoods, or regions).
Name
target_topics
Type
array
Description
Optional list of topics you want to track for this property (e.g., "spa", "family-friendly").

GET/v1/hotels

List hotels

Retrieve the hotels you track in a workspace. Use filters to focus on a single location or to pull a specific page of results.

Optional query params

Name
workspace_id
Type
integer
Description
Filter hotels to a specific workspace when your token spans multiple workspaces.
Name
city
Type
string
Description
Filter hotels returned to a specific city.
Name
brand
Type
string
Description
Filter hotels by brand or group (maps to hotel_group).
Name
country
Type
string
Description
Filter hotels returned to a specific country.
Name
limit
Type
integer
Description
Limit the number of hotels returned (pagination).
Name
page
Type
integer
Description
Page number for pagination (starts at 1).

Request

GET

/v1/hotels

curl -G https://api.hotelrank.ai/v1/hotels \
  -H "Authorization: Bearer {token}" \
  -d workspace_id=8 \
  -d city=Lisbon \
  -d brand=Independent \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "google_places_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "workspace_id": 8,
      "hotel_name": "Hotel Aurora",
      "hotel_website": "https://aurora.example.com",
      "hotel_type": "boutique hotel",
      "hotel_group": "Independent",
      "hotel_classification": 5,
      "street_address": "123 Ocean Dr",
      "postcode": "90210",
      "city": "Miami",
      "country": "USA",
      "location": "South Beach",
      "target_personas": ["digital nomad", "bleisure traveler"],
      "locations": ["Miami", "South Beach"],
      "target_topics": ["pool", "wifi"],
      "created_at": 1712332200,
      "updated_at": 1714934200
    }
  ]
}

POST/v1/hotels

Create a hotel

Register a new hotel for analysis. Google Place ID is required and serves as the primary key — duplicate registrations for the same workspace will be rejected. All other fields are optional and can be added later with an update.

Required attributes

Name
google_places_id
Type
string
Description
Google Places identifier for the hotel (primary key).

Optional attributes

Name
hotel_name
Type
string
Description
The display name for the property.
Name
city
Type
string
Description
City where the hotel is located.
Name
country
Type
string
Description
Country where the hotel is located.
Name
workspace_id
Type
integer
Description
Workspace override if your token spans multiple workspaces.
Name
hotel_website
Type
string
Description
Canonical website URL for the hotel or group.
Name
hotel_type
Type
string
Description
Category such as "boutique hotel", "resort", or "bnb".
Name
hotel_group
Type
string
Description
Group or chain affiliation, e.g., "Marriott" or "Accor".
Name
hotel_classification
Type
integer
Description
Official star classification (1-5).
Name
street_address
Type
string
Description
Full street address for the property.
Name
postcode
Type
string
Description
Postal code portion of the address.
Name
location
Type
string
Description
Traveller-facing location context (e.g., neighborhood or district).
Name
target_personas
Type
array
Description
Optional list of personas you are targeting for this property.
Name
locations
Type
array
Description
Optional list of location contexts you care about (cities, neighborhoods, or regions).
Name
target_topics
Type
array
Description
Optional list of topics you want to track for this property (e.g., "spa", "family-friendly").

Request

POST

/v1/hotels

curl https://api.hotelrank.ai/v1/hotels \
  -H "Authorization: Bearer {token}" \
  -d google_places_id="ChIJN1t_tDeuEmsRUsoyG83frY4" \
  -d hotel_name="Hotel Aurora" \
  -d hotel_type="boutique hotel" \
  -d city="Miami" \
  -d country="USA" \
  -d location="South Beach" \
  -d target_personas[]="digital nomad" \
  -d target_personas[]="family traveler" \
  -d target_topics[]="wifi" \
  -d target_topics[]="pool"

Response

{
  "google_places_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
  "workspace_id": 8,
  "hotel_name": "Hotel Aurora",
  "hotel_website": null,
  "hotel_type": "boutique hotel",
  "hotel_group": null,
  "hotel_classification": null,
  "street_address": null,
  "postcode": null,
  "city": "Miami",
  "country": "USA",
  "location": "South Beach",
  "target_personas": ["digital nomad", "family traveler"],
  "locations": ["Miami", "South Beach"],
  "target_topics": ["wifi", "pool"],
  "created_at": 1714934200,
  "updated_at": 1714934200
}

GET/v1/hotels/:google_places_id

Retrieve a hotel

Get the latest details for a hotel. Responses include all model properties plus metadata such as when the record was last updated.

Request

GET

/v1/hotels/ChIJN1t_tDeuEmsRUsoyG83frY4

curl https://api.hotelrank.ai/v1/hotels/ChIJN1t_tDeuEmsRUsoyG83frY4 \
  -H "Authorization: Bearer {token}"

Response

{
  "google_places_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
  "workspace_id": 8,
  "hotel_name": "Hotel Aurora",
  "hotel_website": "https://aurora.example.com",
  "hotel_type": "boutique hotel",
  "hotel_group": "Independent",
  "hotel_classification": 5,
  "street_address": "123 Ocean Dr",
  "postcode": "90210",
  "city": "Miami",
  "country": "USA",
  "location": "South Beach",
  "target_personas": ["digital nomad", "family traveler"],
  "locations": ["Miami", "South Beach"],
  "target_topics": ["wifi", "pool"],
  "created_at": 1714934200,
  "updated_at": 1717626200
}

PUT/v1/hotels/:google_places_id

Update a hotel

Keep hotel metadata in sync with your source systems by updating contact, classification, or location details. All attributes are optional; send only the fields you want to change. Use the Google Place ID in the path to identify the hotel.

Optional attributes

Name
workspace_id
Type
integer
Description
Workspace override if your token spans multiple workspaces.
Name
hotel_website
Type
string
Description
Canonical website URL for the hotel or group.
Name
hotel_type
Type
string
Description
Category such as "boutique hotel", "resort", or "bnb".
Name
hotel_group
Type
string
Description
Group or chain affiliation, e.g., "Marriott" or "Accor".
Name
hotel_classification
Type
integer
Description
Official star classification (1-5).
Name
street_address
Type
string
Description
Full street address for the property.
Name
postcode
Type
string
Description
Postal code portion of the address.
Name
location
Type
string
Description
Traveller-facing location context (e.g., neighborhood or district).
Name
target_personas
Type
array
Description
Optional list of personas you are targeting for this property.
Name
locations
Type
array
Description
Optional list of location contexts you care about (cities, neighborhoods, or regions).
Name
target_topics
Type
array
Description
Optional list of topics you want to track for this property.

Request

PUT

/v1/hotels/ChIJN1t_tDeuEmsRUsoyG83frY4

curl -X PUT https://api.hotelrank.ai/v1/hotels/ChIJN1t_tDeuEmsRUsoyG83frY4 \
  -H "Authorization: Bearer {token}" \
  -d hotel_classification=5 \
  -d hotel_group="Independent" \
  -d hotel_website="https://aurora.example.com" \
  -d target_personas[]="digital nomad" \
  -d target_topics[]="wifi"

Response

{
  "google_places_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
  "workspace_id": 8,
  "hotel_name": "Hotel Aurora",
  "hotel_website": "https://aurora.example.com",
  "hotel_type": "boutique hotel",
  "hotel_group": "Independent",
  "hotel_classification": 5,
  "street_address": "123 Ocean Dr",
  "postcode": "90210",
  "city": "Miami",
  "country": "USA",
  "location": "South Beach",
  "target_personas": ["digital nomad", "family traveler"],
  "locations": ["Miami", "South Beach"],
  "target_topics": ["wifi", "pool"],
  "created_at": 1714934200,
  "updated_at": 1717626200
}

POST/v1/hotels/:google_places_id/archive

Archive a hotel

Archive a hotel from a workspace without hard-deleting it. Use this when a property is no longer tracked but you want to preserve historical analysis results.

Request

POST

/v1/hotels/ChIJN1t_tDeuEmsRUsoyG83frY4/archive

curl -X POST https://api.hotelrank.ai/v1/hotels/ChIJN1t_tDeuEmsRUsoyG83frY4/archive \
  -H "Authorization: Bearer {token}"