Hong Kong University of Science and Technology Nodes API

openapi: 3.2.0
info:
  title: HKUST Path Advisor Nodes API
  version: '1.0'
  description: Public, keyless JSON API behind HKUST Path Advisor, the university's indoor/outdoor campus wayfinding service at https://pathadvisor.ust.hk.
  contact:
    name: HKUST Information Technology Services Office
    url: https://itso.hkust.edu.hk/
  x-operator: institution
  x-artifact-provenance:
    generated: '2026-08-30'
    method: probed
    source: Live unauthenticated GET probes against https://pathadvisor.ust.hk/api on 2026-08-30. Endpoints confirmed by a 200 or a distinguishing non-generic error; the service returns a generic 400 {"error":{"message":"Bad request"}} for unknown routes, so only 200 and 401 responses were treated as proof a route exists.
servers:
- url: https://pathadvisor.ust.hk/api
  description: Production. CORS Access-Control-Allow-Origin *; HSTS; nginx. No API key required.
tags:
- name: Nodes
  description: Named map features with GeoJSON footprints.
paths:
  /nodes:
    get:
      tags:
      - Nodes
      operationId: searchNodes
      summary: Search map nodes by name
      description: Searches named campus features. The `name` parameter is REQUIRED — every observed request without it returned 400 with the distinguishing message "Empty query is not allowed", including requests that supplied only floorId. Matching is substring and case-insensitive against the node name.
      parameters:
      - name: name
        in: query
        required: true
        description: Substring matched against the node name. Required.
        schema:
          type: string
        example: lift
      - name: floorId
        in: query
        required: false
        description: Observed accepted alongside `name`; narrows results to one floor.
        schema:
          type: string
        example: '1'
      - name: limit
        in: query
        required: false
        description: Observed accepted; caps the number of returned nodes.
        schema:
          type: integer
          minimum: 1
        example: 2
      - name: sortBy
        in: query
        required: false
        description: Observed accepted without error. Ordering effect not verified.
        schema:
          type: string
        example: name
      responses:
        '200':
          description: Matching nodes.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Node'
        '400':
          description: The required `name` query parameter was absent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  message: Empty query is not allowed
  /nodes/{nodeId}:
    get:
      tags:
      - Nodes
      operationId: getNode
      summary: Get one map node
      parameters:
      - name: nodeId
        in: path
        required: true
        description: Node identifier as returned in Node._id.
        schema:
          type: string
        example: 0W9Lglf39vxh
      responses:
        '200':
          description: Node.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/Node'
        '400':
          $ref: '#/components/responses/BadRequest'
  /connectors:
    get:
      tags:
      - Nodes
      operationId: listConnectors
      summary: List floor connectors (authorization required)
      description: 'Vertical circulation between floors — lifts, stairs, escalators. Unlike every other route observed on this API, this one is gated: an unauthenticated request returns 401 {"error":{"message":"Authorization failed"}}. HKUST publishes no documentation for how that authorization is obtained, so the scheme is recorded as observed-but-unspecified and is deliberately NOT guessed at here.'
      responses:
        '200':
          description: Connector list. Shape not observed — the route is gated.
        '401':
          description: Unauthenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  message: Authorization failed
components:
  schemas:
    Error:
      type: object
      description: Error envelope used by every failing route observed.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              example: Bad request
    Node:
      type: object
      description: A named feature on a floor plan, with a point coordinate and a GeoJSON MultiPolygon footprint in the same floor-plan pixel coordinate space.
      required:
      - _id
      - name
      - floorId
      properties:
        _id:
          type: string
          example: 0W9Lglf39vxh
        name:
          type: string
          example: LIFT 1
        floorId:
          type: string
          description: References Floor._id.
          example: LSK3
        coordinates:
          type: array
          description: '[x, y] anchor point in floor-plan pixel space.'
          items:
            type: number
          minItems: 2
          maxItems: 2
          example:
          - 11
          - 18
        centerCoordinates:
          type: array
          description: '[x, y] centroid of the footprint.'
          items:
            type: number
          minItems: 2
          maxItems: 2
          example:
          - 22
          - 11
        connectorId:
          type: string
          description: Present when the node is vertical circulation; groups the same lift or stairwell across floors. Detail is served by the gated /connectors route.
          example: LIFT LSK1
        geoLocs:
          $ref: '#/components/schemas/MultiPolygon'
    MultiPolygon:
      type: object
      description: GeoJSON MultiPolygon geometry (RFC 7946 shape). Coordinates are floor-plan pixels, not WGS84 degrees — convert with Floor.meterPerPixel and Floor.startX/startY.
      required:
      - type
      - coordinates
      properties:
        type:
          type: string
          enum:
          - MultiPolygon
        coordinates:
          type: array
          items:
            type: array
            items:
              type: array
              items:
                type: number
                minItems: 2
                maxItems: 2
  responses:
    BadRequest:
      description: Generic rejection. This API returns the same 400 body for a malformed request and for a route that does not exist, so a 400 is not evidence either way.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              message: Bad request