openapi: 3.0.0
info:
  title: Booking.com Autocomplete API
  description: |
    The Booking.com Autocomplete API turns a partial destination query into a ranked list of suggestions: cities, regions, countries, districts, airports, landmarks and individual properties. Each suggestion carries the identifiers needed to run a precise property search.

    **Cross-linking**: The `dest_id` and `dest_type` returned by this API can be passed to the Booking.com API as the `dest_id` and `dest_type` parameters to pin the search to that destination. A `hotel` suggestion is the exception: it does not return only that property, it searches the property's area with that property ranked first.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Booking.com Autocomplete
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["booking_autocomplete"]
        - name: q
          in: query
          required: true
          description: The partial or full destination text to autocomplete, up to 200 characters.
          schema:
            type: string
            maxLength: 200
        - name: num
          in: query
          required: false
          description: >-
            How many suggestions to return. Booking's own dropdown shows 5; the endpoint
            honours up to 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 5
        - name: language
          in: query
          required: false
          description: >-
            A hint for the language the titles and labels come back in. Booking resolves the
            language from the query itself, so this only applies where the query leaves it
            open: q=Parigi returns Italian whatever language says, and q=Paris returns English.
            It also affects which destinations Booking ranks into the list, not only their
            labels, so pin it when you need a stable suggestion set. en is accepted as an
            alias for en-us.
          schema:
            type: string
            enum: ["en-gb", "en-us", "de", "nl", "fr", "es", "es-ar", "ca", "it", "pt-pt", "pt-br", "no", "fi", "sv", "da", "cs", "hu", "ro", "ja", "zh-cn", "zh-tw", "pl", "el", "ru", "tr", "bg", "ar", "ko", "he", "lv", "uk", "id", "ms", "th", "et", "hr", "sk", "sr", "sl", "vi", "tl", "is", "lt", "en"]
            default: "en-us"
        - name: api_key
          in: query
          required: false
          description: Pass API key as query parameter
          schema:
            type: string
      responses:
        '200':
          description: >-
            Successful response. A prefix Booking has no destination for returns an empty
            suggestions array, not an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Timeout, or Booking answered but returned nothing usable (a rejection body, a
            malformed envelope, or suggestions carrying no destination id). The body is a
            bare {"error": ...} rather than a search response, and the search is not billed.
            A prefix that simply matched nothing is not this case — it is a 200 with an
            empty suggestions array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        suggestions:
          type: array
          description: >-
            The ranked suggestions for the prefix. Empty when Booking has no destination
            matching it.
          items:
            $ref: '#/components/schemas/Suggestion'
    Suggestion:
      type: object
      properties:
        position:
          type: integer
          description: The position of the suggestion in the list.
        dest_id:
          type: string
          description: The Booking destination id, usable as the dest_id parameter of the Booking.com API.
        city_id:
          type: string
          description: >-
            The destination's city id, in the same id space as dest_id. On a nested
            suggestion (hotel, landmark, district, airport) this is the enclosing city;
            on a `city` suggestion it repeats that city's own dest_id.
        properties_count:
          type: integer
          description: How many properties Booking lists for the destination.
        timezone:
          type: string
          description: The destination's IANA time zone, e.g. Europe/London.
        iata:
          type: string
          description: The IATA code, on airports and on cities with a primary airport.
        dest_type:
          type: string
          description: The type of the destination, usable as the dest_type parameter of the Booking.com API.
          enum: ["city", "region", "country", "district", "hotel", "airport", "landmark"]
        title:
          type: string
          description: The destination name.
        label:
          type: string
          description: The full display label for the destination.
        subtitle:
          type: string
          description: A secondary descriptor for the destination.
        country_code:
          type: string
          description: The ISO country code of the destination.
        latitude:
          type: number
          description: The latitude of the destination.
        longitude:
          type: number
          description: The longitude of the destination.
        thumbnail:
          type: string
          description: A thumbnail image URL for the destination.
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: "Unique identifier for the search request"
        status:
          type: string
          description: "Status of the search request"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the search was created"
        request_time_taken:
          type: number
          description: "Time taken to make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "Booking.com URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
        q:
          type: string
        num:
          type: integer
        language:
          type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong