> ## Documentation Index > Fetch the complete documentation index at: https://docs.tangoanalytics.com/llms.txt > Use this file to discover all available pages before exploring further. # Get current utilization for a given space set category in a building. > This request returns the current utilization for each `SpaceSet` with the given space set category in the given building. The response will always contain all `SpaceSets` matching these criteria. If no utilization was recorded for some `SpaceSet`, its utilization will be 'null'. A `SpaceSet` consists of `Spaces` which are on the same floor and have the same `SpaceType` and space attributes. The response contains all `SpaceSets`, including the ones which are hidden in the Locatee Analytics UI. In other words, the 'hidden' flag on the space attributes is ignored. This endpoint is only available for buildings with `SubscriptionPlan=Workplace`. ## OpenAPI ````yaml /tango_occupancy/integrations/guides/locatee-analytics-public-api.yaml get /public/api/analytics/v1/workplace/building/{buildingId}/utilization/current/space-set openapi: 3.1.0 info: title: Locatee Analytics Public API description: >- # Introduction Locatee provides a stable API for the Locatee Analytics data. The public API is a subset of Locatee's APIs but which underlies special stability guarantees. This document is the canonical OpenAPI documentation of the Locatee Analytics Public API. Anything which is not documented in this API should not be used by public API clients. # Compatibility ## Backward compatibility Wherever possible, we will maintain backward compatibility for REST resources and their representations. An API is backward compatible if a program written using one version of the API will continue to work the same way without modification when using future versions of the API. If we need to change a representation so that it is not backward compatible, we will create a new resource or media type using the new representation. In such cases, we will maintain the old resource or media type according to the deprecation policy described below. Such a change to a representation of a resource constitutes a version increment to the corresponding REST API(s). We may change the behavior of an API without warning if the existing behavior is incorrect or creates a security vulnerability. ## Stable URIs If a resource exists at a particular URI, that same resource will continue to exist with the same meaning in future versions. ### HTTP Response Codes * We do not change the meaning of HTTP response codes. For example, if a URI that used to return a 200 response returns a 404, you can know that the response indicates that the resource cannot be found, and not that the resource has been moved to another location. * We may add HTTP response codes when modifying a resource to refine availability or error responses. Such additions will not change the meaning of success or basic failure responses such as 200, 400, or 403 responses. * We may change a resource to return a "redirection" response code, e.g., 301 or 302, instead of returning the resource itself. Your client must handle HTTP-level redirects, and respect HTTP headers such as Location. The target resource for any redirect will be backward compatible with the original resource. ### Parameters and Data * If a resource begins to support more query parameters in future versions they will not be mandatory. The absence of a field value or a default value as appropriate behave as in prior versions. * If a resource accepts a representation, e.g., by POST or PUT, it will continue to accept the same representation in future versions. Any new fields that are accepted in a resource will not be mandatory. The default value assumed in their absence will maintain the previous meaning of the resource. ### Canonical URIs The canonical URI of a resource used in self links or used by other resources to point to the resource may change. ## Stable representations If we document a resource as available in a specific media type, e.g., using the Content-Type header, we will keep it available using that media type. If a resource returns a default media type in the absence of content negotiation, we will maintain that default. ### Structured JSON representations We further commit to the stability of resources with a media type of *application/json*. * We will maintain backward compatibility for key:value pairs in JSON objects. We will use the same name and return the same value type. * If the value of a field is an array, the type of the contents of the array will not change. The order of values in an array is significant. * If the value is an object, that object will meet the same compatibility guarantees as the document as a whole: * We may add new key:value pairs to a representation at any time, but the new pairs will not alter the meaning of existing pairs. * key:value within an object do not maintain a specific order and can change even for the same representation. * If a field exposes an URI, the resource identified by that URI will maintain the same compatibility guarantee. * We may add new values to the enumerations at any time, but new values will not change the documented field default values, if any exists. ## Values Not Included in Compatibility Policy The following are not covered by this compatibility policy: * resource and rate limits. * default and maximum sizes of paged data * default sorting behaviors The above items are not part of the API. They may change without warning. It is your responsibility to adhere to limits and behaviors as described in the API documentation or Contract details. Locatee is allowed to impose strict rate limits if a client shows abusive or term of service violating behavior. Structured representations of paged data and sorting behavior in API responses follow the policies described in the "Structured Representation" section of this document. # API versioning ## Version Increments Our APIs do not tag responses with their version number. The version is part of the URL used to call the API. We increment version numbers only for REST API endpoints affected by a particular change. The "expected" or "preferred" version of an API end-point is always the highest version of the endpoint. The existence of a higher-versioned endpoint implies that we have deprecated some aspect of the previous version of the endpoint or associated resource. Once a newer version of an API endpoint becomes available, we will mark any prior versions of the endpoint as deprecated. If we deprecate an API version, we will follow the policy laid out below. ## Forward compatibility An API is Forwards Compatible if a program written against one version of the API will also work the same way, without modification, against previous versions of the API. We make no guarantee of Forwards Compatibility in our REST APIs, but we provide the following non-normative guidelines about our approach to forwards compatibility. Where possible, we follow the Robustness Principle above. This means that the API will determine what to do with a request based only on the parts of that it recognises: * Request query parameters that are not recognised by the server will be ignored. * Expansion parameters that are not recognised by the server will be ignored. * Properties of structured (i.e. JSON) data submitted via mutative requests that are not recognised by the server will be ignored. # Deprecation ## Deprecation Policy This REST API deprecation policy is to be understood in conjunction with any other relevant deprecation policies. When there is a conflict of policy, the most restrictive policy applies. ## Announcements We make every effort to notify consumers about new deprecations through all relevant channels. This includes: * Deprecation and "since" annotations in REST API OpenAPI documentation * Announcements to the customers via their account teams * Announcements in the release notes ### Time frames Locatee Public REST APIs must be given reasonable notice of deprecations. Any deprecated REST API in the cloud environment MUST be available in its original form for at least 6 months, UNLESS there are critical security vulnerabilities or wrong behavior. ## Detectability Requests made to deprecated APIs return a header with the response to notify the consumer that the endpoint is deprecated. We use the warning header *Warning: 299 - 'Deprecated API; @since version'*. For more information, see [RFC-7234](https://tools.ietf.org/html/rfc7234#section-5.5). # Best Practices * You should not assume any constraints unless they are mentioned in the documentation. That is, even if the documented example is a number, you should not assume that the only possible response types are numeric unless so noted in the docs. * If a field property is not declared as mandatory in the API documentation, do not assume it will be present in responses. * Log the occurrence of any 299 response codes and periodically review the logs to plan for future app maintenance # Obtaining an Access Token This API uses OAuth2 with the clientCredentials grant flow, see [RFC-6749, section 4.4](https://tools.ietf.org/html/rfc6749#section-4.4). Locatee will provide you a clientID and clientSecret which you will need to create an access token with the standard oAuth2 clientCredential grant flow. Access tokens are valid for 3 hours and the API consumer is responsible for tracking access token expiration. To obtain a new access token, a new login using the clientCredentials grant flow can be used or the existing session can be prolonged using the refresh token flow, see [RFC-6749, section 6](https://tools.ietf.org/html/rfc6749#section-6). # Analytics data access Access to Analytics data may vary depending on your Public API subscription plan and which buildings have been enabled. If you are authenticated and receive a 403 response or truncated data, it is likely because you do not have complete access to the requested resource. For assistance managing your plan, contact support@locatee.com. contact: email: api@locatee.com version: 1.4.0 x-logo: url: /analytics/assets/Logo.svg servers: - url: https://{environment}.{customerId}.ch.locatee.com variables: environment: default: testing enum: - prod - uat - qa - testing description: The Locatee Analytics environment customerId: default: demo description: The Locatee assigned customer id. security: - oAuth2: [] tags: - name: Analytics - Static Data description: >- All operations related to static data like building information, floor plans, etc. - name: Analytics - Portfolio Overview description: >- All Analytics operations related to the Portfolio Overview feature of Locatee. - name: Analytics - Workplace Operations description: >- All Analytics operations related to the Workplace Operations feature of Locatee. - name: Ingress - Wireless Data description: >- All operations for pushing information from wireless network sources to Locatee. - name: Ingress - Sensor Data description: >- All operations for pushing information from sensor data sources to Locatee. - name: Ingress - Floor Utilization Data description: All operations for pushing floor utilization data to Locatee. - name: Ingress - Legacy description: All deprecated data input APIs. paths: /public/api/analytics/v1/workplace/building/{buildingId}/utilization/current/space-set: parameters: - name: buildingId in: path description: The unique ID of a building. required: true schema: type: integer format: int32 example: 6 - name: spaceSetCategory in: query description: The name of the space set category. The name is case sensitive. required: true schema: type: string example: Zones get: tags: - Analytics - Workplace Operations summary: Get current utilization for a given space set category in a building. description: >- This request returns the current utilization for each `SpaceSet` with the given space set category in the given building. The response will always contain all `SpaceSets` matching these criteria. If no utilization was recorded for some `SpaceSet`, its utilization will be 'null'. A `SpaceSet` consists of `Spaces` which are on the same floor and have the same `SpaceType` and space attributes. The response contains all `SpaceSets`, including the ones which are hidden in the Locatee Analytics UI. In other words, the 'hidden' flag on the space attributes is ignored. This endpoint is only available for buildings with `SubscriptionPlan=Workplace`. operationId: get-current-utilization-space-set responses: '200': description: Successful operation content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/spaceSetUtilizationContainer' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' security: - oAuth2: - public:analytics:read components: schemas: spaceSetUtilizationContainer: description: Contains utilization data for a list of `SpaceSets`. properties: building: $ref: '#/components/schemas/buildingWithFloors' spaceSets: type: array items: $ref: '#/components/schemas/spaceSetWithUtilization' buildingWithFloors: allOf: - $ref: '#/components/schemas/building' description: >- Building information along with information about all floors in that building. properties: floors: type: array items: $ref: '#/components/schemas/floor' spaceSetWithUtilization: description: >- A `SpaceSet` along with its utilization, i.e. the number of occupied desks, at a particular point in time. properties: spaceSet: $ref: '#/components/schemas/spaceSet' dateTime: type: string format: date-time nullable: true description: >- The time at which this utilization was observed. The timestamp will be in the timezone of the building where the space set is located. If there is no recorded utilization for this `SpaceSet`, the value will be 'null'. example: '2021-03-03T13:45:00+01:00' utilization: type: integer format: int32 nullable: true description: >- The number of occupied `Spaces` which are part of this `SpaceSet`. If there is no recorded utilization for this `SpaceSet`, the value will be 'null'. example: 4 building: description: Contains static information for a building. properties: id: deprecated: true type: integer format: int32 description: >- A unique identifier for a building. This is deprecated and will be replaced by `buildingId`. example: 6 buildingId: type: integer format: int32 description: A unique identifier for a building. example: 6 code: type: string description: The building code, as seen in the Locatee Analytics UI. example: 123 Example Av address: type: string description: The building address, as seen in the Locatee Analytics UI. example: Albisriederstrasse 243a, 8047 Zurich subscriptionPlan: $ref: '#/components/schemas/subscriptionPlan' geoCoordinates: $ref: '#/components/schemas/geoCoordinates' timezone: type: string example: Europe/Zurich required: - buildingId - subscriptionPlan - geoCoordinates - timezone floor: description: Contains static information for a floor. properties: floorId: type: integer format: int32 description: A unique identifier for a floor. example: 26 name: type: string description: The floor name, as seen in the Locatee Analytics UI. example: 1st Floor required: - floorId - name spaceSet: description: >- Contains static information for a collection of spaces which are on the same floor, have the same `SpaceType` and the same category. properties: spaceSetId: type: integer format: int32 description: A unique identifier of a space set. example: 10 name: type: string description: Name of the space set. example: NW701 floorId: type: integer format: int32 description: A unique identifier for a floor. example: 26 category: type: string description: The space set category. example: Zones spaceType: $ref: '#/components/schemas/spaceType' spaceCount: type: integer format: int32 description: The number of `Spaces` that are within the bounds of the `SpaceSet`. example: 99 subscriptionPlan: description: >- The `SubscriptionPlan` of a `Building`. Please refer to the endpoint tag to see if the endpoint is supported for a given `SubscriptionPlan`. Note that the `Workplace` subscription implies the `Portfolio` capabilities. However the reverse does not apply. type: string enum: - Portfolio - Advanced Portfolio - Workplace example: Workplace geoCoordinates: description: >- Describes the position on the surface of the Earth as latitude and longitude. Both the latitude and longitude are measured in degrees. properties: latitude: type: number format: double minimum: -90 maximum: 90 description: >- The latitude specifies the north-south position on the Earth's surface. example: 47.378466513404604 longitude: type: number format: double minimum: -180 maximum: 180 description: >- The longitude specifies the east–west position on the Earth's surface. example: 8.495144435276114 required: - latitude - longitude spaceType: description: The type of `Space` as seen in Locatee Analytics. type: string enum: - Desk - MeetingRoom - CollaborationSpace - Undefined x-enum-varnames: - Desk - MeetingRoom - CollaborationSpace - Undefined example: MeetingRoom responses: '400': description: Unexpected format of the request. '401': description: Invalid authentication for this resource. '500': description: Internal server error. securitySchemes: oAuth2: type: oauth2 description: >- This API uses OAuth 2 with the clientCredentials grant flow. [More info](https://tools.ietf.org/html/rfc6749#section-4.4) flows: clientCredentials: tokenUrl: >- https://auth.locatee.com/auth/realms/locatee-api/protocol/openid-connect/token scopes: public:analytics:read: read from analytics endpoints public:analytics:write: write to analytics endpoints public:ingress:write: write ingress data ````