Cómo utilizar filtros de búsqueda de hoteles en Quick Builder

Quick Builder admite una variedad de filtros para ayudar a los usuarios a limitar los resultados de búsqueda de hoteles. Los filtros se pasan en el objeto filters dentro del cuerpo de la solicitud de búsqueda. Este artículo cubre todas las opciones de filtro disponibles, clasificación, paginación y modo de búsqueda asíncrona.

Objeto de filtros

Agregue un objeto filters al cuerpo de su solicitud de búsqueda para limitar los resultados:

JSON

{
  "checkin_date": "2026-04-15",
  "checkout_date": "2026-04-18",
  "occupancy": [
    {
      "adults": 2,
      "childs": 0,
      "childages": []
    }
  ],
  "lat": 25.7617,
  "long": -80.1918,
  "countryofresidence": "US",
  "placeid": "placeabc123",
  "filters": {
    "ratings": [
      4,
      5
    ],
    "amenities": [
      "pool",
      "wifi",
      "parking"
    ],
    "name": "Hilton",
    "min_price": 100,
    "max_price": 500,
    "distance": 10
  }
}

Filtros disponibles

Calificaciones de estrellas

Filtrar propiedades por clasificación de estrellas. Pase una serie de números enteros que representen los niveles de estrellas deseados.

Parámetro	Tipo	Descripción
`ratings`	conjunto de números	Clasificaciones de estrellas a incluir (por ejemplo, `[3, 4, 5]` para 3 estrellas y superior)

JSON

{
  "filters": {
    "ratings": [
      4,
      5
    ]
  }
}

Servicios

Filtrar por servicios específicos. Pase una serie de cadenas de nombres de servicios.

Parámetro	Tipo	Descripción
`amenities`	conjunto de cadenas	Nombres de servicios para filtrar (por ejemplo, `["pool", "wifi", "gym"]`)

JSON

{
  "filters": {
    "amenities": [
      "pool",
      "wifi",
      "parking",
      "breakfast"
    ]
  }
}

Consejo: Para ver qué servicios están disponibles para una búsqueda determinada, establezca amenities=true en la cadena de consulta del punto final de búsqueda. La respuesta incluirá datos de servicios para cada propiedad.

Nombre de la propiedad

Busque propiedades que coincidan con un nombre o palabra clave específicos.

Parámetro	Tipo	Descripción
`name`	cadena	Nombre de propiedad completo o parcial para que coincida

JSON

{
  "filters": {
    "name": "Marriott"
  }
}

Rango de precios

Filtrar resultados por precio mínimo y/o máximo por noche. Los precios están en la moneda especificada en la cadena de consulta.

Parámetro	Tipo	Descripción
`minprice`	número	Precio mínimo por noche
`maxprice`	número	Precio máximo por noche

JSON

{
  "filters": {
    "min_price": 150,
    "max_price": 400
  }
}

Distancia

Limite los resultados a propiedades dentro de una cierta distancia de las coordenadas de búsqueda.

Parámetro	Tipo	Descripción
`distance`	número	Distancia máxima en kilómetros desde la búsqueda lat/long

JSON

{
  "filters": {
    "distance": 5
  }
}

Combinando filtros

Todos los filtros se pueden combinar en una sola solicitud. Solo se devuelven las propiedades que coinciden con todos los filtros especificados.

JSON

{
  "filters": {
    "ratings": [
      4,
      5
    ],
    "amenities": [
      "pool",
      "wifi"
    ],
    "name": "Resort",
    "min_price": 200,
    "max_price": 800,
    "distance": 15
  }
}

Clasificación

Controle el orden de los resultados con la matriz sort. Cada objeto de clasificación tiene un key y un order.

Campo	Tipo	Descripción
`sort[].key`	cadena	El campo por el que ordenar (por ejemplo, `"price"`)
`sort[].order`	cadena	Dirección de clasificación: `"asc"` (ascendente) o `"desc"` (descendente)

JSON

{
  "sort": [
    {
      "key": "price",
      "order": "asc"
    }
  ]
}

Paginación

Paginar a través de los resultados utilizando los parámetros de consulta page y limit.

Parámetro	Tipo	Descripción
`page`	número	Número de página, comenzando en 1
`limit`	número	Número de resultados por página (máximo 50)

POST /hotels/api/v2/properties?currency=USD&page=2&limit=25&amenities=true

Para recorrer todos los resultados:

Comience con page=1.
Verifique el recuento total en la respuesta.
Incremente page hasta que haya recuperado todos los resultados.

Modo de búsqueda asíncrona

Cuando is_async se establece en true, la búsqueda arroja resultados a medida que están disponibles en lugar de esperar a que todos los proveedores respondan.

JSON

{
  "is_async": true
}

Cómo funciona el modo asíncrono

Envíe la solicitud de búsqueda con is_async: true.
La respuesta puede tener status: "in_progress" con resultados parciales.
Vuelva a enviar la misma solicitud con el mismo x-correlation-id para obtener resultados actualizados.
Continúe sondeando hasta que status cambie a "success", lo que indica que todos los resultados están disponibles.

Cuándo utilizar el modo asíncrono

Escenario	Modo recomendado
Los resultados iniciales rápidos son aceptables	Asíncrono (`isasync: true`)
Necesita todos los resultados antes de mostrarlos	Sincronización (`isasync: false`)
UI de búsqueda en tiempo real con indicadores de carga	Asíncrono (`is_async: true`)

Ejemplo completo

Una solicitud de búsqueda completamente configurada con filtros, clasificación y paginación:

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

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"
    }
  ],
  "filters": {
    "ratings": [
      4,
      5
    ],
    "amenities": [
      "pool",
      "wifi"
    ],
    "min_price": 150,
    "max_price": 600,
    "distance": 20
  },
  "is_async": false
}

Próximos pasos

Consulte las preguntas frecuentes de Quick Builder para obtener respuestas a preguntas comunes sobre integración.