> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifystays.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Hotel Filters

> Retrieve available search facets and counts for a place, city, or hotel's city.

Use this endpoint to build a filter drawer before a hotel search. It returns
only the facet values and counts that are relevant to one selected destination:
star ratings, price range, property types, hotel chains, and facilities.

<Info>
  Pass **exactly one** of `place_id`, `city_id`, or `hotel_id`. The API caches
  the resulting destination facets for 24 hours and returns `cached_until` in
  the response.
</Info>

## Request Example

<RequestExample>
  ```bash theme={null}
  curl "$UNIFYSTAYS_BASE_URL/hotels/filters?city_id=136711" \
    -H "x-api-key: $UNIFYSTAYS_API_KEY" \
    -H "language: en"
  ```
</RequestExample>

## Apply the Facets to Search

Use values from the response as inputs to
[Search Hotels](/api-reference/search-hotels):

| Facet response   | Search request field                            |
| ---------------- | ----------------------------------------------- |
| `stars`          | `star_ratings`                                  |
| `price_range`    | `price_min_usd_cents` and `price_max_usd_cents` |
| `property_types` | `property_types`                                |
| `chains`         | `chain_ids`                                     |
| `facilities`     | `facility_ids`                                  |

For a `place_id`, counts cover the full place subtree. For a `hotel_id`,
Unifystays resolves the hotel's city so a single-hotel result still has a
useful filter set.

<Warning>
  Facets describe the destination catalogue, not live availability. Apply them
  to hotel search, then use fresh room options and prebook before checkout.
</Warning>

The OpenAPI section below contains every parameter, facet field, and response
schema.


## OpenAPI

````yaml reference/openapi.json GET /hotels/filters
openapi: 3.0.0
info:
  title: Unifystays API
  description: >-
    One unified hotel API across suppliers. Integrate once, then enable and
    manage suppliers from the Unifystays portal.
  version: '1.0'
  contact: {}
servers:
  - url: https://api-sandbox.unifystays.com
    description: Sandbox
  - url: https://api.unifystays.com
    description: Production
security:
  - x-api-key: []
tags: []
paths:
  /hotels/filters:
    get:
      tags:
        - Hotels
      summary: List filter facets for a place, a city, or a hotel's city
      description: >-
        Returns available filter values + counts. Pass exactly one of place_id,
        city_id, hotel_id. place_id (from autocomplete type=place) scopes facets
        to the whole place subtree (e.g. all of Bali). For hotel_id, server
        resolves the hotel's city before building facets — so single-hotel
        searches do not have to wait for /hotels/search to know city_id. Payload
        is cached for 24h per destination since hotel inventory changes rarely.
        Use the returned values as filter inputs on POST /hotels/search.
      operationId: HotelFiltersController_getFilters
      parameters:
        - name: city_id
          required: false
          in: query
          description: >-
            City ID from destination autocomplete. Required if place_id/hotel_id
            not supplied.
          schema:
            type: number
            example: 101
        - name: place_id
          required: false
          in: query
          description: >-
            Place ID from destination autocomplete (type=place). Facets cover
            every hotel in the place subtree (e.g. all of Bali). Takes
            precedence over city_id/hotel_id.
          schema:
            example: 2930267
            type: number
        - name: hotel_id
          required: false
          in: query
          description: >-
            Hotel ID (bigint as string). Required if city_id not supplied.
            Server resolves the hotel's city and returns facets for that city.
          schema:
            example: '1892345'
            type: string
        - name: language
          description: Enter language code(ex. en)
          in: header
          schema: {}
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelFiltersResponseDto'
        '400':
          description: Bad request
        '404':
          description: Entity not found
components:
  schemas:
    HotelFiltersResponseDto:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Filters fetched successfully
        data:
          $ref: '#/components/schemas/HotelFiltersDataDto'
      required:
        - success
        - message
        - data
    HotelFiltersDataDto:
      type: object
      properties:
        city_id:
          type: object
          example: 101
          nullable: true
          description: Set for city/hotel-scoped facets; null for place-scoped.
        place_id:
          type: object
          example: 2930267
          nullable: true
          description: Set for place-scoped facets (subtree-wide counts); null otherwise.
        total_hotels:
          type: number
          example: 4021
        stars:
          type: array
          items:
            $ref: '#/components/schemas/FacetCountDto'
        price_range:
          $ref: '#/components/schemas/PriceRangeDto'
        property_types:
          type: array
          items:
            $ref: '#/components/schemas/FacetCountDto'
        chains:
          type: array
          items:
            $ref: '#/components/schemas/FacetCountDto'
        facilities:
          type: array
          items:
            $ref: '#/components/schemas/FacetCountDto'
        cached_until:
          type: string
          example: '2026-04-18T00:00:00.000Z'
      required:
        - city_id
        - place_id
        - total_hotels
        - stars
        - price_range
        - property_types
        - chains
        - facilities
        - cached_until
    FacetCountDto:
      type: object
      properties:
        value:
          type: object
          example: 5
        label:
          type: object
          example: Hotel
          nullable: true
        count:
          type: number
          example: 342
      required:
        - value
        - label
        - count
    PriceRangeDto:
      type: object
      properties:
        min_usd_cents:
          type: number
          example: 2000
          description: Min nightly unit price in USD cents.
        max_usd_cents:
          type: number
          example: 120000
          description: Max nightly unit price in USD cents.
      required:
        - min_usd_cents
        - max_usd_cents
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: Environment-specific API key created in the Unifystays portal

````