> ## 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. # Sensor Based Location Presence Events > Send multiple sensor events. Send a sensor event for each presence count change (i.e. `3` to `4`) or before timeout occurs (specified by timeout parameter), whichever happens first. The sensor's presence count will be automatically reset to `0` after the specified or default timeout. The presenceCount takes precedence over the presenceState that has been deprecated ## OpenAPI ````yaml /tango_occupancy/integrations/guides/locatee-analytics-public-api.yaml post /public/api/ingress/v2/location/sensor/presence 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/ingress/v2/location/sensor/presence: post: tags: - Ingress - Sensor Data summary: Sensor Based Location Presence Events description: >- Send multiple sensor events. Send a sensor event for each presence count change (i.e. `3` to `4`) or before timeout occurs (specified by timeout parameter), whichever happens first. The sensor's presence count will be automatically reset to `0` after the specified or default timeout. The presenceCount takes precedence over the presenceState that has been deprecated operationId: post-location-sensor-event requestBody: content: application/json: schema: $ref: '#/components/schemas/sensorPresenceContainer' required: true responses: '200': $ref: '#/components/responses/200' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '500': $ref: '#/components/responses/500' security: - ApiKeyAuth: [] components: schemas: sensorPresenceContainer: type: array items: $ref: '#/components/schemas/sensorPresence' sensorPresence: type: object description: Represents a single sensor event. allOf: - $ref: '#/components/schemas/presenceBase' - type: object properties: sensorRef: type: string description: The unique case-sensitive sensor identifier. example: WDYIS-12312-A12 required: - sensorRef presenceBase: type: object description: >- Represents basic information about the presence of a device or people. This component should not be used on its own - rather, use the components which extend it. properties: eventID: type: string maxLength: 36 description: The ID of the event generated by the originating system. presenceState: $ref: '#/components/schemas/presenceState' presenceCount: type: integer format: int32 description: >- The total number of connected devices (network connectivity) or detected people (sensors). For wireless presence events, the `presenceCount` is expected to be `1` if the client device is connected to the network and `0` if the client device is disconnected. For sensor events, the `presenceCount` is expected to be `1` if the sensor detects a person's presence. For people-counting sensors, the `presenceCount` is expected to be the number of detected people by the sensor. example: 1 measuredAt: type: string format: date-time description: When this event had occurred. example: '2018-10-07T08:32:03Z' timeout: type: integer description: >- Timeout in seconds until the presence count will reset to `0`. The default value of timeout is 15min (900s). Ideal value is 2 times the readout frequency if `0` presenceCount events do not exist in the source system. example: 600 default: 900 required: - eventID - measuredAt presenceState: type: string deprecated: true description: Describes the presence of the client device. enum: - PRESENT - ABSENT example: PRESENT responses: '200': description: Successful Operation '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 ApiKeyAuth: type: http scheme: bearer ````