openapi: 3.2.0
info:
  title: CoworkingView Search API
  version: 1.0.0
  description: 'Read API for the CoworkingView catalogue plus the lead write path. Within a major version this contract is APPEND-ONLY: fields are added, never removed or retyped, because clients include mobile builds that cannot be recalled. A breaking change means /v2, with /v1 kept alive for at least two app releases.'
servers:
- url: https://api.coworkingview.com
  description: Production
- url: http://localhost:4000
  description: Local development
tags:
- name: Search
paths:
  /v1/search/suggest:
    get:
      operationId: searchSuggest
      summary: City, zone, operator and property autocomplete
      description: Autocomplete across cities, zones, operators and individual spaces. Pass a short query string; results include the type and the slug to follow up with listProperties or propertyDetail. No API key.
      tags:
      - Search
      parameters:
      - name: locale
        in: query
        required: true
        schema:
          type: string
          enum:
          - en
          - de
          - es
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: limit
        in: query
        required: false
        schema:
          default: 8
          type: integer
          exclusiveMinimum: 0
          maximum: 20
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        kind:
                          type: string
                          enum:
                          - country
                          - city
                          - zone
                          - operator
                          - property
                        slug:
                          type: string
                          minLength: 1
                          maxLength: 200
                          pattern: ^[a-z0-9-]+$
                        label:
                          type: string
                        sublabel:
                          type: string
                        center:
                          type: object
                          properties:
                            lat:
                              type: number
                            lng:
                              type: number
                          required:
                          - lat
                          - lng
                          additionalProperties: false
                        propertyCount:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                      required:
                      - kind
                      - slug
                      - label
                      additionalProperties: false
                  meta:
                    type: object
                    properties:
                      contractVersion:
                        type: string
                      pagination:
                        type: object
                        properties:
                          page:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          pageSize:
                            type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          total:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          pageCount:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                        required:
                        - page
                        - pageSize
                        - total
                        - pageCount
                        additionalProperties: false
                      truncated:
                        type: boolean
                      seed:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                    required:
                    - contractVersion
                    - pagination
                    additionalProperties: false
                required:
                - data
                - meta
                additionalProperties: false
        '400':
          description: VALIDATION_FAILED
          content:
            application/problem+json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    minimum: 400
                    maximum: 599
                  detail:
                    type: string
                  code:
                    type: string
                    enum:
                    - VALIDATION_FAILED
                    - NOT_FOUND
                    - RATE_LIMITED
                    - CHALLENGE_FAILED
                    - UPSTREAM_UNAVAILABLE
                    - INTERNAL_ERROR
                    - CLIENT_TOO_OLD
                    - IDEMPOTENCY_KEY_CONFLICT
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                      required:
                      - path
                      - message
                      additionalProperties: false
                  traceId:
                    type: string
                required:
                - type
                - title
                - status
                - code
                additionalProperties: false
        '429':
          description: RATE_LIMITED
          content:
            application/problem+json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    minimum: 400
                    maximum: 599
                  detail:
                    type: string
                  code:
                    type: string
                    enum:
                    - VALIDATION_FAILED
                    - NOT_FOUND
                    - RATE_LIMITED
                    - CHALLENGE_FAILED
                    - UPSTREAM_UNAVAILABLE
                    - INTERNAL_ERROR
                    - CLIENT_TOO_OLD
                    - IDEMPOTENCY_KEY_CONFLICT
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                      required:
                      - path
                      - message
                      additionalProperties: false
                  traceId:
                    type: string
                required:
                - type
                - title
                - status
                - code
                additionalProperties: false
        '500':
          description: INTERNAL_ERROR
          content:
            application/problem+json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    minimum: 400
                    maximum: 599
                  detail:
                    type: string
                  code:
                    type: string
                    enum:
                    - VALIDATION_FAILED
                    - NOT_FOUND
                    - RATE_LIMITED
                    - CHALLENGE_FAILED
                    - UPSTREAM_UNAVAILABLE
                    - INTERNAL_ERROR
                    - CLIENT_TOO_OLD
                    - IDEMPOTENCY_KEY_CONFLICT
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                      required:
                      - path
                      - message
                      additionalProperties: false
                  traceId:
                    type: string
                required:
                - type
                - title
                - status
                - code
                additionalProperties: false
        '502':
          description: UPSTREAM_UNAVAILABLE
          content:
            application/problem+json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                    minimum: 400
                    maximum: 599
                  detail:
                    type: string
                  code:
                    type: string
                    enum:
                    - VALIDATION_FAILED
                    - NOT_FOUND
                    - RATE_LIMITED
                    - CHALLENGE_FAILED
                    - UPSTREAM_UNAVAILABLE
                    - INTERNAL_ERROR
                    - CLIENT_TOO_OLD
                    - IDEMPOTENCY_KEY_CONFLICT
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        message:
                          type: string
                      required:
                      - path
                      - message
                      additionalProperties: false
                  traceId:
                    type: string
                required:
                - type
                - title
                - status
                - code
                additionalProperties: false
      x-cache:
        maxAge: 300
        staleWhileRevalidate: 3600