Cómo buscar hoteles en Quick Builder

Quick Builder utiliza los mismos puntos finales de búsqueda y autocompletado de hoteles que la API de Xeni Hotels. Este artículo cubre el proceso de dos pasos: encontrar una ubicación con autocompletar y luego buscar propiedades disponibles.

Paso 1: Autocompletar: buscar una ubicación

Utilice el punto final de autocompletar para buscar destinos por palabra clave. Esto devuelve datos de ubicación y un ID de correlación que necesita para la búsqueda de propiedades.

Solicitud

GET /hotels/api/v2/autocomplete?key=miami

Parámetro	Tipo	Requerido	Descripción
`key`	cadena	Sí	Palabra clave de búsqueda (nombre de la ciudad, región o punto de referencia)

Respuesta

La respuesta devuelve ubicaciones coincidentes en la matriz data. La pieza crítica es el encabezado de respuesta x-correlation-id; debe capturar este valor.

JSON

{
  "data": [
    {
      "id": "place_abc123",
      "country": "US",
      "full_name": "Miami, Florida, United States",
      "location": {
        "lat": 25.7617,
        "long": -80.1918
      },
      "name": "Miami",
      "state": "Florida",
      "type": "city"
    }
  ]
}

Importante: El encabezado x-correlation-id de esta respuesta debe incluirse en solicitudes de búsqueda posteriores. Sin él, la búsqueda fracasará.

Tipos de ubicación

Tipo	Descripción
`city`	Una ciudad específica
`state`	Un estado o provincia
`multicity`	Una región que abarca varias ciudades

Paso 2: Buscar propiedades

Una vez que tenga una ubicación y un ID de correlación, busque propiedades hoteleras disponibles.

Solicitud

POST /hotels/api/v2/properties?currency=USD&page=1&limit=50&amenities=true

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`currency`	cadena	Sí	Código de moneda de tres letras (por ejemplo, `USD`, `EUR`, `GBP`)
`page`	número	Sí	Número de página para resultados paginados (comienza en 1)
`limit`	número	Sí	Número de resultados por página (máximo 50)
`amenities`	booleano	No	Establezca en `true` para incluir datos de servicios en los resultados

Encabezados

Encabezado	Requerido	Descripción
`x-correlation-id`	Sí	El ID de correlación de la respuesta de autocompletar
`Content-Type`	Sí	`application/json`

Cuerpo de solicitud

JSON

{
  "checkin_date": "2026-04-15",
  "checkout_date": "2026-04-18",
  "occupancy": [
    {
      "adults": 2,
      "childs": 1,
      "childages": [
        8
      ]
    }
  ],
  "lat": 25.7617,
  "long": -80.1918,
  "countryofresidence": "US",
  "placeid": "placeabc123",
  "radius": 25,
  "sort": [
    {
      "key": "price",
      "order": "asc"
    }
  ],
  "is_async": false
}

Parámetros del cuerpo

Parámetro	Tipo	Requerido	Descripción
`checkindate`	cadena	Sí	Fecha de entrada en formato `YYYY-MM-DD`
`checkoutdate`	cadena	Sí	Fecha de salida en formato `YYYY-MM-DD`
`occupancy`	matriz	Sí	Matriz de objetos de ocupación de habitaciones
`occupancy[].adults`	número	Sí	Número de adultos en la habitación
`occupancy[].childs`	número	Sí	Número de niños en la habitación
`occupancy[].childages`	matriz	Condicional	Requerido si `childs` > 0. Matriz de edades de los niños.
`lat`	número	Sí	Latitud del resultado de autocompletar
`long`	número	Sí	Longitud del resultado de autocompletar
`countryofresidence`	cadena	Sí	Código de país de dos letras del huésped
`placeid`	cadena	Sí	Colocar ID del resultado de autocompletar
`radius`	número	No	Radio de búsqueda en kilómetros (el valor predeterminado varía según la ubicación)
`sort`	matriz	No	Criterios de clasificación (consulte el artículo sobre filtros para obtener más detalles)
`filters`	objeto	No	Criterios de filtrado (consulte el artículo sobre filtros para obtener más detalles)
`isasync`	booleano	No	Establezca en `true` para el modo asíncrono. El valor predeterminado es `false`.

Flujo de ID de correlación

El ID de correlación vincula las solicitudes de autocompletar y de búsqueda. Aquí está el flujo completo:

1. GET /hotels/api/v2/autocomplete?key=miami
   ← Response includes x-correlation-id header: "corr_xyz789"
POST /hotels/api/v2/properties?currency=USD&page=1&limit=50   → Include header: x-correlation-id: corr_xyz789
   ← Response returns hotel results

Utilice siempre el ID de correlación de la llamada de autocompletar más reciente. No reutilice los ID de correlación en diferentes búsquedas.

Varias habitaciones

Para buscar varias habitaciones, agregue objetos adicionales a la matriz occupancy:

JSON

{
  "occupancy": [
    {
      "adults": 2,
      "childs": 0,
      "childages": []
    },
    {
      "adults": 2,
      "childs": 2,
      "childages": [
        5,
        10
      ]
    }
  ]
}

Cada objeto representa una habitación. La búsqueda arroja propiedades que pueden acomodar todas las habitaciones especificadas.

Próximos pasos

Aprenda cómo aplicar filtros para limitar los resultados de su búsqueda por calificación, servicios, rango de precios y más.