Locations API

openapi: 3.2.0
info:
  title: Locations API
  contact:
    name: DoIT Enterprise Business Systems (EBS) Integrated Business Solutions (IBS) API Team
    email: locations-api@doit.wisc.edu
  description: An API for accessing UW location data.
  version: 1.0.0
servers:
- url: https://api.wisc.edu
  description: Production server
security:
- OAuth2ClientCredentials: []
tags:
- name: Locations
paths:
  /locations:
    get:
      summary: Get a list of locations
      description: Retrieve a paginated list of UW locations with optional filters and search.
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/GenericFilter'
      - name: filter[active]
        in: query
        description: Get locations with exact matches in the `active` attribute
        schema:
          type: boolean
      - name: filter[addresses.isPrimary]
        in: query
        description: Get locations with exact matches in the `addresses.isPrimary` attribute
        schema:
          type: boolean
      - name: filter[addresses.country]
        in: query
        description: Get locations with exact matches in the `addresses.country` attribute
        schema:
          type: string
      - name: filter[addresses.line1]
        in: query
        description: Get locations with exact matches in the `addresses.line1` attribute
        schema:
          type: string
      - name: filter[addresses.municipality]
        in: query
        description: Get locations with exact matches in the `addresses.municipality` attribute
        schema:
          type: string
      - name: filter[addresses.postalCode]
        in: query
        description: Get locations with exact matches in the `addresses.postalCode` attribute
        schema:
          type: string
      - name: filter[addresses.region]
        in: query
        description: Get locations with exact matches in the `addresses.region` attribute
        schema:
          type: string
      - name: filter[addresses.regionDescriptor]
        in: query
        description: Get locations with exact matches in the `addresses.regionDescriptor` attribute
        schema:
          type: string
      - name: filter[addresses.regionSubdivision]
        in: query
        description: Get locations with exact matches in the `addresses.regionSubdivision` attribute
        schema:
          type: string
      - name: filter[addresses.regionSubdivisionDescriptor]
        in: query
        description: Get locations with exact matches in the `addresses.regionSubdivisionDescriptor` attribute
        schema:
          type: string
      - name: filter[addresses.usages]
        in: query
        description: Get locations with exact matches in the `addresses.usages` attribute
        schema:
          type: string
      - name: filter[buildingName]
        in: query
        description: Get locations with exact matches in the `buildingName` attribute
        schema:
          type: string
      - name: filter[buildingNumber]
        in: query
        description: Get locations with exact matches in the `buildingNumber` attribute
        schema:
          type: string
      - name: filter[workdayCreatedOn]
        in: query
        description: Get locations with exact matches in the `workdayCreatedOn` attribute
        schema:
          type: string
      - name: filter[workdayDateOfLastChange]
        in: query
        description: Get locations with exact matches in the `workdayDateOfLastChange` attribute
        schema:
          type: string
      - name: filter[fullName]
        in: query
        description: Get locations with exact matches in the `fullName` attribute
        schema:
          type: string
      - name: filter[hierarchyId]
        in: query
        description: Get locations with exact matches in the `hierarchyId` attribute
        schema:
          type: string
      - name: filter[inactiveDate]
        in: query
        description: Get locations with exact matches in the `inactiveDate` attribute
        schema:
          type: string
      - name: filter[referenceId]
        in: query
        description: Get locations with exact matches in the `referenceId` attribute
        schema:
          type: string
      - name: filter[roomName]
        in: query
        description: Get locations with exact matches in the `roomName` attribute
        schema:
          type: string
      - name: filter[roomNumber]
        in: query
        description: Get locations with exact matches in the `roomNumber` attribute
        schema:
          type: string
      - name: filter[superiorBranchCampusId]
        in: query
        description: Get locations with exact matches in the `superiorBranchCampusId` attribute
        schema:
          type: string
      - name: filter[superiorBuildingId]
        in: query
        description: Get locations with exact matches in the `superiorBuildingId` attribute
        schema:
          type: string
      - name: filter[superiorCampusId]
        in: query
        description: Get locations with exact matches in the `superiorCampusId` attribute
        schema:
          type: string
      - name: filter[superiorFloorId]
        in: query
        description: Get locations with exact matches in the `superiorFloorId` attribute schema
        schema:
          type: string
      - name: filter[superiorLocationId]
        in: query
        description: Get locations with exact matches in the `superiorLocationId` attribute
        schema:
          type: string
      - name: filter[type]
        in: query
        description: Get locations of a given `type`. See the [Types documentation](https://locationsapi.wisc.edu/documentation/endpoints/types/) for a list of values.
        schema:
          type: string
      - name: search
        in: query
        description: Text search across string location fields. See the Search Query Parameter documentation in the [Overview](/docs/locations-api/1/overview) for more information.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Location'
                  links:
                    $ref: '#/components/schemas/Links'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '302':
          $ref: '#/components/responses/CSVRedirect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
      - Locations
      operationId: getLocations
      x-operation-id-source: derived
  /locations/usages:
    get:
      summary: Get a list of location usages
      description: Retrieve a list of all possible location usages.
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/GenericFilter'
      - name: filter[name]
        in: query
        description: Get usages with exact matches in the `name` attribute. See the [Usages documentation](https://locationsapi.wisc.edu/documentation/endpoints/usages/) for a list of values.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Usage'
                  links:
                    $ref: '#/components/schemas/Links'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '302':
          $ref: '#/components/responses/CSVRedirect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
      - Locations
      operationId: getLocationsUsages
      x-operation-id-source: derived
  /locations/types:
    get:
      summary: Get a list of location types
      description: Retrieve a list of all possible location types.
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/PageNumber'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/GenericFilter'
      - name: filter[name]
        in: query
        description: Get types with exact matches in the `name` attribute. See the [Types documentation](https://locationsapi.wisc.edu/documentation/endpoints/types/) for a list of values.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Type'
                  links:
                    $ref: '#/components/schemas/Links'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '302':
          $ref: '#/components/responses/CSVRedirect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
      - Locations
      operationId: getLocationsTypes
      x-operation-id-source: derived
components:
  schemas:
    Location:
      type: object
      properties:
        active:
          type: boolean
          example: true
        addresses:
          description: The addresses associated with the location.
          type: array
          items:
            $ref: '#/components/schemas/Address'
        buildingName:
          type:
          - string
          - 'null'
          example: Blue Gym
        buildingNumber:
          type:
          - string
          - 'null'
          example: '2345'
        workdayCreatedOn:
          type: string
          format: date
          example: 2025-05-26
        workdayLastModifiedOn:
          type: string
          format: date
          example: 2025-08-01
        hierarchyId:
          type: string
          example: LH_UWTST
        inactiveDate:
          type:
          - string
          - 'null'
          format: date
          example: 2025-08-01
        referenceId:
          type: string
          example: LCTST_2345_01_5555
        fullName:
          description: The name assigned to the location with IDs appended.
          type: string
          example: Blue Gym-2345-01-5555
        roomName:
          type:
          - string
          - 'null'
          example: Wingra Training Room
        roomNumber:
          type:
          - string
          - 'null'
          example: '5555'
        superiorBranchCampusId:
          type:
          - string
          - 'null'
          example: LCTST_BRN
        superiorBuildingId:
          type:
          - string
          - 'null'
          example: LCTST_2345
        superiorCampusId:
          type:
          - string
          - 'null'
          example: LCTST
        superiorFloorId:
          type:
          - string
          - 'null'
          example: '01'
        superiorLocationId:
          type:
          - string
          - 'null'
          example: LCTST_2345_01
        type:
          description: 'The type of the location. See the [Types documentation](https://locationsapi.wisc.edu/documentation/endpoints/types/) for more information.

            '
          type: string
          example: Room
        usages:
          description: 'How the space is intended to be used. See the [Usages documentation](https://locationsapi.wisc.edu/documentation/endpoints/usages/) for more information.

            '
          type: array
          example:
          - WORK SPACE
          - BUSINESS ASSET
          items:
            $ref: '#/components/schemas/Usage'
    CSVRedirectResponse:
      description: 'Information on the CSV response. Triggered by setting the `Accept` header to `text/csv`.

        '
      type: object
      properties:
        message:
          description: Human-readable information about the response.
          type: string
          example: Your file is available from the following download link.
        status:
          description: The HTTP code of the response.
          type: integer
          example: 302
        url:
          description: 'The URL the CSV can be downloaded from. Note that this URL is only valid for 15 minutes, and attempting to access it after it expires will return an error.

            '
          type: string
          format: uri
          example: https://example.com/00000000-0000-0000-0000-000000000000.csv?signature=123456
      example:
        message: Your file is available from the following download link.
        status: 302
        url: https://example.com/00000000-0000-0000-0000-000000000000.csv?signature=123456
    Type:
      description: 'The type of a location. See the [Types documentation](https://locationsapi.wisc.edu/documentation/endpoints/types/) for more information.

        '
      type: object
      properties:
        name:
          type: string
          example: Building
    Meta:
      description: Information about the response's pagination.
      type: object
      properties:
        totalCount:
          description: The total number of items in the result set.
          type: integer
          example: 1000
        page:
          type: object
          properties:
            number:
              description: The requested page number.
              type: integer
              example: 1
            size:
              description: The requested page size.
              type: integer
              example: 100
    Usage:
      description: 'How a space is intended to be used. See the [Usages documentation](https://locationsapi.wisc.edu/documentation/endpoints/usages/) for more information.

        '
      type: object
      properties:
        name:
          type: string
          example: BUSINESS SITE
    Links:
      description: Pagination links.
      type: object
      properties:
        nextPage:
          description: The next page of data.
          type:
          - string
          - 'null'
          format: uri
          example: https://api.wic.edu/locations?page[number]=3&page[size]=100
        prevPage:
          description: The previous page of data.
          type:
          - string
          - 'null'
          format: uri
          example: https://api.wisc.edu/locations?page[number]=1&page[size]=100
        firstPage:
          description: The first page of data.
          type: string
          format: uri
          example: https://api.wisc.edu/locations?page[number]=1&page[size]=100
        lastPage:
          description: The last page of data.
          type: string
          format: uri
          example: https://api.wisc.edu/locations?page[number]=1892&page[size]=100
    Address:
      type: object
      properties:
        isPrimary:
          description: Whether the address is the primary address of the location. If a location has multiple addresses, this should only be true for one of them.
          type: boolean
          example: true
        country:
          type: string
          example: USA
        line1:
          description: Line 1 of the address.
          type: string
          example: 879 Faux Circle
        municipality:
          type: string
          example: Stateville
        postalCode:
          type: string
          example: 54401-5362
        region:
          description: The region within the country. This is usually the state's postal abbreviation.
          type: string
          example: WI
        regionDescriptor:
          description: The descriptive name of the region within the country. This is usually the state's unabbreviated name.
          type: string
          example: Wisconsin
        regionSubdivision:
          description: The subdivision within the region. This is usually a county name, but can be null if it splits multiple subdivisions (i.e. the boundaries extend into multiple counties).
          type: string
          example: Dane
        regionSubdivisionDescriptor:
          description: The type of the subdivision within the region. This is usually just "County", or null if it splits multiple subdivisions.
          type: string
          example: County
        usages:
          description: 'How the address is intended to be used. Note that usages are not guaranteed to be unique among a location''s addresses, e.g. a location could have multiple shipping and street addresses.

            '
          type: array
          example:
          - SHIPPING
          - BUSINESS
          items:
            $ref: '#/components/schemas/Usage'
  responses:
    CSVRedirect:
      description: 'Redirect to a URL to download a CSV response. Triggered by setting the `Accept` header to `text/csv`.

        '
      headers:
        Location:
          description: The URL to download a CSV with the query results.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CSVRedirectResponse'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Bad Request
              message:
                type: string
                example: Invalid parameter or request.
              status:
                type: integer
                example: 400
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Rate limit exceeded. Try again later.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Authentication failed. Invalid or missing API key.
  parameters:
    Accept:
      name: Accept
      in: header
      description: 'The response format. For `application/json`, nothing changes, as the API defaults to JSON responses. For `text/csv`, the response will be serialized as a CSV and uploaded to AWS S3. See the CSV Output documentation in the [Overview](/docs/locations-api/1/overview) for more information.

        '
      required: false
      schema:
        type: string
        default: application/json
        enum:
        - application/json
        - text/csv
    PageSize:
      name: page[size]
      in: query
      description: Number of records per page
      schema:
        type: integer
        default: 100
    GenericFilter:
      name: filter
      in: query
      description: Filter query results on the specified attribute. See the Filter Query Parameter documentation in the [Overview](/docs/locations-api/1/overview) for more information.
      required: false
      style: deepObject
      explode: true
      examples:
        basicEquality:
          description: Filtering a field using basic equality.
          value: filter[addresses.line1]=100 Main St
        specialOperatorBetween:
          description: Filtering a field using the "between" operator.
          value: filter[workdayCreatedOn:between]=2020-01-01,2022-01-01
        specialOperatorGreaterThan:
          description: Filtering a field using the "greaterThan" operator.
          value: filter[workdayDateOfLastChange:greaterThan]=2020-01-01
      schema:
        type: object
        additionalProperties: false
        properties:
          attributeAndOperator:
            description: The name of the attribute and (if needed) the special operator being used on it. If a special operator is in use, it is separated from the attribute name with a `:`.
            type: string
            example: addresses.line1
            pattern: ^(?<attributeName>[^:]+)(?::(?<specialOperator>.+))?$
    PageNumber:
      name: page[number]
      in: query
      description: Page number for pagination
      schema:
        type: integer
        default: 1
  securitySchemes:
    OAuth2ClientCredentials:
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.wisc.edu/oauth/token
      type: oauth2