> ## 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 the daily peak for all buildings. > This request will return the peak utilization for a specific date for all buildings in the portfolio. The date should be specified as a query parameter. The date is interpreted from the point of view of the building. Only the measurements within office hours and during workdays are used for the peak utilization. The queried date is expected to be in the past, i.e. the most recent date that can be queried is yesterday. If a building has not finished the queried date yet, it will have 'null' peak utilization. If there is no data for a building for the queried date, it will also have 'null' peak utilization. Please note that a building in Sydney (UTC+11) might already have data for 2020-10-20, while at that time another building in Honolulu (UTC-10) will still be collecting data (and return 'null'). This endpoint is available to all `SubscriptionPlans`. ## OpenAPI ````yaml /tango_occupancy/integrations/guides/locatee-analytics-public-api.yaml get /public/api/analytics/v1/portfolio/daily-peak 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/portfolio/daily-peak: get: tags: - Analytics - Portfolio Overview summary: Get the daily peak for all buildings. description: >- This request will return the peak utilization for a specific date for all buildings in the portfolio. The date should be specified as a query parameter. The date is interpreted from the point of view of the building. Only the measurements within office hours and during workdays are used for the peak utilization. The queried date is expected to be in the past, i.e. the most recent date that can be queried is yesterday. If a building has not finished the queried date yet, it will have 'null' peak utilization. If there is no data for a building for the queried date, it will also have 'null' peak utilization. Please note that a building in Sydney (UTC+11) might already have data for 2020-10-20, while at that time another building in Honolulu (UTC-10) will still be collecting data (and return 'null'). This endpoint is available to all `SubscriptionPlans`. operationId: get-daily-portfolio-peaks parameters: - name: date in: query required: true schema: type: string format: date example: '2020-10-20' description: >- The date for which the peak utilization is requested. The expected format is YYYY-MM-DD. responses: '200': description: Successful operation content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/portfolioDailyPeaks' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' security: - oAuth2: - public:analytics:read components: schemas: portfolioDailyPeaks: description: >- Contains all buildings in the portfolio and their respective daily peaks. properties: buildingDailyPeaks: type: array items: $ref: '#/components/schemas/buildingDailyPeak' buildingDailyPeak: description: Describes a daily peak of the building's utilization. properties: building: $ref: '#/components/schemas/building' date: type: string format: date description: The date when this building peak was observed. example: '2020-10-20' buildingCapacity: type: integer format: int32 description: >- Customer-supplied maximum capacity of the building. Measured as number of people in the building at the same time. example: 1000 targetUtilizationPercent: type: number format: double minimum: 0 maximum: 1 description: >- Customer-supplied targeted utilization of the building. Measured as a percentage, relative to the building capacity. The percentage is in the form of a decimal number from 0 (0%) to 1 (100%). example: 0.15 targetUtilization: type: integer format: int32 description: >- The targeted utilization of the building, measured as number of people in the building at the same time. Computed by rounding down the product of the configured target utilization percent and the building capacity. example: 150 peakUtilization: type: integer nullable: true description: >- The largest number of people that have been in the building at the same time. This value will be 'null' if there's no data for the queried date or the queried date has not finished yet for this building. example: 120 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 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 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 ````