Búsqueda de hoteles: ubicaciones, filtros y paginación
La búsqueda de hotel es un proceso de dos pasos. Primero, resuelva el nombre de un destino en coordenadas geográficas utilizando el punto final de autocompletar. Luego, use esas coordenadas para buscar propiedades disponibles. Este artículo cubre ambos pasos con todo detalle, incluido cómo aplicar filtros y paginar conjuntos de resultados grandes.
Paso 1: Buscar ubicaciones (Autocompletar)
El punto final de autocompletar resuelve una consulta de texto libre en resultados de ubicación estructurados con coordenadas. Admite nombres de ciudades, nombres de regiones, nombres de países e incluso nombres de hoteles específicos.
Punto final
GET /hotels/api/v2/autocomplete?key={query}
Parámetros
| Parámetro | Tipo e | Requerido | Descripción | XENIKB PH35
|---|---|---|---|
clave XENIKBPH42 | string | Sí | Buscar consulta. Ejemplos: "Miami", "París", "Hilton Garden Posada" |
Solicitud de ejemplo
GET /hotels/api/v2/autocomplete?key=MiamiAuthorization: {signature}Content-Type: application/json
Ejemplo de respuesta
{
"data": [
{
"id": "12345",
"name": "Miami",
"full_name": "Miami, Florida, United States",
"country": "United States",
"state": "Florida",
"location": {
"lat": 25.7617,
"long": -80.1918
}
},
{
"id": "12346",
"name": "Miami Beach",
"full_name": "Miami Beach, Florida, United States",
"country": "United States",
"state": "Florida",
"location": {
"lat": 25.7907,
"long": -80.13
}
}
]
}Campos de respuesta
| Campo | X ENIKBPH63TipoDescripción | XENIKBPH6 7|
|---|---|---|
idX ENIKBPH73 | string | Único ubicación identificador. |
na yo | cadena | Corto ubicación nombre. |
fullna yo | string | Completamente nombre calificado (ciudad, estado, país). |
país). y | string | País nombre. |
estado | string | Estado o provincia (donde aplicable). |
ubicación n.lat | número | Latitud coordenada. |
ubicación .long | número | Longitud coordenada. |
Importante: Los encabezados de respuesta incluirán un valor x-correlation-id. Debes capturar y pasar este valor en los encabezados de todas las llamadas API posteriores dentro de la misma sesión de búsqueda. Consulte Administración de sesiones e ID de correlación para obtener más detalles.
*
Paso 2: Buscar hoteles
Una vez que tenga las coordenadas del paso de autocompletar, utilice el punto final de búsqueda de hoteles para encontrar propiedades disponibles.
Punto final
POST /hotels/api/v2/properties?page={page}&limit={limit}
Parámetros de consulta
| Parámetro | TipoXENI KBPH148 | Predeterminado | Descripción |
|---|---|---|---|
página | XENIKB PH_161entero1 | Página numero para paginación. | |
límite__XENIKBPH174 _ | entero | 20 | Número de resultados por página. |
Cuerpo de solicitud
| Campo | TipoXEN IKBPH192 | Requerido | Descripción |
|---|---|---|---|
checkindate XENIKBPH204 | string | Sí | Registro fecha en AAAA-MM-DD formato. |
fecha de pagoXENIKBPH217 | string | Sí | Pagar fecha en formato AAAA-MM-DD. debe ser después checkindate. |
occu pancy | array | Sí | Array de objetos de ocupación de habitaciones (ver abajo). |
latX ENIKBPH246número | Sí | Latitud desde autocompletar resultados. | |
largoX ENIKBPH258número | Sí | Longitud desde autocompletar resultados. | |
paísderesidenciaXENIKB PH269 | string | Sí | ISO Código de país de dos letras del huésped (p. ej., "US"). |
sort XENIKBPH283 | array | No | Clasificación criterios. Consulte la sección Clasificación abajo. |
filtros | objeto | No | Filtro criterios. Consulte la sección Filtros a continuación. |
isasyncXENIKBPH311 _ | booleano | No | Conjunto a false para resultados sincrónicos (recomendado). |
Objeto de ocupación
Cada elemento de la matriz occupancy representa una habitación:
| Campo | XE NIKBPH329TipoDescripción | XENIKBPH333|
|---|---|---|
adultosX ENIKBPH339 | entero | Número de huéspedes adultos (mayores de 18 años). Mínimo: 1. |
niños XENIKBPH349__ | entero | Número de niños. Establezca en 0 si none. |
childages | matriz de números enteros | Edades de cada niño. Debe tener exactamente childs elementos. Ejemplo: [5, 12]. |
Ejemplo: Habitación individual, 2 adultos
"occupancy": [ { "adults": 2, "childs": 0, "childages": [] }]
Ejemplo: Habitación individual, 2 adultos + 1 niño de 8 años
"occupancy": [ { "adults": 2, "childs": 1, "childages": [8] }]
Ejemplo: dos habitaciones
"occupancy": [ { "adults": 2, "childs": 0, "childages": [] }, { "adults": 1, "childs": 2, "childages": [5, 10] }]
*
Filtros
El objeto filters le permite limitar los resultados de la búsqueda. Todos los campos de filtro son opcionales.
| CampoXENIKBPH 378 | Tipo | DescripciónXENIKBPH3 82 |
|---|---|---|
| matriz de números enteros | Calificaciones de estrellas para incluir. Valores: 1 a 5. Ejemplo: [4, 5] para 4 y 5 estrellas hoteles. | |
amenidades | conjunto de strings | Filtrar por servicios. Valores comunes: "WiFi gratis", "Piscina", "Gimnasio", "Estacionamiento", "Restaurante", "Spa", "Admite mascotas", "Aeropuerto lanzadera". |
| XENIKBPH43 0minprecio | número | Mínimo precio total (USD). |
maxpric e | número | Máximo precio total (USD). |
nombre XENIKBPH_451__ | cadena | Filtro por nombre del hotel (coincidencia parcial). Ejemplo: "Marriott". |
Ejemplo: hoteles de 4+ estrellas con piscina de menos de $300
"filters": { "ratings": [4, 5], "amenities": ["Pool"], "max_price": 300}
*
Clasificación
La matriz sort controla el orden de los resultados. Cada elemento es un objeto con campos key y order.
| Ordenar Clave | Descripción |
|---|---|
precio | Ordenar por tarifa total. |
| Pedido | Descripción | XENIKBPH489
|---|---|
asc | Ascendente (el más bajo primero). |
desc | Descendente (el más alto). primero). |
Ejemplo
"sort": [{ "key": "price", "order": "asc" }]
*
Ejemplo de solicitud de búsqueda completa
POST /hotels/api/v2/properties?page=1&limit=20Authorization: {signature}x-correlation-id: {correlation_id}Content-Type: application/json
{ "checkindate": "2025-06-01", "checkoutdate": "2025-06-05", "occupancy": [ { "adults": 2, "childs": 0, "childages": [] } ], "lat": 25.7617, "long": -80.1918, "countryofresidence": "US", "sort": [{ "key": "price", "order": "asc" }], "filters": { "ratings": [4, 5], "amenities": ["Free WiFi", "Pool"], "maxprice": 400 }, "isasync": false}
Respuesta de búsqueda
{
"data": {
"total": 147,
"hotels": [
{
"property_id": "XN00012345",
"name": "Oceanview Resort & Spa",
"ratings": {
"star_rating": 4,
"user_rating": 8.5,
"review_count": 1240
},
"rate": {
"base_rate": 756,
"total_rate": 891.08,
"currency": "USD",
"taxandfees": 135.08,
"recommendedsellingprice": 950,
"saved_price": 58.92
},
"amenities": [
"Free WiFi",
"Pool",
"Spa",
"Restaurant",
"Fitness Center"
],
"image": {
"large": "https://images.xeni.com/hotels/12345/main.jpg"
},
"contact": {
"address": {
"line_1": "123 Ocean Drive",
"city": "Miami Beach",
"state": "FL",
"postal_code": "33139"
}
},
"chain": "Independent",
"distance": 2.4
}
]
}
}Campos de respuesta clave
| Campo | Descripción | XENIKBPH517
|---|---|
datos.total | Total número de propiedades coincidentes en todos páginas. |
propertyid | Identificador único de hotel. Utilice esto para obtener detalles y disponibilidad. llamadas. |
rate.baserate | Tarifa de la habitación antes de impuestos y tasas (para estancia completa). |
rate.totalrate | Total precio incluyendo impuestos y tarifas. |
rate.taxandfees | Impuestos y tarifa importe. |
| XENIKBPH562 tarifa.preciodeventarecomendado | Recomendado precio de venta al público (para margen cálculos). |
rate.saved_price | Ahorros comparados con el precio de venta recomendado. |
distance | Distancia desde el centro de búsqueda en millas. |
*
Paginación
Los resultados se paginan utilizando los parámetros de consulta page y limit.
- El tamaño de página predeterminado es 20 resultados.
- El campo
data.totalen la respuesta le indica el número total de propiedades coincidentes. - Calcular páginas totales:
Math.ceil(total / limit). - Incrementar el parámetro
pagepara recuperar el siguiente lote.
Ejemplo: Obteniendo la página 2
POST /hotels/api/v2/properties?page=2&limit=20
Utilice el mismo cuerpo de solicitud y encabezados que la búsqueda original. El ID de correlación debe permanecer igual durante toda la sesión.
Consejos de paginación
- Si recibes menos resultados que
limit, has llegado a la última página. - Agregue nuevos resultados a su lista existente en lugar de reemplazarlos, para crear una vista completa para el usuario.
- Evite solicitar tamaños de página muy grandes. El valor predeterminado de 20 proporciona un buen equilibrio entre rendimiento e integridad.
_Artículo siguiente: Recuperación de detalles del hotel y disponibilidad de habitaciones
_