Places API#

Search places#

GET /api/v1/places

Query parameters#

Parameter	Type	Required	Description
`country`	string	yes	Dataset code of a country with published data: `es` (Spain), `gb` (United Kingdom), `fr` (France) or `pt` (Portugal). France and Portugal have partial initial coverage around twenty major cities and nearby lodging.
`city`	string	no	Lowercase city slug such as `madrid`, `girona`, or `london`.
`q`	string	no	Literal text match across names, city, and lodging categories; maximum 100 characters.
`lodgingType`	string	no	One lodging type. `lodging` is the catch-all and restricts nothing.
`whatsapp`	boolean	no	`true` selects records whose primary number appears WhatsApp-reachable.
`verified`	boolean	no	Select places whose Google listing is marked verified.
`limit`	integer	no	Records per page, from 1 to 100. Default: 25.
`cursor`	string	no	Opaque `nextCursor` from the preceding response.

curl --get 'https://www.hotelovia.com/api/v1/places' \
  --header "X-API-Key: $HOTELOVIA_API_KEY" \
  --data-urlencode 'country=es' \
  --data-urlencode 'city=girona' \
  --data-urlencode 'lodgingType=campsite'

Place object#

Field	Type	Meaning
`id`	string	Stable Hotelovia place identifier.
`name`, `legalName`	string or null	Published display and legal names.
`address`	object	`street`, `city`, `state`, `postalCode`, and two-letter `country`.
`location`	object or null	`latitude` and `longitude`.
`phone`, `phoneType`	string or null	Primary normalized number and `mobile`, `landline`, or `other`.
`additionalPhones`	array	Additional normalized phone records.
`email`	string or null	Published contact email.
`website`, `googleMapsUrl`	string or null	Validated public HTTP(S) URLs.
`primaryType`, `lodgingTypes`	string / array	Google's own category labels, in the country's language.
`lodgingType`	string	One lodging type key, derived from those labels.
`rating`, `reviewCount`	number or null	Google's rating and review count, not Hotelovia's.
`whatsappEligible`	boolean	Technical reachability signal; never consent.
`verified`	boolean	Whether the Google listing is marked verified.
`openingHours`	object or null	Published source day labels mapped to time ranges.
`profileUrl`	string	Canonical public Hotelovia profile.

Fields with no published value remain null or an empty array; clients should not invent data from neighboring fields.

Hotelovia is a directory, not a booking site. A place record carries no availability, no prices and no reservation, and Hotelovia neither rates nor inspects a place itself. Confirm anything that matters directly with the place.

Lodging types#

lodgingType is a language-neutral key. lodgingTypes and primaryType keep Google's own labels, which arrive in the country's language, so the key is what an integration should branch on.

Key	Places it covers
`lodging`	The catch-all: a place to sleep with no narrower label.
`hotel`	Hotels, motels, paradores.
`guesthouse`	Hostales, pensiones, guest houses, posadas.
`hostel`	Hostels, albergues, mountain refuges.
`ruralHouse`	Casas rurales, agroturismo, farm stays.
`apartment`	Tourist apartments, aparthotels, serviced apartments.
`holidayHome`	Holiday homes, villas, chalets, bungalows, cabins.
`campsite`	Campsites and glamping.
`bedAndBreakfast`	Bed and breakfasts.
`resort`	Resorts, spa hotels, holiday villages.
`motorhomeArea`	Motorhome and RV areas.

A place belongs to exactly one key: the most specific one its categories name. Filtering by hotel therefore excludes an aparthotel and a spa resort, which answer to apartment and resort.

Get one place#

GET /api/v1/places/{placeId}

URL-encode the id received from a search response:

const url = `https://www.hotelovia.com/api/v1/places/${encodeURIComponent(place.id)}`
const response = await fetch(url, {
  headers: { 'X-API-Key': process.env.HOTELOVIA_API_KEY },
})
const { place } = await response.json()

The endpoint returns 404 when the id is unknown, suppressed, closed, or no longer published.