# Occuspace The simplest way to collect and act on occupancy measurement data Occuspace brings the power of Web analytics to the physical world by continuously measuring how people move through and use the environment around them. Our focus is to make it simple for you to understand how your spaces are utilized, giving you actionable, high quality data to make decisions to improve your visitor experience, save you money, and accomplish your business goals. This documentation is the primary source of online support information about our data and service. Below are a series of guides to assist you from the setup of your installation to understanding your data and using it to accomplish your space planning, management, and utilization goals. {% content-ref url="/pages/LfQQrFygL6F1YnmSCokW" %} [Getting Started](/guides/getting-started) {% endcontent-ref %} {% content-ref url="/pages/FH0gKnMJyFfWwqlE7ol2" %} [The Occuspace Portal](/guides/the-occuspace-portal) {% endcontent-ref %} {% content-ref url="/pages/RGqk3pDYm6looGGgEl8S" %} [Setting Up Occuspace](/guides/setting-up-occuspace) {% endcontent-ref %} {% content-ref url="/pages/yRTi9gcOcCX0QKqKvEcQ" %} [Understanding Your Data](/guides/understanding-your-data) {% endcontent-ref %} {% content-ref url="/pages/9CxJQtpJgGk38dvc1hh6" %} [Using Live Data](/guides/using-live-data) {% endcontent-ref %} ## Technology {% content-ref url="/pages/Gp3A5VnAVbWN4M2sP2Wk" %} [Summary](/technology/summary) {% endcontent-ref %} {% content-ref url="/pages/IFWoHX0QrBog1BQJU5vO" %} [Hardware Specifications](/technology/hardware-specifications) {% endcontent-ref %} {% content-ref url="/pages/tC9bhUUlDS5wehU03KxT" %} [Network Specifications](/technology/network-specifications) {% endcontent-ref %} {% content-ref url="/pages/eArecx97v6nKABpYsSXr" %} [Privacy & Security](/technology/privacy-and-security) {% endcontent-ref %} # Getting Started A quick run-through of how to get started with Occuspace Occuspace provides space behavior insights to our customers from raw data gathered by our proprietary hardware sensors that are installed in the spaces being measured. Getting these sensors properly configured and installed is a very simple and quick process which is briefly summarized in the three steps below. ### Step 1 - Configuration (Understanding & Defining Your Space) The first step is for Occuspace to understand the various spaces that you wish to measure with our platform. This can be done during an introductory call with our business team. Typically you send us floor plans of the relevant areas so that we can understand your goals, identify how many of our sensors are needed to adequately cover the space, and in which specific locations they should be placed.
An example of floor plan showing the desired coverage areas

An example of a floor plan showing the two desired coverage areas for Occuspace measurement

{% hint style="info" %} Occuspace uses a variety of different terminology to describe the service and the setup and installation process. A helpful glossary of these terms and their descriptions is available [here](/glossary). {% endhint %} After understanding your coverage needs and reviewing the floor plans we determine the total number of sensors needed and the optimal placement locations. The main considerations are power availability and network connectivity. Our sensors can be easily plugged into wall AC power outlets and also can be powered over Ethernet (PoE). The floor plan is typically marked up with the sensor placement information and provided back to you for review and approval. ![A floor plan marked up with the placement locations for the sensors](/files/T7HiZ7bJ050F2yX8iJ95) {% hint style="info" %} The marked-up floor plan is meant to guide the total number of sensors needed and the optimal locations for installation, but our sensors do not need to be installed exactly as shown. Sensors have some flexibility if they need to be moved for a number of reasons that might come up during installation (e.g. non-working power outlet). Our team works with you through this process to find replacement locations and ensure that Occuspace has adequate coverage to provide high quality data. {% endhint %} Once the floor plans are approved and the contract paperwork is signed we are ready to move onto the setup and installation phase. You can decide to move forward with a self-installation where we ship you the sensors and you plug them in yourself (it's easy and fast to do it yourself), or with a professional installation done by the Occuspace team. ### Step 2 - Setup & Installation During the setup and installation phase we work with you to get your sensors properly configured and installed in your space. Whether you install them yourself using our self-service [Occuspace Portal](/guides/the-occuspace-portal), or you chose to have us do a professional installation, the general steps are the same: 1. **Network Connectivity Setup** - Our sensors need to transmit data regularly to our cloud infrastructure and need to be connected to the Internet. We support connectivity via WiFi and Ethernet. If you are using WiFi our support team will work with you to understand how best to securely connect our sensors to your network, obtain the proper credentials and configuration, etc. (we support a wide range of WiFi encryption standards to handle nearly any situation). 2. **Sensors Provisioned & Shipped** - The next step is to ship you the required number of sensors for the space you are measuring. If you are using WiFi for connectivity the sensors will come provisioned to automatically connect to your network when they are powered up with the credentials you provided during the network setup step above. 3. **Sensor Installation** - Once the sensors are received at your location the final step in this phase is to walk around your space and install the sensors in the locations defined by the marked up floor plan. Installation is as simple as plugging a sensor into a standard power wall receptacle (or power can be provided by PoE), waiting for it to power up, and then associating the sensor ID with the specific location of the floor plan. This can be done in seconds using the Occuspace Portal, or will be handled by our staff if you are doing a professional installation. {% hint style="info" %} Setup is very easy and simple, and requires no custom electrical work that would involve an electrician or other general contractor. {% endhint %} ### Step 3 - Space Calibration The final phase of the process is to tune the Occuspace software platform to your specific space and occupancy behaviors. This is done by providing a few "head counts" where the number of people in your space is recorded at different occupancy levels and those counts are provided to Occuspace. This data acts as a truth set that is used to calibrate the machine learning models that provide your final space utilization data. We typically ask for 7-10 head counts to be made over the week after installation of the sensors. These counts should occur at different levels of occupancy (i.e when the space is busy, when it is not busy, etc.). They can be easily submitted via the Customer Portal, or in a professional install our team will handle. Once these head counts have been provided and our sensors have monitored your space for a week, Occuspace finalizes the calibration and your occupancy data is unlocked in the Customer Portal and any other delivery mechanisms that you need (API, digital signage Web pages, mobile app, etc). {% hint style="info" %} Occuspace uses machine learning (ML) algorithms to generate accurate occupancy data for your spaces. We need to calibrate, or "train", our ML models with a truth set that ensures high quality data. The head counts you submit are used in our training systems. {% endhint %} This page is a very quick summary of the steps to get started measuring your spaces with Occuspace. The rest of the documentation on this site goes into much more detail about both the installation and regular usage of our service. # The Occuspace Portal A single unified application for understanding your data and managing your account The [Occuspace Portal](https://portal.occuspace.io/) is a Web application accessible via your browser where you can view your space utilization data and manage all setup and maintenance activities. You can access this application from any type of Web browser on your desktop/laptop as well as your mobile device. It is available 24 hours a day and is continuously updating with the latest data.

The Occuspace Portal which provides detailed utilization data from your spaces

Depending on your user account role you will have access to some or all of the following sections: * **Analytics** - View and interact with your historical occupancy data * **Live Data** - See live data from your spaces * **Spaces -** Manage the setup of your spaces and provide calibration data * **User Management -** Invite and manage users from your organization You can access the different sections by using the global navigation bar at the top of the page. ### **Navigating Your Spaces In The Occuspace Portal** An important navigational control in the Portal is the Space Tree which is a hierarchical representation of the different spaces you are monitoring with Occuspace. The Space Tree is critical to navigating the Analytics, Live Data, and Spaces sections of the Portal and ensuring all users have access to the correct spaces via User Management.

The Space Tree allows you to quickly and easily move among your various spaces being measured by Occuspace

The topmost entry in the Space Tree represents the top/root level of your account (usually appearing as your company or organization name, or a major building or campus where you work) and represents a "space group" consisting of one or more spaces you are measuring with Occuspace. Underneath this top level are items that can either be fully discrete spaces you are measuring (e.g. Lounge or Library) or another space group with its own child spaces (e.g. New York Office or 1st Floor West). The Space Tree for a customer can potentially go quite deep with many levels in complex space environments. The Space Tree appears on the left-hand side of the Portal page if you are on a laptop or desktop. If you are on a mobile phone you can access the Space Tree via the main menu available from the top right global navigation icon. You can expand any space group to see its children and their children...and so on. A search box is available at the top to quickly narrow down on the part of the tree of interest if you already know the space name. Your position in the Space Tree is maintained as you move across the Analytics, Live Data, and Spaces sections of the Portal. The data presented and the functionality available in the main content area of these sections is always applicable to the space or space group you currently have selected in the Space Tree. The Space Tree can also be collapsed to the side if you want to use the full width of your screen for viewing data in Analytics or other reasons. {% hint style="info" %} You may be wondering how your Space Tree is defined to begin with. That's a good question and is a critical part of onboarding as an Occuspace customer. Our Account Management team works with you to define the correct hierarchy for your discrete spaces that matches your occupancy measurement needs. We can support a wide variety of arrangements in the Space Tree to accommodate nearly any situation. {% endhint %} Another key navigation and orientation aid in the Portal are the "breadcrumbs" that are prominently displayed immediately above the page header (highlighted in orange below). These series of links build as you navigate down your Space Tree, always indicating where you are and quickly allowing you to move back up to any of the higher space groups in the hierarchy.

Breadcrumbs are a navigation aid that orient you to your location and allow you to quickly move up the space tree hierarchy

### The Space Details Panel The Space Details panel slides in from the right hand side of the page, and is accessible via the "Space Details" link at the top right when you are in the "Analytics", "Live Data", or "Spaces" sections of the Occuspace Portal. This panel shows detailed information about the currently selected space and also provides the user with the ability to edit certain attributes.

The Space Details panel shows detailed information about the current space and provides the ability to edit certain attributes

Space Details is also where you can access the marked-up floor plans for the associated space. A preview of the floor plan is shown at the bottom of the panel. Clicking on this image opens up the Floor Plan Viewer layer allows you to examine the floor plan in detail, zooming into aspects of particular interest.

The Occuspace Portal has a floor plan viewer that shows the measured spaces and location of Occuspace sensors

{% hint style="info" %} This page is a quick overview of our Occuspace Portal, explaining its role, the main sections, and how to navigate around. If you are looking for deeper help content for the Analytics section of the Portal and how to understand your occupancy measurement data please go [here](/guides/understanding-your-data). {% endhint %} The Occuspace Portal plays a key role in setting up the hardware sensors which is covered in the next guide in this documentation. # Setting Up Occuspace The easiest and simplest space utilization data platform to set up today Setting up Occuspace is very simple and quick to do. It does not require any holes to be cut in walls, dedicated electrical wiring, or other custom work that is expensive and time consuming. It is possible to install our sensors to cover 100,000 square feet of your spaces in just a few hours, not days or more likely weeks/months as with other solutions. And the installation process is very easy making it possible for you to do a self-installation if you like. Or we can provide a professional installation experience with our team visiting your space and setting things up for you. Just over half of our customers opt for self-installation, and we typically send our team when there are more than 200,000 square feet to monitor. A quick video of the key steps in this process is shown below: {% embed url="" %} Installing Occuspace sensors is simple and quick to do {% endembed %} Regardless of whether the installation is self-service or done professionally by our team, there are three phases to get Occuspace installed and running for your space: 1. Configuration & Setup - Understanding floor plans, defining your space, and network setup 2. Sensor Installation - Installing sensors physically and activating them in the Occuspace Portal 3. Calibration - Providing head counts to fine tune data accuracy

The Spaces section of the Occuspace Portal allows you to easily install and configure your sensors and spaces

Our account management team works with you through each of these steps which are described in detail on the following pages. # Configuration & Setup Setting up Occuspace starts during the sales process as we understand your business objectives and the spaces you wish to measure and improve. ### Floor Plans & Space Definition The first step in onboarding onto the Occuspace platform is to provide floor plans of the spaces you wish us to measure. Typically your Occuspace Sales Representative will work with you to get whatever available assets in this regard that you have (we accept a wide variety of formats including PDFs, images, CAD, Figma...even worse case sketches and photos!). We will review these floor plans with you to determine the specific areas that you wish to cover, and how you want to divide those areas into further levels of granularity. A key part of this phase is deciding how you want to divide up the spaces you wish to measure so that the data Occuspace reports is useful and actionable for you. If you are using our Occupancy product you will want to define the "neighborhoods" of your space by which you can break down your data. These neighborhoods may represent individual rooms in your spaces, or you may have a larger space that you wish to break down into smaller, measurable zones (e.g. the Sales desk area versus the Customer Support desk area). Occuspace allows for a lot of flexibility in how you want to define these neighborhoods to best suit your needs. Below is an example of a floor plan where the entire floor is measured as one neighborhood by Occuspace. In this example space utilization data is reported for this entire floor.

In this floor plan configuration data is available for one reporting level of the entire floor

However, the same space can be broken up in a variety of ways that may be of better understanding and lead to actions for improvement. Below is the same space but with multiple "neighborhoods" dividing up the space. The divisions might represent different departments within a business for instance, or another breakout of importance to the organization. In the example below occupancy data is reported for each neighborhood on this floor, as well as the entire floor together.

In this floor plan configuration data is available by six "neighborhoods" representing open seating areas and meeting rooms

We will work with you to help define the space breakout for your floor plans based on what makes the most sense for your needs. Once the neighborhoods are defined Occuspace can determine how many sensors are needed and the approximate locations that they should be placed (called sensor placements, more on that in the next step). We will mark-up the floor plans with these indications and review them with you for final approval. This allows us to determine the exact number of sensors needed to properly cover your space and finalize the contract details. ### Network Connectivity Occuspace sensors will need to connect to the Internet to send us data and ultimately provide you with the measurement data from our service. We support two methods of connectivity for our sensors, WiFi and Ethernet (PoE). #### WiFi Based Connectivity For WiFi based connectivity we will need access credentials to be able to connect to an available WiFi network that you provide at your spaces. Occuspace supports a wide range of different WiFi access methods from unencrypted open networks (though not what we usually recommend) to very tightly controlled enterprise networks utilizing highly secure credentials and policies. The table below outlines the supported WiFi standards and specific requirements of our sensors: | Spec | | | ----------------------------- | ---------------------------------------------------------------------------- | | **WiFi** | 802.11 b/g/n/ac 2.4GHz or 5GHz | | **Network Type Supported** | Open, WPA2 - Personal, WPA2 - Enterprise, WPA3 - Personal, WPA3 - Enterprise | | **Encryption Type Supported** | TKIP & AES (CCMP-128 only for WPA3) | | **Ports Required Open** | 80 (HTTP) & 443 (HTTPS) | **Additional WiFi Requirements** * No splash pages or button press requirements to join the network (unless MAC address bypass is possible) Our team will work with you to obtain the appropriate WiFi credentials for your situation. We preconfigure our hardware sensors with your security credentials prior to shipping them to you so that installation is a smooth process. #### Ethernet Connectivity For Ethernet based connectivity the setup is simpler as no network credentials are required. Our sensors can simply be plugged in via Ethernet and will connect to the Occuspace cloud as long as there are no special access requirements from your end. The following LAN standards and specific requirements of our sensors are: | Spec | | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Input** |

VLAN connection to public Internet
IEEE 802.3 connection (minimum)

IEEE 802.3u (recommended)
10Mbps (minimum)
100Mbps (recommended)

| | **Ethernet Cable** | Cat 5 or Cat 6 | | **Connector** | RJ45 connector, 8-pin, 4 pairs | | **Ports Required Open** | 80 (HTTP) & 443 (HTTPS) | {% hint style="info" %} Occuspace recommends that our devices are specifically allowed on your network in any relevant administrative settings around MAC address permissions if these are employed in your organization. If your IT team uses MAC allow/deny lists it is important for us to work with them to ensure that the MAC addresses of our sensors are properly accounted for on their side. {% endhint %} Once the contract process is complete, your space breakout is defined, and we have obtained your WiFi credentials (if applicable) then your configuration is loaded into the Occuspace platform, we ship you your sensors, and you receive credentials via email to access the Occuspace Portal. You can then proceed with the next step which is the setup and installation of your sensors. # Sensor Installation Once the floor plans have been reviewed, your spaces are defined, your WiFi credentials have been provided (if applicable), and the contractual paperwork is complete, we move into installation of the Occuspace sensors. We offer two methods for this step; self-installation where we ship you the sensors and you plug them in yourself (it's easy and fast to do it on your own) or a professional installation done by the Occuspace team. Regardless of the method employed the steps below are the same. ### How To Install Sensors You will receive a shipment from Occuspace of one or more boxes of sensors configured and ready to be installed in your space. Installing an Occuspace sensor is very simple to do and involves two quick steps. We recommend that you do each of these two steps in quick succession for each sensor placement before moving on to the next one. 1. **Physical Installation -** plugging the sensor into a power source (via standard 110AC wall outlet or via a Powered over Ethernet cable) at the specified location on the marked-up floor plan (note the Sensor ID on the back of the sensor before plugging it in per the below image and accompanying tip)

Sensor ID A78BDF in plug in mode

Sensor ID A78BDF in PoE mode

Sensor ethernet port for PoE

{% hint style="warning" %} You will need to note the Sensor ID on the back of each sensor -`A78BDF` in the example above - \*before\* plugging it into its power source. This Sensor ID is used when you install the sensor into a sensor placement in the Occuspace Portal. {% endhint %} 2. **Occuspace Portal Installation** - Installing the sensor into a [sensor placement](/glossary#sensor-placement) in the Occuspace Portal. {% hint style="info" %} The Occuspace Portal works very well on a mobile phone browser, and makes it easy to walk around with sensors, plug them in, and complete each install with your phone. We recommend this approach which will allow you to install a large number of sensors very quickly. A laptop or tablet work very well too. {% endhint %} Both of the installation steps are described in more detail below. ### Physical Installation Sensors can be installed either in a standard 110AC wall outlet or via a Powered over Ethernet (PoE) cable. The sensor has a retractable wall plug which you can flip down if you are using PoE so that it is not in the way. #### Identifying Where To Plug In Your Sensors During the [Configuration & Setup](/guides/setting-up-occuspace/configuration-and-setup) phase, Occuspace worked with you to assess your floor plans and define how many sensors are needed to cover your desired spaces. Part of this process involved marking up floor plans with recommended [sensor placements](/glossary#sensor-placement). These placements are represented by markers like `1A` and `1E` in the image below, and are placed at the desired locations where Occuspace sensors should be installed to provide the best measurement data on your space. ![A marked-up floor plan showing the optimum sensor placements for two spaces (e.g. "1A" or "1G")](/files/2NK2CGUi3sLc7tHIrFJX) The marked-up floor plans are used to guide installation for the ideal sensor placements for your space. However, we do understand that installation is not always possible exactly in the indicated space placements. If this is the case, you can follow the best practices below to find a suitable alternative. #### Sensor Placement Best Practices You may have to install a sensor in a location that is not on your marked-up floor plan. If this is the case there are some simple recommendations to keep in mind: * Sensors should be evenly distributed throughout the zone they are covering. Clustering all sensors on one side of the zone reduces the overall coverage of the space and should be avoided * Sensors should avoid being placed on the exterior of a zone if possible. This is particularly the case if the adjacent space is a highly trafficked area. If a sensor is sharing a wall with a highly trafficked space it is more likely to pick up signals from that adjacent space as well (though there are things we can do to mitigate this problem as well if it is unavoidable, contact your Account Manager if so) * Sensors should not be placed behind any major barriers. If a sensor is behind a refrigerator or metal bookshelf, it will significantly reduce the range that it can cover * If a sensor is not being installed in the indicated location in the floor plan it should ideally be installed within 5-10 feet of that location {% hint style="warning" %} In the event that you install a sensor in a different position than the placement indicated on your marked-up floor plans please contact your Account Manager to verify the new location is acceptable. {% endhint %} #### Plugging In Your Sensors Each sensor comes with an adhesive on the back to secure it to a power receptacle wall plate, wall, or ceiling. After finding a suitable outlet or PoE cable location in the close vicinity of the sensor placement marked on the floor plan, take a fresh uninstalled sensor (any is fine, you do not need to worry about using a specific sensor), remove the adhesive cover strips on the back, and plug the sensor into the wall receptacle (or PoE cable) pressing firmly to make contact between the adhesive and the surface. **Remember to note the Sensor ID on the back before doing this.** You will need this Sensor ID to finish installing the sensor in the Occuspace Portal.
{% hint style="info" %} You can install any fresh uninstalled sensor into any empty sensor placement. Just remember to note the ID of the sensor on the back before actually plugging it in. {% endhint %} ### Installation via The Occuspace Portal The second step in the overall process is to complete the installation using the Occuspace Portal. This is done by assigning the Sensor ID of each installed sensor to its corresponding sensor placement. This is done on the "Install" tab in the "Spaces" section of the Occuspace Portal.

Sensors are installed via the Occuspace Portal after being plugged into each location

**Occuspace Portal Installation Steps** These are the steps to follow in the Portal to complete the installation of each sensor: 1. Head to the "Spaces" section from the top navigation 2. Navigate to the "Install" tab on the "Spaces" section 3. Once there, you will see a list of all [sensor placements](/glossary#sensor-placement) for the space(s) you are installing. Sensor placements are grouped together by [zone](/glossary#zones) as indicated in your marked-up floor plan(s) * You can search for a specific zone, sensor placement, or Sensor ID by using the search box at the top of the page * You can also filter for specific statuses using the sensor status dropdown. * Sensors have a number of statuses that can be displayed in the Portal in addition to "In Review" and "Installed". A full list of all sensor statuses and their meanings is described on the [Managing Your Spaces](https://docs.occuspace.io/guides/setting-up-occuspace/managing-your-spaces#sensor-placement-statuses) page. 4. To finish the install of a sensor, find the sensor placement that you are physically installing into. You must be installing into a placement that has the status "Empty". In the example screenshot below, we are installing Sensor ID `f6b0c0` into sensor placement `2A`. 5. Click the "Install Sensor" link. A layer will appear with the marked-up floor plan and a drop-down menu to assign a Sensor ID for this placement. Use the drop-down to search for the Sensor ID you noted from the back of the sensor. Once the correct Sensor ID has been selected, click the "Install Sensor" button at the bottom of the layer. 6. The status of the sensor placement will change to "In Review" to confirm that you have successfully completed the installation of this sensor. At this point our system goes through a series of automated checks. Once these checks are complete the status updates to "Installed" Once you have successfully installed all of the sensors, Occuspace will do a final check and validation of your setup before moving onto the final step of setting up Occuspace which is [the calibration and tuning of the sensors](https://docs.occuspace.io/guides/setting-up-occuspace/calibration).

An Occuspace sensor with the ID F6B0C0 is being installed into sensor location 2A via the Occuspace Portal

{% hint style="info" %} If you encounter a problem while installing a sensor (e.g. the sensor does not seem to power up) you can use the "Uninstall Sensor" link for the sensor placement in the Occuspace Portal to remove the currently installed sensor, and replace it with a fresh uninstalled sensor. {% endhint %} # Calibration After you have completed the installation of your sensors you will move onto the final step of the setup process which is the calibration and fine tuning of your sensors and data. ### Head Counts Explained Occuspace uses "head counts" to help validate and calibrate our occupancy estimations. A head count is literally what the words describe, namely a count of how many people are in the defined space at a specific date and time. After [sensors are installed](/guides/setting-up-occuspace/sensor-installation), we require a handful of head counts at various occupancy levels to help us more accurately estimate the number of people in each monitored [zone](/glossary#zones). These head counts are used as training data for our machine learning models, and serve to finely calibrate your setup. ### When To Provide Head Counts Ideally, we like to see head counts conducted at various occupancy levels - low, medium and high occupancy - for each space being measured. Some spaces may not get to "high occupancy". This is perfectly fine as long as the submitted counts have a degree of variability across the other two levels. The most important aspect of head counting is a variety of counts, not total quantity. Five counts of high variability are better than ten counts all of the same level of occupancy. {% hint style="info" %} We generally need 5 - 10 total head counts per space across these levels to fully calibrate them and ensure accurate data, though we love it when our customers capture even more as each one helps better train our machine learning models. Every head count supplied improves the overall Occuspace service. {% endhint %} ### Submitting Head Counts via The Occuspace Portal The Occuspace Portal provides all the functionality you need to capture and track head counts for your spaces. This is done on the "Head Counts" tab of the "Spaces" section of the Occuspace Portal.

Head counts are used to calibrate machine learning models and can be easily submitted via the Occuspace Portal

**Occuspace Portal Head Counting Steps** These are the steps to follow in the Portal to submit a head count for a space: 1. Head to the "Spaces" section from the top navigation 2. Navigate to the "Head Count" tab on the "Spaces" section 3. Once there, you will see a list of all [zones](/glossary#zones) for the spaces you are measuring with your sensors * You can search for a specific zone by using the search box at the top of the page * You can also filter for specific [statuses](#undefined) using the zone status dropdown 4. Once you find the zone card for the specific head count you wish to capture, click on "Submit Head Count". A pop-up layer will appear allowing you to input the count date, count time, and actual head count value which you can then submit to capture it in the Occuspace platform. See below for some important things to keep in mind when capturing and inputting head counts 5. Upon submission of the head count the layer will disappear and you will receive a confirmation that your count was successfully captured If you made an error you can always edit or delete any head count that you submit by going into the detailed count summary view for the associated zone. This view shows you all head counts captured for any space and gives you the ability to edit and delete them.

The Occuspace Portal tracks all previously submitted head counts

{% hint style="info" %} It is important that the head counts that are captured are as accurate as possible. The following are some important tips to keep in mind as you count your spaces: * The space being counted should match the space on the Occuspace provided marked-up floor plans * If you are in the space at the time of the count, please count yourself * **The time inputted for a head count should be as close as possible to the time it was performed**. If a count was performed at 10:10am, the count should be inputted at 10:10am, not 10:00am or 10:15am * Counts should be conducted at least 15 minutes apart. If a count was performed at 10:30am, the next count for that space should not be performed until 10:45am or later * If possible, counts should not be performed during high flux times — when significant numbers of people are either entering or leaving a space. This may be unavoidable for some high traffic spaces * Counts should not be artificially enhanced — don’t plan to have people in a space that wouldn’t naturally be there to get higher head counts * A variety of counts at varying levels of occupancy is important for accurate measurement from Occuspace {% endhint %} Once you have captured a good variety of head counts for each of your spaces the installation work is complete. The Occuspace platform will begin to use machine learning to adapt to your space and filter for signals in your desired breakdown; the platform will fully learn your space over the following days (depending on the size and layout), at which point our service is fully activated and your space utilization data is available via the Customer Portal Analytics module and our API. At this point the installation phase is complete. You may make changes to your space configuration from time to time (e.g. the capacity of a space changes, or you wish to edit the names how your spaces appear for example). These space management actions are covered in the next section. # Managing Your Spaces Once you have Occuspace setup and installed in your space it operates automatically without human intervention required. Periodically you may need to make changes to your setup, particularly around the data presentation, as you learn how to better optimize the platform for your needs. Occasionally technical solutions are needed to improve the performance of our sensors in your environment. All of these kinds of maintenance activities are addressed below. ### Spaces Overview & Sensor Monitoring The "Spaces" section of the Occuspace Portal provides a summary of the current setup of your account as well as access to all functionality to install your sensors and calibrate your space. During installation and after it provides a helpful summary of the state of your sensors and head counts, and provides you with important guidance on how to improve your account health if necessary. #### Overview Tab When you first land in the "Spaces" section you are presented with the "Overview" tab showing you a summary of the status of your [sensor placements](/glossary#sensor-placement) and [zones](/glossary#zones), across your various spaces. Placements that may need attention, or details about the status of your zones are summarized and called to your attention at the top of this section. The immediate children of this space and their status appear in a summary table at the bottom.

The Spaces section of the Occuspace Portal

The "Overview" tab shows a summary card at the top right of all of your sensor placements grouped by status as shown below. The Sensor Placements summary card showing sensors grouped by status #### Sensor Placement Statuses Important information about the current status of your sensors is available on both the "Overview" and "Install" tabs of the "Spaces" section. This status information aids you during installation, as well as for ongoing maintenance activities that may occur from time to time. There are five possible statuses that a placement can have: * **Empty -** There is no sensor currently installed in the sensor placement * **Review** - The sensor placement has been successfully installed and is being reviewed for network connectivity and health * **Installed** - The sensor placement is fully installed with strong network connectivity * **Reset** - The sensor needs to be reset/rebooted * **Replace** - The sensor is not functioning properly and needs to be replaced If you have any questions about your sensor placements and their current status please contact your Occuspace Account Manager. ### Capacity Settings Each of your spaces has a different maximum capacity of occupants that it can accommodate. The Occuspace platform needs to know these space capacity values in order to provide your occupancy data. These values can be updated easily at any time in the Occuspace Portal: 1. Using the Space Tree, navigate to the space you wish to edit the capacity in either the "Analytics", "Live Data", or "Spaces" sections 2. Open the "Space Details" panel with the link at the top right of the page 3. The current capacity number is displayed in the panel that appears under "Attributes". Roll over the value to display an edit icon 4. Click on the edit icon to change the value to the new capacity for the space. Update the value and click "Save" to submit 5. The side panel will update with the new capacity value you just set {% hint style="warning" %} If the edit icon does not appear when you rollover the capacity attribute value in the space details panel this is due to one of the following conditions: * You must be an Admin level or Setup level user to edit the capacity for your spaces. Other user levels do not have privileges to be able to change capacity values * You can only edit the capacity of individual spaces, not space groups. Space groups automatically have a capacity value that is the sum of the individual spaces that belong to that space group {% endhint %} ### Space Names The names of your spaces can be updated at any time using the Occuspace Portal: 1. Using the Space Tree, navigate to the space you wish to edit the capacity in either the "Analytics", "Live Data", or "Spaces" sections 2. Open the "Space Details" panel with the link at the top right of the page 3. The current space name is displayed in the panel that appears under "Attributes". Roll over the "Name" value to display an edit icon 4. Click on the edit icon to update the name for this space. Update the value and click "Save" to submit 5. The side panel and rest of the Portal (e.g. space tree, page titles, downloadable files, etc) will update with the new name you just set {% hint style="warning" %} If the edit icon does not appear when you rollover the name attribute value in the space details panel this is due to one of the following conditions: * You must be an Admin level or Setup level user to edit the names of your spaces. Other user levels do not have privileges to be able to change space names {% endhint %} ### Hours Occuspace provides functionality to manage the open and closed hours that our customers use for spaces that are presented in [Digital Signage](https://docs.occuspace.io/guides/using-live-data#digital-signage) or on [Waitz](https://docs.occuspace.io/guides/using-live-data#waitz). Self-service functionality in the Customer Portal enables full control of the creation and management of the various hour setups in use. Please see the video below for a quick run through of how customers can quickly update their hours - a need we've heard from Higher Ed customers as students return to campus. We'll be sharing more here shortly! And for those who haven't already taken advantage of these offerings, they come included so please ask your Customer Success Manager for more information! {% embed url="" %} ### Resetting & Replacing Sensors Occasionally an Occuspace sensor may encounter difficulties with connectivity and need to be reset or even replaced. When this happens the status of your sensor placements in the Customer Portal will update appropriately as described above. Resetting a sensor is easy to do and can be accomplished by pressing the reset button on the sensor using a small pin or paper clip. Press the button for three seconds and release. You can also reset a sensor by unplugging it, waiting a few seconds, and then plugging it back in (though this may not be practical if adhesive has been employed to secure the sensor to a power receptacle faceplate). Replacing a sensor is also an easy process and follows the same general steps as [installing a sensor](/guides/setting-up-occuspace/sensor-installation). You will first uninstall the nonfunctioning sensor in the Occuspace Portal and then follow the same installation instructions to install the replacement sensor. Contact your Occuspace Account Manager if you need any help or have questions about this process. ### Recalibration Occasionally Occuspace may need to request that one of your zones goes into recalibration to improve the data accuracy. Recalibration simply entails providing a few more head counts so that we can retrain your zone and improve it's accuracy. Your Occuspace Account Manager will work with you to provide specific guidance on when those counts are needed, but the submission process is the same as before during the [Calibration](/guides/setting-up-occuspace/calibration) phase. Simply follow the same steps to submit your additional head counts via the Occuspace Portal. Your zone will be retrained shortly to improve the data accuracy. ### User Management Creating new user credentials and managing existing ones for the Occuspace Portal is easily done in the "User Management" section. You must be an Admin level user to have access to this functionality. When you first enter the "User Management" section you will be presented with a list of the current users in your account and over which you have control. You are able to see both active users as well as those that are still pending (i.e. users who have been invited to the platform but have not yet set up their credentials). You can search for a specific user by using the search box at the top of the page, or you can also filter for users with specific access roles or status using the drop-down menus.

User Management is available for Admin users and allows full self-service user management for your organization

{% hint style="info" %} An account can have more than one Admin user, you can create as many as you want to best manage your particular account. Each Admin user can create other Admin users as well as User and Setup users. An Admin can only administer users directly created by themselves, as well as any in turn created by these users. Admins will not be able to manage users that were created by entirely different Admin users in the same account, and for which they have no relationship. {% endhint %} #### Creating New Users Admin level users can create other users for their account via the "Add User" button at the top right of the "User Management" section. Clicking this button opens a layer allowing the Admin to provide the new individual's email address, desired access level or "User Role", and specific space permissions.

Invite new users to your Occuspace Portal account quickly with just a few required pieces of information; email invitations are sent out to all

Occuspace supports three possible "User Roles" or access levels that can be assigned to users of the platform. Each of the following and their abilities are described below: * Admin - Complete access to analytics data, live data, space setup & configuration, and user management functionality for a given set of spaces * User - Access to analytics data, live data, and space setup & configuration functionality for a given set of spaces * Setup - Access to space setup & configuration functionality only for a given set of spaces Occuspace also supports restricting access to a certain set of spaces within your account if you do not wish certain users to have access to everything. This space restriction can be applied to Admin users as well. In the "Add User" layer the "Spaces" section allows you to click on the specific spaces you wish to assign to a given user. If you want a user to have access to all spaces in the account you click on the top level entry which is usually represented with your account name. Once you submit the request for a new user the Occuspace Platform will send an email invitation to the email address that was provided allowing the individual to complete the registration process and activate their credentials. #### Managing Existing Users Existing users may periodically need help with their access privileges which can all be achieved from the "User Management" user listings table. Simply find the user you wish to manage and click anywhere on that row to bring up the details about that particular user. From this view you can edit the user's details and trigger password reset/invitation emails. # Understanding Your Data Space utilization data is a powerful data set that can be used to make your business more efficient and improve the experience of your customers and employees. Occuspace's data is used by many organizations in a variety of ways. Below are a few examples of the use cases that our data enables. * A higher education customer uses Occuspace to measure the occupancy utilization of all campus buildings to accurately allocate space to departments, and recently saved $35 million in one year by eliminating previously planned new construction projects * A large commercial real estate ownership group uses Occuspace to measure foot traffic to their portfolio of real estate assets, to better understand tenant utilization and be more effective in marketing properties and negotiating leases * A large tech company uses Occuspace to understand building capacity in real-time allowing them to optimize food service operations, reduce waste, improve staffing, and ensure a strong employee experience for their on-site workforce * A major ski resort uses Occuspace to provide real-time information to their visitors (via app, their Website, and digital signage) around ski lift waiting times and restaurant/dining room busyness The above are just a few examples of the many ways Occuspace data can be useful. However in order to ensure that you successfully leverage our data it is important to understand the various data sets we offer and how to interpret them. This guide and following sections cover this in further detail. # Analytics Module The Occuspace Portal provides a rich analytics interface for understanding your space data, allowing you to identify trends and insights from the entire period of time during which measurement occurred. The "Analytics" module is available in the global navigation at the top of the Portal. This page covers the primary functionality of this module and applies to all of the different data dimensions that Occuspace offers. ### Overview & Data Dimensions Upon entering the Analytics module you are placed at the topmost level of your Space Tree and presented with a summary of the data dimensions that are available for you to view at that level. Initial charts and visualizations of the dimensions are shown as well. At the bottom of the page is a table listing any children or subspaces of the current space if they exist. Clicking on a different location in either this table or in the Space Tree will refresh the page with the data available for that space.

The default overview of the Analytics module in the Occuspace Portal

You can dive deeper into any of the data dimensions available by using the secondary navigation element towards the top of the screen (or by clicking on one of the initial chart and data visualizations on summary view).

Analytics provides a secondary navigation bar to move across the various available data dimensions

These deeper views present each data dimension in both visual and tabular formats to satisfy different information analysis needs of users, and allow for a much more sophisticated analysis of each data set. Advanced charting controls, comparison functionality, and exporting capabilities (all covered below) are provided.

Analytics provides deeper views into each data dimension; in the example above the Hourly Occupancy dimension is shown

### Date & Time Selection A key configuration option of the Analytics module is the time frame desired for the data analysis being viewed. Analytics always depicts data points in the charts and table elements that are calculated based on the defined date, time, and day range options. These settings are always prominently depicted at the top of the page immediately under the space name header.

You can fine tune the specific dates, times, and days of the week you want to include in your analysis

Users can set the following configuration options when defining the parameters of their analysis: * **Date Range** - You can set the start and end date for your desired analysis. The date range pickers will allow you to select any day in the past going back to the very first day of measurement data for the associated space. Some quick options (e.g. Yesterday, This Week, Last Week, This Month, and Last Month) are provided as suggestions. * **Time Range** - You can chose the start time and end time for your desired analysis, excluding hours that you do not wish to be factored into the results. * **Days of Week** - You can include or exclude specific days of the week in your desired analysis. This is useful for understanding behavior on specific days (e.g. weekdays vs weekend), excluding days you do not wish to have in the results. Once you make changes to the date and time configuration click on the "Apply" button to refresh the data views and tables on the page. This configuration is retained as you navigate to other dimensions and locations in your Space Tree. ### Compare To The data dimension views provide powerful functionality to compare the current space with other spaces of yours during the same time period, or compare the current space and date/time range with a previous date/time range for the same space.

Comparison functionality allows you to analyze multiple spaces (or time periods) in a single view

You can access this capability from the "Compare to" link at the bottom of the dimension data charts. This link will open a layer allowing you to chose up to five comparison items which are then loaded into the chart and table.

Comparison functionality lets you compare your current space and time range to up to five other spaces or previous periods of time

If you set up a comparison of the current space and move to another data dimension (e.g. from Daily Occupancy to Hourly Occupancy) you can easily establish that same comparison in the new dimension when you click on "Compare to". The layer that appears will have a link at the bottom to use the same comparison set as before. Data comparisons that have been set up can be easily exported, see below. ### Chart Controls The Occuspace Portal offers a flexible charting system to allow you to visualize your data in many ways. The charts have a number of controls that are important to be familiar with to aid in your analysis. #### Average / Peak Display Control Charts for certain data dimensions (e.g. Daily Occupancy & Hourly Occupancy) allow the user to visualize both the average value and the peak (max) value of a data series over a certain range of time. Enabling and disabling each data series is accomplished via the chart key. You can click on each data series in the key itself to enable or disable it from the chart.

The chart key allows you to toggle on and off the different data series being presented

#### Zoom Feature For data series that are represented as a percentage (e.g. "% Occupied" for Daily Occupancy) the chart allows you to zoom in close to the data series maximums, or zoom out to see the data represented at a scale of 100%. This toggle affects the y-axis scaling functionality of the chart, and depending on the particulars of the data you are viewing this can have a large effect on the visualization.

The zoom feature changes the scale of the y-axis to allow you to better understand the chart visualization

#### Y-axis Toggle (Compare To Mode) When using the comparison functionality, and viewing a data series that is represented with more than one attribute (e.g. "Average Occupancy" and "% Occupied" for Daily Occupancy) the chart has to show each attribute separately. This toggle switches between the different attributes of the data series in order to create the chart.

Comparison funtionality allows you to view a space against other spaces, or against other time periods

#### Parallel vs Stacked Bar Display (Compare To Mode) For comparison functionality the option to visualize the data series as stacked bars instead of parallel bars is available.

Comparison charting can be toggled between parallel and stacked bar visualizations

### Exporting Data & Chart Images The Analytics module provides an extensive number of ways to obtain your data and make use of it in your own workflows. #### Export (Raw) Data The most granular level of your available data dimensions is available via the "Export Data" link at the top right of every page in the Analytics module. For the current configuration of Space Tree selection and date & time range settings you can obtain the base level data enabling all of the visualizations seen in the charts and tables (and in certain cases even more granular data than what is shown in the UI). This data is provided to you in CSV file format that is immediately downloaded to your computer. Clicking on the "Export Data" link brings up a window allowing you to tailor your CSV download more finely. If the current space has more than one data dimension available you will first need to choose the desired dimension for the export. The window allows you to update the date and time range more carefully, and for Occupancy data you can select different data bin sizes for the export. Finally the Space Tree is presented with the current space confirmed for the download as checked. You can select other spaces to include in the download as well. When you are happy with the configuration click on the Export Data button at the bottom right of the window. The CSV file is immediately generated and then downloaded to your computer.

You can export any spaces Occupancy and Visitors data to a CSV file for analysis in your own tools

Select the spaces, date and time ranges, and desired data time interval and the file will be downloaded to your computer

#### Export Table Values For the different data dimensions shown in the Analytics module you can export the data shown in the tables as CSV files downloaded to your computer. Any data comparisons set up in the charts and tables are included in the CSV files as well. To download this data click on the "Table Values" download link at the top right of any data table.

The table values export functionality downloads a CSV of exactly the data presented in the chart and table, including any comparisons

#### Chart Image Export All of the charts in the data dimension views are exportable as PNG images for use in your own materials. Any data comparisons set up in the charts are included in the PNG images as well. To export an image click on the "Image" download link at the top right of any chart on the dimension views.

Export any chart visualization as a PNG image for use in your own presentations and materials

# Occupancy Occupancy is a primary data set available from Occuspace that reports the level of occupancy of your spaces (i.e. how many people are in each location over a given time frame). It is highly valuable in understanding how your space is currently used, and to aid in making future planning and allocation decisions. This metric provides a rich level of fidelity in the data at the neighborhood level that is flexible and can align with the way that you view and manage your real estate. For understanding your space behavior and making optimization and planning decisions, there is no better data set to base your decisions than Occupancy. Occuspace's platform makes it simple to continuously monitor as much of your real estate as desired, and report on this valuable and actionable metric. Your Occupancy data is available 24x7x365 via the Occuspace Portal in the "Analytics" section which provides you with access to all of your data collected since installation. You can also access this data programmatically from the Occuspace Customer API. ### Occupancy Data Points Occupancy is the number of people in a space over a given period of time (e.g. a day, an hour, a date range). Occuspace reports each Occupancy data point in four specific ways: * **Average Occupancy** - The average number of people that were in the space over the time period * **Average Utilization** - The average percentage occupied the space was over the time period, based on the defined capacity of the space * **Peak Occupancy** - The peak number of people that were in the space over the time period * **Peak Utilization** - The percentage occupied the space was at the peak level of occupancy during the time period, based on the defined capacity of the space The Analytics module of the Customer Portal as well as the Occuspace API allow you to retrieve Occupancy data points for any of your spaces. The data points that are available in these interfaces will have each of the four attributes described above.

Occupancy reports how many people on average are in a given space over a defined time period

{% hint style="info" %} It is not unusual for there to be significant differences in the average and peak Occupancy values for a space during a time frame, particularly for longer time frames of analysis. This is usually the case for spaces that are dynamic environments and have highly variable rates of use throughout the day. Spaces that are more static and constant in nature will generally have average and peak Occupancy that are much closer to each other. {% endhint %} ### Data Reporting Intervals Occupancy data provided by the Occuspace platform is available in different time period intervals to satisfy varying levels of granularity desired in data analysis. The intervals available include full day, 60 minute, 30 minute, and 15 minute periods of time. The Occuspace Portal visualizes Occupancy data in daily and hourly intervals, which are generally appropriate for most data analysis needs. These intervals are also the most stable from a data perspective, and where the machine learning algorithms provide the highest level of accuracy. #### Daily Occupancy For the date and time range selected the average occupancy for each day is displayed in the chart and table.

Occupancy is frequently analyzed at daily time intervals

#### Hourly Occupancy For the date and time range defined the average occupancy for each hour of the day is displayed in the chart and table.

Analytics provides an hourly breakout of Occupancy as well for more dynamic trend analysis

#### Weekday & Hourly Occupancy For the date and time range defined the average occupancy for each hour of the day and for each day of the week is displayed in the chart and table. This visualization in particular helps understand weekly trends.

Two dimensional hourly and weekday analysis of Occupancy is also provided

#### Finer Data Granularity Intervals More granular data reporting intervals of 30 minutes and 15 minutes can be suitable for decisions that need to be based on shorter time segments of the day. The tradeoff is that these smaller intervals can result in noisier Occupancy data that fluctuates substantially from one interval to the next, especially for very dynamic environments. Occuspace recommends that these intervals are only used when they can influence decisions in your business that are also similarly highly dynamic in nature (these tend to be more real-time signal based use cases). Otherwise the data can be much harder to interpret and act upon. These finer granularity data intervals are available in the Data Export functionality in the Analytics module of the Customer Portal, which will provide you with a downloadable CSV file for further analysis. ### Neighborhood Level Data Breakout Occupancy data is continuously collected and reported for each of the spaces in the neighborhood breakout that was defined during your on-boarding and installation. This neighborhood breakout maps to a hierarchy for how you manage your own business and real estate (e.g. by department or business group). The Occuspace Portal allows you to view your Occupancy data for any of these neighborhoods.

Occupancy is frequently reported at a neighborhood level data reporting granularity

You can also compare the Occupancy data of one space against up to five other spaces (or compare the Occupancy data of one space against previous time ranges in the past for the same space) using the Compare To functionality in the Analytics module. This feature is particularly powerful for space understanding, planning, and allocation purposes.

Comparison functionality allows for visualizing spaces against other spaces being measured, or against other time periods

Occupancy data is also aggregated from individual spaces to the associated parent level spaces as well (e.g. the various floors of a library can be viewed individually, but you can also look at the Occupancy data and patterns of the library as a whole).

Occupancy can provide a comparison of parent and children space relationships

By dissecting Occupancy trends and patterns within defined neighborhoods, businesses can unlock a deeper understanding of how each sector of their space is being utilized over time. This granular approach enables more strategic and evidence-based decisions concerning space allocation, optimization, and future planning. It facilitates a more nuanced approach to managing space, allowing you to identify underutilized areas, predict peak usage times, and adjust resources accordingly. # Traffic Traffic is a primary data set available from Occuspace that reports the foot traffic of your spaces over a given time frame. It is valuable in understanding the total number of visitors to a space and how heavily it is used. This data is useful as a primary business metric around space usage and is frequently used in budgetary allocation activities (particularly for public spaces such as libraries, dining halls, restaurants and gyms). It is also useful as a trigger metric, in real-time, for space support services (e.g. janitorial cleaning of bathrooms after a certain number of visits). Traffic is a highly complimentary data set to Occupancy, and often helps to paint a deeper picture of the activity of a space when the two are analyzed together. Your Traffic data is available 24x7x365 via the Occuspace Portal in the Analytics module which provides you with access to all of your data collected since installation. You can also access this data programmatically from the Occuspace Customer API. ### Traffic Data Point Traffic is the number of people who have visited a given space over a period of time. Occuspace reports each Traffic data point with a single number representing the daily counts of people who entered the defined space during that time frame.

Traffic reports how many people visits a given building over a defined date range

{% hint style="info" %} The Traffic data set from Occuspace does not count the unique visitors of a space (i.e. accounts for multiple visits by the same individual and counts them as one). Rather the data set represents the total number of visitors to a space. Individuals who entered the space in the morning, left for lunch, and returned in the afternoon are counted as two visitors. {% endhint %} The Analytics module of the Customer Portal as well as the Occuspace API allow you to retrieve Traffic data points for your eligible spaces. The data points that are available in these interfaces will each have the attribute described above. ### Data Reporting Intervals Traffic data provided by the Occuspace platform is currently available at a single reporting interval of 24 hours. #### Daily Traffic For the date range selected the total numbers of visitors for each day is displayed in the chart and table.

Traffic is available at a data reporting granularity of daily time intervals

### Building Level Data Breakout Occuspace provides Traffic data at the building level. Our sensors act as a network to detect signal activity and provide the data sets that our machine learning algorithms use to generate the actual Traffic counts provided in the Customer Portal and Customer API. And these algorithms perform best in larger spaces that have well defined physical boundaries (i.e. walls and ceilings) and where we have enough coverage of the overall building itself.

Traffic reports data for entire buildings or well defined and covered spaces

You can also compare the Traffic data of one building against up to five other buildings (or compare the Traffic data of one building against previous time ranges in the past for itself) using the Compare To functionality in the Analytics module.

Comparison functionality allows for analyzing Traffic data across different spaces

# Dwell Time Dwell Time is a primary data set available from Occuspace that reports the amount of time people spend in your spaces. We define Dwell Time as the amount of time - in minutes - spent by people in a space each time they visit. Similar to Occupancy, we calculate and report two data points: Average Dwell Time and Peak Dwell Time. Note - we exclude transient visitors by only considering people who visit and stay for more than three minutes in a given space. Dwell Time is a daily metric. Occuspace calculates the total Dwell Time for the previous day once that day ends. Dwell Time data is available 24x7x365 via the Occuspace Portal in the "Analytics" section which provides you with access to all of your data collected since installation. You can also access this data programmatically from the [Occuspace Customer API](https://occuspace.io/api#daily-dwell-time). ### Dwell Time Data Points Dwell Time is the amount of time people spend in a space per visit, and - like Occupancy - can be aggregated up a customer's space tree, and reported over time. Occuspace reports Dwell Time in two specific ways: * **Average Dwell Time** - The average amount of time people spend per visit to a space * **Peak Dwell Time** - The largest amount of time that people were in the space in a given visit The Analytics module of the Customer Portal as well as the Occuspace API allow you to retrieve Dwell Time data points for any of your covered spaces. The data points that are available in these interfaces will have each of the two attributes described above.
### Data Reporting Intervals The Occuspace Portal visualizes Dwell Time data in daily intervals. ### Neighborhood Level Data Breakout Dwell Time data is continuously collected and reported daily for each of the spaces in the neighborhood breakout that was defined and implemented during your on-boarding and installation. This neighborhood breakout maps to a hierarchy for how you manage your own business and real estate (e.g. by department or business group). The Occuspace Portal allows you to view your Dwell Time data for any of these neighborhoods, and critically, compare Dwell Time across them. You can also compare the Dwell Times of your spaces with up to five other spaces (or compare the Dwell Time data of one space against previous time ranges in the past for itself) using the Compare To functionality in the Analytics module.

Comparing Dwell Times across various spaces shows in this case that the Breakroom consistently sees materially lower Dwell Times on Fridays, wheres the Cafeteria and Fitness Center are much more consistent day-to-day

By dissecting Dwell Time trends and patterns within defined neighborhoods, businesses can unlock a deeper understanding of how each of their spaces is being utilized over time. This granular approach enables more strategic and evidence-based decisions concerning space allocation, optimization, and future planning. It facilitates a more nuanced approach to managing space, allowing you to identify underutilized areas, predict peak usage times, and adjust resources accordingly. # Using Live Data Occuspace provides live, real-time [Occupancy](/guides/understanding-your-data/occupancy) data for your spaces in a number of flexible ways, enabling different use cases around optimizing space management and operations processes as well as improving the visitor experience. Below are a few examples of what our customers have achieved using our live data. * Higher education customers use live occupancy data to report the busyness levels of their public spaces (libraries, dining halls, restaurants, recreational facilities, etc.) to their students via websites and mobile apps, allowing these students to better react to conditions and plan their day * A large tech company uses live data to understand building occupancy in real-time, allowing them to optimize food service operations, reduce waste, improve staffing, and ensure a strong employee experience for their on-site workforce * A major ski resort uses Occuspace to provide real-time information to their skiers (via a mobile app, their Website, and digital signage) around ski lift waiting times and restaurant/dining room busyness Live data is accessible 24x7x365 via the Occuspace Portal and the Customer API, and through the Digital Signage and Waitz products, and customizable to reflect changing Hours to account for Holidays, staffing changes, or other customer-specific events. ### Live Data Attributes Each live data data point reported by Occuspace has the following attributes that can be provided across the various access methods: * **Count** - The number of people in the space at the current moment in time * **Capacity** - The overall capacity of the space * **Percent Occupied** - The percent occupied the space is at the current time based on the Count and Capacity numbers * **Busyness Level** - A textual representation of the busyness level of a space based on the Percent Occupied value, and used in externally facing functionality such as Digital Signage and the Waitz service. The following are the three possible text values that appear and their corresponding data ranges: * "Very busy" - Percent occupied > 80% * "Busy" - Percent occupied > 45% and <= 80% * "Not busy" - Percent occupied <= 45% ### Live Data In The Occuspace Portal The simplest way to view your real-time live data is with the Live Data module in the Occuspace Portal. You can view live occupancy data for any of your spaces using the Space Tree which will present the data to you in cards reflecting that level and any immediate children.
You can also view live data without leaving your Analytics views, by clicking on Space Details in the upper right.

Clicking on Space Details in any view will reveal the Space Details panel that includes Live Data

View Live Data, Capacity, floor plan, and hours in Space Details.

### Digital Signage Live data from your spaces can be leveraged for use in large format digital displays and browsers to help visitors to the space understand the busyness of various locations. It assists with people who are looking for a quiet empty floor to study in a library, to inform employees of the current wait time for the office cafeteria and dining room, or for programming to orient towards busier spaces. You can set up as many Digital Signage instances as you like displaying Live Data for specific neighborhood spaces.

Occuspace provides ready to go Digital Signage URLs that load live busyness data from your spaces for visitors

#### Setting Up Digital Signage The Spaces section of the Customer Portal has subsection called "Digital Signage".
Similar to "Hours" and "WiFi Credentials", this subsection is available at the topmost level of the Spaces section for Admin & Setup level users of your account. These users can create, configure, edit and delete Digital Signs. * Clicking on "Digital Signage" takes the user to a listing of the current Digital Signage for that customer. For each Sign, the current URL is shown and clicks through to the live sign in a new browser tab.
#### Creating New Digital Signs You can create or edit Digital Signage for any of your spaces with a WYSIWYG editor that shows a real-time preview of the Sign as you create and modify it:
{% embed url="" %} Brief video to show how you can create and manage Digital Signs {% endembed %} As the video above will show you, there are a few key options when you create Digital Signs. * You can choose up to 8 total spaces to feature on a Sign, each represented as a unique card. * The Digital Sign's name, as well as the names of the individual spaces, can all be edited by clicking on the edit icon next to any name. * You can drag the cards to change the display order to what they desire. * Optional QR code and label functionality is also supported. * A toggle option is provided to show or hide the capacity display, providing flexibility in how you define capacity. Once you set up a a new Digital Sign, you will receive a URL that you can use in your digital signage displays to easily display this valuable data in your locations. #### Integration With Hours Digital Signage leverages our [Hours](/guides/setting-up-occuspace/managing-your-spaces#hours) functionality to correctly indicate if spaces are open or closed. * If the space is already featured on Waitz or on a Digital Sign, it will automatically reflect the same hour rule used in the other location(s). * Spaces not previously used in Waitz or another Digital Sign will initially use the global hour rule of being open 24/7. Users can then modify the hours for the space itself in Space Details (by clicking the edit icon next to the hours), or in the "Hours" section where they can create a new hour rule or associate one of their existing hour rules. ### Waitz Occuspace offers a consolidated consumer service for providing live busyness data on public spaces for our higher education customers. The service is called Waitz, and it is used by the various student bodies of these institutions to improve their campus experience. Waitz is an easy way for universities and colleges to leverage a high quality user experience and Web platform infrastructure to provide this data without any technical expertise or setup work required. Waitz is available through branded Web pages and also through a native mobile app (available on the Apple App Store and the Google Play Store). Waitz serves millions of data requests each month from higher ed institutions across the United States and Canada.

Waitz provides a native app experience (Apple App Store & Google Play Store) and Web pages for reporting busyness information at higher education campuses in North America

Waitz can be set up for any of your public spaces if you are a higher education customer of Occuspace and want to provide your students with another way to improve their campus experience. Contact your Occuspace Account Manager if you would like to learn more and have your spaces listed on Waitz. {% hint style="info" %} Digital Signage and Waitz display Open & Closed Hours that you can easily update in our portal. For more on Hours, [please review this section and short video under Managing Your Spaces](https://docs.occuspace.io/guides/setting-up-occuspace/managing-your-spaces#hours). {% endhint %} ### Customer API Live data is also available through the Customer API which provides REST endpoints to access live data for spaces being measured by Occuspace. This method is recommended for more sophisticated user experiences where only the data points are provided by Occuspace and the customer handles all presentation needs and complexities. The Customer API is also valuable for customers looking to ingest live data into their own data stores or business intelligence platforms. Our Account Management team can get developers set up with an authorization bearer token, and our [latest API documents are available here](https://occuspace.io/api). # Summary An overview of Occuspace technology and how it all works
Occuspace uses proprietary sensor technology and machine learning algorithms to determine the number of people in buildings and smaller spaces, and provide insights about their activity. ### Macro Sensors Measure Wide Areas Occuspace employs different technologies to gather measurement data about people in spaces. One approach is intended for wide area space measurement and is based on the presence of consumer devices (smartphones, laptops, tablets, audio headphones, etc.) that people carry with them. ![Macro sensors turn device signal activity into space occupancy and behavior data](/files/YoT0IQY0cDrE6nSFK5dR) Occuspace Macro sensors passively detect Bluetooth Low Energy (BLE) and WiFi signal activity in the surrounding area. The sensors detect the presence of laptops, cell phones, wearables, and other connected devices and send summary information about these signals to Occuspace's cloud. Occuspace does not actually connect to any of these devices, and no personally identifiable information (PII) is ever collected during this process ensuring a high level of privacy for consumers. ### Micro Sensors Measure Conference Rooms & Other Meeting Spaces The other approach employed by Occuspace is intended for smaller spaces and involves actively scanning the surrounding area with mmWave based sensors.

Micro sensors use mmWaves to scan and determine space occupancy and behavior data

Occuspace Micro sensors use mmWaves to scan smaller spaces and determine the occupancy from the waves that bounce back from people and objects in the vicinity. The fidelity of the sensors is sufficient to determine occupancy of the space but not to record any personally identifiable information ensuring a high level of privacy with this approach as well. ### Signals Transformed Into Metrics In Our Cloud The collected Macro and Micro signal data is analyzed in Occuspace's cloud with proprietary machine learning algorithms using extensive training data gathered over years by Occuspace. This training data calibrates the models and then the number of people for a given area is estimated and reported on a minute-by-minute basis, along with more detailed insights. Customers can access data and insights via a Web-based Customer Portal or from a REST API. # Hardware Specifications Occuspace collects data through hardware sensors that easily install in spaces you wish to measure ### Macro Sensor Physical Specifications * Dimensions are 3" height x 3" width x 2" depth (74mm x 74mm x 50mm) * Supported operating temperature range is -20°C to 65°C * The device is not waterproof but is suitable for outdoor use when installed in a weatherproof housing

Occuspace Macro Sensor

### Macro Sensor Power Requirements Macro sensors can either plug into your existing AC wall outlets or can be powered by PoE. The following are the power requirements depending on the method being used: | Spec | | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **Outlet Type (AC powered)** |

Standard grounded 120 volt outlet or
NEMA 5-5 (North American 3 pin)

| | **Power Draw (AC powered)** |

Input: 100-240 VAC, 50-60Hz, 0.7A

2.2 watts per device

| | **Outlet Type (PoE powered)** |

RJ45 PoE powered connector, 8-pin, 4 pairs

Ethernet Category 5 or 6 PoE cable
Voltage: 47V (802.3af sufficient)

| | **Power Draw (PoE powered)** | 2.5 watts per device (802.3af sufficient) | ### Micro Sensor Physical Specifications * Dimensions are 1.9" height x 1.9" width x 1.1" depth (48mm x 48mm x 29mm) * Supported operating temperature range is -20°C to 65°C

Occuspace Micro Sensor

### Micro Sensor Power Requirements Micro sensors are powered via USB giving flexibility to installations. Customers can leverage AC wall receptacles with the included power adapter to USB ports on the back of TVs and on other equipment. The following are the specific power requirements for the sensor: | Spec | | | ------------------ | ------------------------------------------------- | | **Connector Type** | USB Type-C 24-pin reversible connector | | **Power Draw** |

Input: 5VDC, 0.2A

<1 watt per device

| ### FCC Certification Occuspace sensors are fully certified to be compliant with all United States Federal Communications Committee (FCC) regulations:
# Network Specifications Occuspace Macro sensors are designed to easily communicate with the Occuspace cloud via cellular connectivity. They can also integrate with existing customer networks via WiFi or Ethernet. ### Macro Sensor Cellular Network Connection Our Macro sensors come automatically enabled to communicate with cellular networks with the connectivity and data fully managed by Occuspace. This is the recommended method of connectivity for most situations in which Macro sensors are installed due to ease and speed of install. The table below outlines the supported cellular bandwidth and networks: | Spec | | | ---------------------------------- | ------------------------------------------------------------- | | **Cellular Connectivity Standard** | LTE CAT-1 | | **Cellular Networks Supported** | Roams on AT\&T, Verizon and T-Mobile | | **Cellular Data Plan** | Fully managed by Occuspace, no customer involvement necessary | ### Macro Sensor WiFi Network Connection Requirements Our customers frequently supply a WiFi network that our Macro sensors use to connect to the Internet and send data back to Occuspace's cloud. The table below outlines the supported WiFi standards and specific requirements of our sensors: | Spec | | | ----------------------------- | ---------------------------------------------------------------------------- | | **WiFi** | 802.11 b/g/n/ac 2.4GHz or 5GHz | | **Network Type Supported** | Open, WPA2 - Personal, WPA2 - Enterprise, WPA3 - Personal, WPA3 - Enterprise | | **Encryption Type Supported** | TKIP & AES (CCMP-128 only for WPA3) | | **Ports Required Open** |
  • 80 (HTTP)
  • 443 (HTTPS)
  • 123 (UDP)
| **Additional Requirements** * No splash pages or button presses to join network (unless MAC address bypass is possible) ### Macro Sensor Ethernet Connection Requirements Our Macro sensors can also connect to the Internet via Ethernet. In this case the following LAN standards and specific requirements of our sensors are: | Spec | | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Input** |

VLAN connection to public Internet
IEEE 802.3 connection (minimum)

IEEE 802.3u (recommended)
10Mbps (minimum)
100Mbps (recommended)

| | **Ethernet Cable** | Cat 5 or Cat 6 | | **Connector** | RJ45 connector, 8-pin, 4 pairs | | **Ports Required Open** | 80 (HTTP) & 443 (HTTPS) | ### WiFi / Ethernet Network Setup Best Practices & Recommendations * We recommend that our customers whitelist the MAC addresses of each Occuspace Macro sensor in their central network/IT infrastructure * We also recommend when possible that customers assign static IP addresses for each Occuspace Macro sensor {% hint style="info" %} Occuspace's Micro sensors for measuring conference rooms and other meeting spaces use Macro sensors to relay their measurement data to our cloud. Micro sensors do not need their own connectivity. At least one Macro sensor (and potentially more) will be required in order for Micro sensors to operate. {% endhint %} # Privacy & Security Occuspace's service does not collect any personally identifiable information (PII) about people in the spaces being measured by our sensors. Our service is privacy safe and secure. Occuspace was architected with privacy in mind and we are committed to protecting individual identities. The design of Occuspace makes it impossible to track any individual and no Personally Identifiable Information is ever collected and stored in our platform. ### Privacy & Security Safeguards * Occuspace collects zero personally identifiable information (PII) and is fully GDPR and CCPA compliant * Occuspace sensors have passed security review and penetration tests by a certified, independent third-party security auditing firm (report available upon request) * Occuspace sensors never connect to any devices, and can only passively observe the BLE and WiFi activity in a space being measured * Occuspace does use a unique identifier for each BLE and WiFi signal being measured. This unique identifier is based on the broadcasted MAC address of each radio * Modern smartphones, laptops, and other consumer devices randomly rotate the MAC address of the BLE and WiFi radios for consumer protection * Occuspace further enhances privacy by irreversibly hashing the broadcast MAC addresses into the unique identifiers used in data analysis * MAC addresses are irreversibly hashed immediately on the sensor itself with the original MAC address value never stored locally or in the cloud * Hashing is performed with SHA256 and reduced (truncated) in size to make it impossible to reverse * A daily rotating salt is applied to the hashing process to further obfuscate the unique identifiers * The sensors only transmit hashed data to the Occuspace cloud * After hashed data is successfully sent to Occuspace it is permanently deleted from the sensors # Glossary ### Sensor Occuspace sensors collect signal activity data. Every sensor has an associated ID on the back, which you will use during installation.
### Sensor Placement A sensor placement refers to where a sensor is placed within a zone. This is mapped to a physical location, usually denoted by a label like "1A" on marked-up floorplans. ![The boxes outlined in red are sensor placements](/files/70jNku0CZtt2uWsEMl87) ### Zones A zone refers to the physical spaces where we return data for. In the picture below, there are two zones -- West Area & East Area. ![](/files/dzdy5Bq7X3eo2ducCaEb) # Summary Occuspace provides a powerful and flexible REST API for customers to obtain their occupancy data programmatically. This API provides both real-time and historical data for Occuspace-enabled locations, and is available to any active customer. This documentation provides the background necessary to access and understand the various endpoints that comprise this API. {% hint style="info" %} There are a variety of different data sets and aggregations provided by Occuspace in this API, and it is important to use the correct configuration for your given use case. We highly encourage our customers to reach out to us when starting to use this API. Occuspace Customer Success Managers can help identify which particular metric, data set, and aggregation makes the most sense to utilize. {% endhint %} {% content-ref url="/pages/SA7X34cUsBDCLFrin5Ys" %} [Authentication](/api-reference/authentication) {% endcontent-ref %} {% content-ref url="/pages/1Jk3HMSXRBJhnYqxOpLr" %} [Error Handling](/api-reference/error-handling) {% endcontent-ref %} {% content-ref url="/pages/6Js5yKGJRvGXpOuZLLT2" %} [Pagination](/api-reference/pagination) {% endcontent-ref %} {% content-ref url="/pages/O5OV2GnNYlci4TNZPBjZ" %} [Filters](/api-reference/filters) {% endcontent-ref %} {% content-ref url="/pages/JahkA2BZ2pjDT9Hnf0u6" %} [Locations](/api-reference/locations) {% endcontent-ref %} {% content-ref url="/pages/7F3IiWyZZgDDvAelnVIH" %} [Metrics](/api-reference/metrics) {% endcontent-ref %} # Authentication All requests to the Occuspace Customer API must be authenticated using a Bearer token passed in the Authorization header. ### Obtaining a Token API tokens are issued directly by the Occuspace team. To request a token, contact your Occuspace Customer Success Manager or reach out to support. Once issued, your token does not expire and can be used indefinitely. ### Making Authenticated Requests Replace `YOUR_API_TOKEN` with the token issued to you by Occuspace. The token must be included in every request. ```bash curl -X GET "https://api.occuspace.io/v2/locations" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ### Security Best Practices {% hint style="warning" %} **Keep your token secure.** Do not expose your API token in client-side code, public repositories, or anywhere it could be accessed by unauthorized parties. If you believe your token has been compromised, contact Occuspace immediately to have it rotated. {% endhint %} ### Error Responses If your token is missing or invalid, the API will return a `401 Unauthorized` response. For a full breakdown of error response formats, see the Error Handling page. ```json { "type": "https://api.occuspace.io/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Invalid API key", "instance": "/v2/locations", "request_id": "f1b8698f-b0e8-4fb9-82e1-ddf89029350c" } ``` # Error Handling The Occuspace API uses standard HTTP status codes to indicate the success or failure of a request. All error responses follow the RFC 7807 Problem Details standard for consistent, machine-readable error information. ### Error Response Format Every error response returns a JSON object with the following fields, regardless of the type of error. The `request_id` field is particularly useful when contacting support as it allows the Occuspace team to trace the exact request in our systems.
FieldTypeDescription
typestringA URI that identifies the problem type
titlestringA short, human-readable summary of the problem
statusintegerThe HTTP status code
detailstringA specific explanation of this occurrence of the problem
instancestringThe API path that generated the error
request_idstringA unique identifier for the request, useful for support
```json { "type": "https://api.occuspace.io/problems/not-found", "title": "Not Found", "status": 404, "detail": "Location 1560 not found or not accessible", "instance": "/v2/locations/1560", "request_id": "f1b8698f-b0e8-4fb9-82e1-ddf89029350c" } ``` ### HTTP Status Codes The following HTTP status codes are used by the Occuspace API:
Status CodeNameDescription
200OKThe request was successful
400Bad RequestOne or more request parameters are missing or invalid
401UnauthorizedThe Bearer token is missing or invalid
404Not FoundThe requested resource does not exist or is not accessible with your credentials
500Internal Server ErrorAn unexpected error occurred on the Occuspace servers
### 400 Bad Request {% hint style="warning" %} **Check your request parameters.** A `400` error means something in your request is invalid. The `detail` field will identify the specific parameter that caused the error and what the valid values are. {% endhint %} ```json { "type": "https://api.occuspace.io/problems/bad-request", "title": "Bad Request", "status": 400, "detail": "Invalid interval: 'yearly'. Supported intervals for occupancy: daily, hourly, weekly, monthly, 60min, 30min, 15min", "instance": "/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-03&interval=yearly", "request_id": "a3c9512d-e4f7-4ab2-91c3-eef12084610b" } ``` Common causes of a `400` error include: an unsupported `interval` value for the requested metric, an invalid `start_date` or `end_date` format (expected `YYYY-MM-DD`), or using `start_hour_filter`, `end_hour_filter`, or `days_filter` with an interval that does not support them. ### 401 Unauthorized {% hint style="danger" %} **Your Bearer token is missing or invalid.** Ensure the `Authorization` header is included in every request and that the token value is correct. {% endhint %} ```json { "type": "https://api.occuspace.io/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "Invalid API key", "instance": "/v2/locations", "request_id": "b2d8423e-f5a6-4bc3-82d2-cce23195721c" } ``` If you believe your token is correct but are still receiving a `401`, contact your Occuspace Customer Success Manager to verify that your token is active. ### 404 Not Found {% hint style="warning" %} **The requested resource was not found.** This can mean the resource does not exist, or that your API token does not have access to it. The `detail` field will identify the specific resource that could not be found. {% endhint %} ```json { "type": "https://api.occuspace.io/problems/not-found", "title": "Not Found", "status": 404, "detail": "Location 1560 not found or not accessible", "instance": "/v2/locations/1560", "request_id": "d5f0645g-h7c8-6de5-04f4-eeg45317943e" } ``` Verify that the location ID in your request is correct and that your API token has been granted access to that location. If you believe you should have access, contact your Occuspace Customer Success Manager. ### 500 Internal Server Error {% hint style="danger" %} **An unexpected error occurred on the Occuspace servers.** This is not caused by your request. Please retry the request after a short wait. If the error persists, contact Occuspace with your `request_id` so our team can investigate. {% endhint %} ```json { "type": "https://api.occuspace.io/problems/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred. Please try again later.", "instance": "/v2/locations/1559/occupancy", "request_id": "e6g1756h-i8d9-7ef6-15g5-ffh56428054f" } ``` When contacting Occuspace about a `500` error, always include the `request_id` from the error response. This allows our team to locate the exact request in our logs and diagnose the issue quickly. # Pagination The Occuspace API uses cursor-based pagination to navigate through large result sets. Cursors are more efficient and reliable than traditional page-number pagination, especially for real-time data that may change between requests. ### How It Works When a response contains more results than the requested `limit`, the API returns a cursor in the `pagination` object that you can use to fetch the next or previous page of results. Pagination is supported on all endpoints that return lists or time-series data.
FieldTypeDescription
has_morebooleantrue if additional results are available beyond the current page
next_cursorstringPass this value as the cursor parameter to fetch the next page. null if there are no more results.
prev_cursorstringPass this value as the cursor parameter to fetch the previous page. null if you are on the first page.
### Request Parameters The following query parameters control pagination behavior and are supported on all paginated endpoints:
ParameterTypeRequiredDefaultDescription
limitintegerNo1000The maximum number of results to return per page. Must be between 1 and 1000.
cursorstringNo-The cursor value from a previous response's next_cursor or prev_cursor field. Omit this parameter on your first request.
### Paginating Forward To paginate forward through results, pass the `next_cursor` value from the current response as the `cursor` parameter in your next request. Keep paginating until `has_more` is `false`. {% hint style="info" %} **Always check `has_more` first.** Rather than checking whether `next_cursor` is null, use `has_more` as your primary signal for whether more results are available. This is the most reliable way to detect the end of a result set. {% endhint %} ```bash # Step 1 — First request, no cursor needed curl -X GET "https://api.occuspace.io/v2/locations?limit=3" \ -H "Authorization: Bearer YOUR_API_TOKEN" # Response pagination object: # { # "has_more": true, # "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2MX0", # "prev_cursor": null # } # Step 2 — Pass next_cursor to fetch the next page curl -X GET "https://api.occuspace.io/v2/locations?limit=3&cursor=eyJsb2NhdGlvbl9pZCI6MTU2MX0" \ -H "Authorization: Bearer YOUR_API_TOKEN" # Response pagination object: # { # "has_more": true, # "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2NH0", # "prev_cursor": "eyJsb2NhdGlvbl9pZCI6MTU1OX0" # } # Step 3 — Continue until has_more is false curl -X GET "https://api.occuspace.io/v2/locations?limit=3&cursor=eyJsb2NhdGlvbl9pZCI6MTU2NH0" \ -H "Authorization: Bearer YOUR_API_TOKEN" # Response pagination object: # { # "has_more": false, # "next_cursor": null, # "prev_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2MX0" # } ``` ### Paginating Backward To paginate backward through results, pass the `prev_cursor` value from the current response as the `cursor` parameter in your next request. `prev_cursor` is `null` when you are on the first page of results. ```bash # To go back to the previous page, pass prev_cursor as the cursor parameter curl -X GET "https://api.occuspace.io/v2/locations?limit=3&cursor=eyJsb2NhdGlvbl9pZCI6MTU1OX0" \ -H "Authorization: Bearer YOUR_API_TOKEN" # Response pagination object: # { # "has_more": true, # "next_cursor": "eyJsb2NhdGlvbl9pZCI6MTU2MX0", # "prev_cursor": null # } ``` ### Pagination With Metric Endpoints Pagination works the same way on the Metric endpoints (`/occupancy`, `/traffic`, `/dwell_time`, `/availability`). The `limit` parameter controls how many data points are returned per page, and `cursor` is used to navigate between pages of time-series data. ```bash # First page of occupancy data curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&limit=10" \ -H "Authorization: Bearer YOUR_API_TOKEN" # Next page using next_cursor from the response curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&limit=10&cursor=eyJsb2NhdGlvbl9pZCI6MTU2MCwidGltZXN0YW1wIjoiMjAyNS0xMi0xMFQwMDowMDowMFoiLCJkaXJlY3Rpb24iOiJuZXh0In0" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` {% hint style="info" %} **Include all original parameters when paginating.** When fetching subsequent pages of metric data, always include the same `start_date`, `end_date`, and `interval` parameters alongside your `cursor`. Omitting them may produce unexpected results. {% endhint %} ### Pagination With Child Locations When using `include=children` on the `/locations/{id}` or `/locations/{id}/now` endpoints, the `limit` and `cursor` parameters apply to the child locations returned in `children_data`, not the parent location. The parent location is always returned regardless of pagination. ```bash # First page of children curl -X GET "https://api.occuspace.io/v2/locations/1559?include=children&limit=5" \ -H "Authorization: Bearer YOUR_API_TOKEN" # Next page of children curl -X GET "https://api.occuspace.io/v2/locations/1559?include=children&limit=5&cursor=eyJsb2NhdGlvbl9pZCI6MTU2NH0" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` # Filters The Occuspace API supports optional filters on all metric endpoints that allow you to narrow data to specific hours of the day and days of the week. Filters are independent of each other and can be used in any combination. ### Overview By default, metric endpoints return data based on each location's configured operating hours and days. Filters allow you to override these defaults and focus on a specific time window that is meaningful for your analysis, for example, only business hours on weekdays, or just weekend afternoons. {% hint style="info" %} **Filters are reflected in the response.** Every metric response includes `hour_range` and `days_of_week` fields that echo back the filters applied to the request. If no filters were provided, these fields reflect the location's default operating hours and days making it easy to verify exactly what data window was used. {% endhint %}
ParameterSupported IntervalsDefault
start_hour_filterAllLocation's configured operating hours
end_hour_filterAllLocation's configured operating hours
days_filterAllLocation's configured operating days
### Hour Filter The `start_hour_filter` and `end_hour_filter` parameters let you restrict data to a specific range of hours within each day. Hours are expressed as integers from 0 to 23 using a 24-hour clock. The filters can be used independently, you can provide just `start_hour_filter`, just `end_hour_filter`, or both together.
ParameterTypeValid ValuesDescription
start_hour_filterinteger0-23Only include data at or after this hour of the day
end_hour_filterinteger0-23Only include data up to and including this hour of the day
```bash # Restrict data to business hours only (9am to 5pm) curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&start_hour_filter=9&end_hour_filter=17" \ -H "Authorization: Bearer YOUR_API_TOKEN" # Restrict data to morning hours only (no end_hour_filter needed) curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&interval=daily&start_hour_filter=6&end_hour_filter=12" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ### Day Filter The `days_filter` parameter lets you restrict data to specific days of the week. It is provided as a string of day code digits with no separator, where each digit represents a day of the week. Days can be provided in any order.
CodeDay
1Sunday
2Monday
3Tuesday
4Wednesday
5Thursday
6Friday
7Saturday
For example, to filter to weekdays only (Monday through Friday), pass `days_filter=23456`. To filter to weekends only (Saturday and Sunday), pass `days_filter=17`. ```bash # Weekdays only (Monday through Friday) curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&days_filter=23456" \ -H "Authorization: Bearer YOUR_API_TOKEN" # Weekends only (Saturday and Sunday) curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&days_filter=17" \ -H "Authorization: Bearer YOUR_API_TOKEN" # Mid-week only (Tuesday, Wednesday, Thursday) curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&days_filter=345" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` ### Combining Filters All three filters can be combined freely in a single request. For example, to analyze occupancy during business hours on weekdays only, combine `start_hour_filter`, `end_hour_filter`, and `days_filter` in the same request: ```bash # Business hours (9am-5pm) on weekdays only (Monday through Friday) curl -X GET "https://api.occuspace.io/v2/locations/1559/occupancy?start_date=2025-12-01&end_date=2025-12-31&interval=daily&start_hour_filter=9&end_hour_filter=17&days_filter=23456" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` To confirm which filters were applied, check the `hour_range` and `days_of_week` fields in the response. These always reflect the exact time window used to calculate the returned data: ```json { "location_id": 1559, "name": "Austin Office", "capacity": 10897, "metric": "occupancy", "interval": "daily", "time_range": { "start": "2025-12-01T00:00:00Z", "end": "2025-12-31T23:59:59Z" }, "days_of_week": [2, 3, 4, 5, 6], "hour_range": { "start": 9, "end": 17 }, "data": [...], "pagination": { "has_more": false, "prev_cursor": null, "next_cursor": null } } ``` ### Supported Endpoints Filters are supported on all four metric endpoints. Note that each endpoint supports a different set of intervals, so the intervals on which filters are valid vary accordingly:
EndpointIntervals
GET /locations/{id}/occupancydaily, hourly, weekly, monthly, 60min, 30min, 15min
GET /locations/{id}/trafficdaily, weekly, monthly, 60min
GET /locations/{id}/dwell_timedaily, weekly, monthly
GET /locations/{id}/availabilitydaily, hourly, weekly, monthly, 60min
# Locations The Locations endpoints allow you to retrieve a list of all accessible locations, view details for a specific location, and get real-time occupancy data for any location. ## GET /locations > List of accessible locations ```json {"openapi":"3.0.0","info":{"title":"Occuspace Customer API","version":"2.0.0"},"servers":[{"url":"https://api.occuspace.io/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"LocationsResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Location":{"type":"object","required":["location_id","name","status","parent_id","capacity","start_date"],"properties":{"location_id":{"type":"integer","description":"ID of the location. Can be used on other endpoints for specific resources on the location in question."},"name":{"type":"string","description":"Name of the location."},"status":{"type":"string","enum":["active","inactive","setup","review","calibration"],"description":"Current status of this location."},"parent_id":{"type":"integer","nullable":true,"description":"ID of the parent location. Null if it is the root location."},"capacity":{"type":"integer","description":"Capacity of the location (includes the sum of all children locations if applicable)."},"start_date":{"type":"string","format":"date","nullable":true,"description":"Date string to indicate the earliest measured data. Null if no data has been captured for this location."}}},"Pagination":{"type":"object","required":["prev_cursor","next_cursor","has_more"],"properties":{"prev_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["type","title","status","detail","instance","request_id"],"description":"Error response following the RFC 7807 Problem Details standard","properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem, including relevant identifiers to help with debugging"},"instance":{"type":"string","format":"uri-reference","description":"The specific API path that generated the error"},"request_id":{"type":"string","format":"uuid","description":"A unique identifier for the request, useful for tracing and support"}}}}},"paths":{"/locations":{"get":{"summary":"List of accessible locations","tags":["Locations"],"parameters":[{"name":"limit","description":"Limits how many records are returned in the response.","in":"query","required":false,"schema":{"type":"integer","default":1000,"maximum":1000,"minimum":1}},{"name":"cursor","in":"query","required":false,"description":"Cursor value from the previous response's pagination object used to fetch the next or previous page of results.","schema":{"type":"string"}}],"responses":{"200":{"description":"A flat list of accessible locations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationsResponse"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` *** ## GET /locations/{id} > Get location details ```json {"openapi":"3.0.0","info":{"title":"Occuspace Customer API","version":"2.0.0"},"servers":[{"url":"https://api.occuspace.io/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"LocationDetailResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"$ref":"#/components/schemas/LocationDetail"},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"LocationDetail":{"type":"object","required":["location_id","name","status","parent_id","capacity","start_date"],"properties":{"location_id":{"type":"integer","description":"ID of the location. Can be used on other endpoints for specific resources on the location in question."},"name":{"type":"string","description":"Name of the location."},"status":{"type":"string","enum":["active","inactive","setup","calibration","review"],"description":"Current status of this location."},"parent_id":{"type":"integer","nullable":true,"description":"ID of the parent location. Null if it is the root location."},"capacity":{"type":"integer","description":"Capacity of the location (includes the sum of all children locations if applicable)."},"start_date":{"type":"string","format":"date","nullable":true,"description":"Date string to indicate the earliest measured data. Null if no data has been captured for this location."},"children_data":{"type":"array","description":"Details for each child location. Only present when include=children is passed in the request.","items":{"$ref":"#/components/schemas/LocationDetailChild"}}}},"LocationDetailChild":{"type":"object","description":"Location details for a child location","properties":{"location_id":{"type":"integer","description":"ID of the child location."},"name":{"type":"string","description":"Name of this child location."},"status":{"type":"string","enum":["active","inactive","setup","calibration","review"],"description":"Current status of this child location."},"parent_id":{"type":"integer","nullable":true,"description":"ID of this child's parent location."},"capacity":{"type":"integer","description":"Capacity of this child location."},"start_date":{"type":"string","format":"date","nullable":true,"description":"Date string to indicate the earliest measured data. Null if no data has been captured for this location."}}},"Pagination":{"type":"object","required":["prev_cursor","next_cursor","has_more"],"properties":{"prev_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["type","title","status","detail","instance","request_id"],"description":"Error response following the RFC 7807 Problem Details standard","properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem, including relevant identifiers to help with debugging"},"instance":{"type":"string","format":"uri-reference","description":"The specific API path that generated the error"},"request_id":{"type":"string","format":"uuid","description":"A unique identifier for the request, useful for tracing and support"}}}}},"paths":{"/locations/{id}":{"get":{"summary":"Get location details","tags":["Locations"],"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the location.","schema":{"type":"integer"}},{"name":"include","in":"query","required":false,"description":"Pass \"children\" to include child locations of the current location in the response.","schema":{"type":"string","enum":["children"]}},{"name":"limit","in":"query","required":false,"description":"Maximum number of children to return per page when using include=children. Defaults to 1000 if not specified.","schema":{"type":"integer","default":1000}},{"name":"cursor","in":"query","required":false,"description":"Cursor value from the previous response's pagination object used to fetch the next or previous page of children when using include=children.","schema":{"type":"string"}}],"responses":{"200":{"description":"Location details found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationDetailResponse"}}}},"404":{"description":"Location not found or not accessible with the provided credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` *** ## GET /locations/{id}/now > Get real-time occupancy data for a location ```json {"openapi":"3.0.0","info":{"title":"Occuspace Customer API","version":"2.0.0"},"servers":[{"url":"https://api.occuspace.io/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"LocationNowResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"$ref":"#/components/schemas/LocationNow"},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"LocationNow":{"type":"object","required":["location_id","name","status","count","percentage","timestamp"],"description":"Current occupancy data for a location","properties":{"location_id":{"type":"integer","description":"ID of this location."},"name":{"type":"string","description":"Name of this location."},"status":{"type":"string","enum":["active","inactive","setup","calibration","review"],"description":"Current status of this location."},"count":{"type":"integer","description":"Current number of people estimated at this location."},"percentage":{"type":"number","format":"float","description":"Current count occupancy as a fraction of capacity."},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp of when the current count estimation."},"children_data":{"type":"array","description":"Only present when include=children is passed in the request.","items":{"$ref":"#/components/schemas/LocationNowChild"}}}},"LocationNowChild":{"type":"object","description":"Current occupancy data for a child location","properties":{"location_id":{"type":"integer","description":"ID of the child location."},"name":{"type":"string","description":"Name of this child location."},"status":{"type":"string","enum":["active","inactive","setup","review","calibration"],"description":"Current status of this child location."},"count":{"type":"integer","description":"Current number of people estimated at this child location."},"percentage":{"type":"number","format":"float","description":"Current count occupancy as a fraction of capacity."}}},"Pagination":{"type":"object","required":["prev_cursor","next_cursor","has_more"],"properties":{"prev_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["type","title","status","detail","instance","request_id"],"description":"Error response following the RFC 7807 Problem Details standard","properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem, including relevant identifiers to help with debugging"},"instance":{"type":"string","format":"uri-reference","description":"The specific API path that generated the error"},"request_id":{"type":"string","format":"uuid","description":"A unique identifier for the request, useful for tracing and support"}}}}},"paths":{"/locations/{id}/now":{"get":{"summary":"Get real-time occupancy data for a location","tags":["Locations"],"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the location.","schema":{"type":"integer"}},{"name":"include","in":"query","required":false,"description":"Pass \"children\" to include current occupancy for child locations in the response.","schema":{"type":"string","enum":["children"]}},{"name":"limit","in":"query","required":false,"description":"Maximum number of children to return per page when using include=children. Defaults to 1000 if not specified.","schema":{"type":"integer","default":1000}},{"name":"cursor","in":"query","required":false,"description":"Cursor value from the previous response's pagination object used to fetch the next page of children when using include=children.","schema":{"type":"string"}}],"responses":{"200":{"description":"Current real-time occupancy data for the location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationNowResponse"}}}},"404":{"description":"Location not found or not accessible with the provided credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` # Metrics The Metrics endpoints provide historical space analytics data for Occuspace-enabled locations. Each endpoint supports flexible date ranges, intervals, and optional filters for hour of day and day of week. {% hint style="info" %} There are a variety of different data sets and aggregations provided by Occuspace in this API, and it is important to use the correct configuration for your given use case. We highly encourage our customers to reach out to us when starting to use this API. Occuspace Customer Success Managers can help identify which particular metric, data set, and aggregation makes the most sense to utilize. {% endhint %} ## Get Occupancy metrics for a location > Returns historical occupancy metrics for a specific location over a given date range and interval. Supports optional hour and day filters for all intervals. ```json {"openapi":"3.0.0","info":{"title":"Occuspace Customer API","version":"2.0.0"},"servers":[{"url":"https://api.occuspace.io/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"OccupancyResponse":{"type":"object","required":["location_id","name","capacity","metric","interval","time_range","days_of_week","hour_range","data","pagination"],"properties":{"location_id":{"type":"integer","description":"The ID of the location."},"name":{"type":"string","description":"The name of the location."},"capacity":{"type":"integer","description":"The total capacity of the location."},"metric":{"type":"string","description":"The metric type returned."},"interval":{"type":"string","description":"The time interval used to aggregate the data.","enum":["daily","hourly","weekly","monthly","60min","30min","15min"]},"time_range":{"$ref":"#/components/schemas/TimeRange"},"days_of_week":{"type":"array","description":"The days of the week included in the response data. Reflects the days_filter parameter if provided, otherwise includes all days. 1=Sunday through 7=Saturday.","items":{"type":"integer","minimum":1,"maximum":7}},"hour_range":{"$ref":"#/components/schemas/HourRange"},"data":{"type":"array","description":"The occupancy data points for the requested time range and interval.","items":{"$ref":"#/components/schemas/OccupancyDataPoint"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"TimeRange":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"The start of the requested time range in UTC."},"end":{"type":"string","format":"date-time","description":"The end of the requested time range in UTC."}}},"HourRange":{"type":"object","required":["start","end"],"properties":{"start":{"type":"integer","description":"The start hour filter applied to the request. Defaults to the assigned operating hours for this location.","minimum":0,"maximum":23},"end":{"type":"integer","description":"The end hour filter applied to the request. Defaults to the assigned operating hours for this location.","minimum":0,"maximum":23}}},"OccupancyDataPoint":{"type":"object","required":["timestamp","window_start","window_end","avg_occupancy","avg_utilization_percentage","peak_occupancy","peak_utilization_percentage"],"properties":{"timestamp":{"type":"string","format":"date-time","description":"The start timestamp of the data point window in UTC."},"window_start":{"type":"string","format":"date-time","description":"The start of the aggregation window in UTC."},"window_end":{"type":"string","format":"date-time","description":"The end of the aggregation window in UTC."},"avg_occupancy":{"type":"integer","description":"The average number of people during the window."},"avg_utilization_percentage":{"type":"number","format":"float","description":"The average occupancy as a fraction of total capacity during the window."},"peak_occupancy":{"type":"integer","description":"The highest number of people detected at any point during the window."},"peak_utilization_percentage":{"type":"number","format":"float","description":"The peak occupancy as a fraction of total capacity during the window."}}},"Pagination":{"type":"object","required":["prev_cursor","next_cursor","has_more"],"properties":{"prev_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["type","title","status","detail","instance","request_id"],"description":"Error response following the RFC 7807 Problem Details standard","properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem, including relevant identifiers to help with debugging"},"instance":{"type":"string","format":"uri-reference","description":"The specific API path that generated the error"},"request_id":{"type":"string","format":"uuid","description":"A unique identifier for the request, useful for tracing and support"}}}}},"paths":{"/locations/{id}/occupancy":{"get":{"summary":"Get Occupancy metrics for a location","description":"Returns historical occupancy metrics for a specific location over a given date range and interval. Supports optional hour and day filters for all intervals.","tags":["Metrics"],"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the location.","schema":{"type":"integer"}},{"name":"start_date","in":"query","required":true,"description":"The start date of the requested time range in YYYY-MM-DD format.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":true,"description":"The end date of the requested time range in YYYY-MM-DD format.","schema":{"type":"string","format":"date"}},{"name":"interval","in":"query","required":false,"description":"The time interval to aggregate occupancy data by.","schema":{"type":"string","enum":["daily","hourly","weekly","monthly","60min","30min","15min"],"default":"daily"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of data points to return per page. Defaults to 1000 if not specified.","schema":{"type":"integer","default":1000}},{"name":"cursor","in":"query","required":false,"description":"Cursor value from the previous response's pagination object used to fetch the next or previous page of results.","schema":{"type":"string"}},{"name":"start_hour_filter","in":"query","required":false,"description":"Filter data to only include readings at or after this hour of the day. Valid values are 0-24. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"integer","minimum":0,"maximum":23}},{"name":"end_hour_filter","in":"query","required":false,"description":"Filter data to only include readings before or at this hour of the day. Valid values are 0-24. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"integer","minimum":0,"maximum":23}},{"name":"days_filter","in":"query","required":false,"description":"Filter data to only include specific days of the week. Provided as a string of day codes with no separator where 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday. For example '23456' means Monday through Friday. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"string","pattern":"^[1-7]+$"}}],"responses":{"200":{"description":"Occupancy metrics for the location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OccupancyResponse"}}}},"400":{"description":"Bad request — one or more request parameters are invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Location not found or not accessible with the provided credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` *** ## Get Traffic metrics for a location > Returns visits for a specific location over a given date range and interval. Traffic represents the total number of people who entered the location during each interval window. Supports optional hour and day filters for all intervals. ```json {"openapi":"3.0.0","info":{"title":"Occuspace Customer API","version":"2.0.0"},"servers":[{"url":"https://api.occuspace.io/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TrafficResponse":{"type":"object","required":["location_id","name","capacity","metric","interval","time_range","days_of_week","hour_range","data","pagination"],"properties":{"location_id":{"type":"integer","description":"The ID of the location."},"name":{"type":"string","description":"The name of the location."},"capacity":{"type":"integer","description":"The total capacity of the location."},"metric":{"type":"string","description":"The metric type returned."},"interval":{"type":"string","description":"The time interval used to aggregate the data.","enum":["daily","weekly","monthly","60min"]},"time_range":{"$ref":"#/components/schemas/TimeRange"},"days_of_week":{"type":"array","description":"The days of the week included in the response data. Reflects the days_filter parameter if provided, otherwise includes all days. 1=Sunday through 7=Saturday.","items":{"type":"integer","minimum":1,"maximum":7}},"hour_range":{"$ref":"#/components/schemas/HourRange"},"data":{"type":"array","description":"The traffic data points for the requested time range and interval.","items":{"$ref":"#/components/schemas/TrafficDataPoint"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"TimeRange":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"The start of the requested time range in UTC."},"end":{"type":"string","format":"date-time","description":"The end of the requested time range in UTC."}}},"HourRange":{"type":"object","required":["start","end"],"properties":{"start":{"type":"integer","description":"The start hour filter applied to the request. Defaults to the assigned operating hours for this location.","minimum":0,"maximum":23},"end":{"type":"integer","description":"The end hour filter applied to the request. Defaults to the assigned operating hours for this location.","minimum":0,"maximum":23}}},"TrafficDataPoint":{"type":"object","required":["timestamp","window_start","window_end","traffic"],"properties":{"timestamp":{"type":"string","format":"date-time","description":"The start timestamp of the data point window in UTC."},"window_start":{"type":"string","format":"date-time","description":"The start of the aggregation window in UTC."},"window_end":{"type":"string","format":"date-time","description":"The end of the aggregation window in UTC."},"traffic":{"type":"integer","description":"The total number of people who entered the location during the window."}}},"Pagination":{"type":"object","required":["prev_cursor","next_cursor","has_more"],"properties":{"prev_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["type","title","status","detail","instance","request_id"],"description":"Error response following the RFC 7807 Problem Details standard","properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem, including relevant identifiers to help with debugging"},"instance":{"type":"string","format":"uri-reference","description":"The specific API path that generated the error"},"request_id":{"type":"string","format":"uuid","description":"A unique identifier for the request, useful for tracing and support"}}}}},"paths":{"/locations/{id}/traffic":{"get":{"summary":"Get Traffic metrics for a location","description":"Returns visits for a specific location over a given date range and interval. Traffic represents the total number of people who entered the location during each interval window. Supports optional hour and day filters for all intervals.","tags":["Metrics"],"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the location.","schema":{"type":"integer"}},{"name":"start_date","in":"query","required":true,"description":"The start date of the requested time range in YYYY-MM-DD format.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":true,"description":"The end date of the requested time range in YYYY-MM-DD format.","schema":{"type":"string","format":"date"}},{"name":"interval","in":"query","required":false,"description":"The time interval to aggregate traffic data by. Defaults to daily if not specified.","schema":{"type":"string","enum":["daily","weekly","monthly","60min"],"default":"daily"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of data points to return per page. Defaults to 1000 if not specified.","schema":{"type":"integer","default":1000}},{"name":"cursor","in":"query","required":false,"description":"Cursor value from the previous response's pagination object used to fetch the next or previous page of results.","schema":{"type":"string"}},{"name":"start_hour_filter","in":"query","required":false,"description":"Filter data to only include readings at or after this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"integer","minimum":0,"maximum":23}},{"name":"end_hour_filter","in":"query","required":false,"description":"Filter data to only include readings before or at this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"integer","minimum":0,"maximum":23}},{"name":"days_filter","in":"query","required":false,"description":"Filter data to only include specific days of the week. Provided as a string of day codes with no separator where 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday. For example '23456' means Monday through Friday. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"string","pattern":"^[1-7]+$"}}],"responses":{"200":{"description":"Traffic metrics for the location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrafficResponse"}}}},"400":{"description":"Bad request — one or more request parameters are invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Location not found or not accessible with the provided credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` *** ## Get Dwell Time metrics for a location > Returns historical dwell time metrics for a specific location over a given date range and interval. Dwell time represents how long people stayed in the location during each interval window, expressed in seconds. Supports optional hour and day filters for all intervals. ```json {"openapi":"3.0.0","info":{"title":"Occuspace Customer API","version":"2.0.0"},"servers":[{"url":"https://api.occuspace.io/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DwellTimeResponse":{"type":"object","required":["location_id","name","capacity","metric","interval","time_range","days_of_week","hour_range","data","pagination"],"properties":{"location_id":{"type":"integer","description":"The ID of the location."},"name":{"type":"string","description":"The name of the location."},"capacity":{"type":"integer","description":"The total capacity of the location."},"metric":{"type":"string","description":"The metric type returned."},"interval":{"type":"string","description":"The time interval used to aggregate the data.","enum":["daily","weekly","monthly"]},"time_range":{"$ref":"#/components/schemas/TimeRange"},"days_of_week":{"type":"array","description":"The days of the week included in the response data. Reflects the days_filter parameter if provided, otherwise includes all days. 1=Sunday through 7=Saturday.","items":{"type":"integer","minimum":1,"maximum":7}},"hour_range":{"$ref":"#/components/schemas/HourRange"},"data":{"type":"array","description":"The dwell time data points for the requested time range and interval.","items":{"$ref":"#/components/schemas/DwellTimeDataPoint"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"TimeRange":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"The start of the requested time range in UTC."},"end":{"type":"string","format":"date-time","description":"The end of the requested time range in UTC."}}},"HourRange":{"type":"object","required":["start","end"],"properties":{"start":{"type":"integer","description":"The start hour filter applied to the request. Defaults to the assigned operating hours for this location.","minimum":0,"maximum":23},"end":{"type":"integer","description":"The end hour filter applied to the request. Defaults to the assigned operating hours for this location.","minimum":0,"maximum":23}}},"DwellTimeDataPoint":{"type":"object","required":["timestamp","window_start","window_end","avg_dwell_time","peak_dwell_time"],"properties":{"timestamp":{"type":"string","format":"date-time","description":"The start timestamp of the data point window in UTC."},"window_start":{"type":"string","format":"date-time","description":"The start of the aggregation window in UTC."},"window_end":{"type":"string","format":"date-time","description":"The end of the aggregation window in UTC."},"avg_dwell_time":{"type":"integer","nullable":true,"description":"The average time in minutes people spent in the location during the window. Null if no data was available for this window."},"peak_dwell_time":{"type":"integer","nullable":true,"description":"The longest time in minutes any individual spent in the location during the window. Null if no data was available for this window."}}},"Pagination":{"type":"object","required":["prev_cursor","next_cursor","has_more"],"properties":{"prev_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["type","title","status","detail","instance","request_id"],"description":"Error response following the RFC 7807 Problem Details standard","properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem, including relevant identifiers to help with debugging"},"instance":{"type":"string","format":"uri-reference","description":"The specific API path that generated the error"},"request_id":{"type":"string","format":"uuid","description":"A unique identifier for the request, useful for tracing and support"}}}}},"paths":{"/locations/{id}/dwell_time":{"get":{"summary":"Get Dwell Time metrics for a location","description":"Returns historical dwell time metrics for a specific location over a given date range and interval. Dwell time represents how long people stayed in the location during each interval window, expressed in seconds. Supports optional hour and day filters for all intervals.","tags":["Metrics"],"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the location.","schema":{"type":"integer"}},{"name":"start_date","in":"query","required":true,"description":"The start date of the requested time range in YYYY-MM-DD format.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":true,"description":"The end date of the requested time range in YYYY-MM-DD format.","schema":{"type":"string","format":"date"}},{"name":"interval","in":"query","required":false,"description":"The time interval to aggregate dwell time data by. Defaults to daily if not specified.","schema":{"type":"string","enum":["daily","weekly","monthly"],"default":"daily"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of data points to return per page. Defaults to 1000 if not specified.","schema":{"type":"integer","default":1000}},{"name":"cursor","in":"query","required":false,"description":"Cursor value from the previous response's pagination object used to fetch the next or previous page of results.","schema":{"type":"string"}},{"name":"start_hour_filter","in":"query","required":false,"description":"Filter data to only include readings at or after this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"integer","minimum":0,"maximum":23}},{"name":"end_hour_filter","in":"query","required":false,"description":"Filter data to only include readings before or at this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"integer","minimum":0,"maximum":23}},{"name":"days_filter","in":"query","required":false,"description":"Filter data to only include specific days of the week. Provided as a string of day codes with no separator where 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday. For example '23456' means Monday through Friday. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"string","pattern":"^[1-7]+$"}}],"responses":{"200":{"description":"Dwell time metrics for the location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DwellTimeResponse"}}}},"400":{"description":"Bad request — one or more request parameters are invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Location not found or not accessible with the provided credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` *** ## Get Availability metrics for a location > Returns historical availability metrics for a specific location over a given date range and interval. Availability represents the percentage of time the location was unoccupied during each interval window. Null values indicate no data was available for that window, typically on days outside operating hours. Supports optional hour and day filters for daily, weekly, and monthly intervals. ```json {"openapi":"3.0.0","info":{"title":"Occuspace Customer API","version":"2.0.0"},"servers":[{"url":"https://api.occuspace.io/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"AvailabilityResponse":{"type":"object","required":["location_id","name","capacity","metric","interval","time_range","days_of_week","hour_range","data","pagination"],"properties":{"location_id":{"type":"integer","description":"The ID of the location."},"name":{"type":"string","description":"The name of the location."},"capacity":{"type":"integer","description":"The total capacity of the location."},"metric":{"type":"string","description":"The metric type returned."},"interval":{"type":"string","description":"The time interval used to aggregate the data.","enum":["daily","hourly","weekly","monthly","60min"]},"time_range":{"$ref":"#/components/schemas/TimeRange"},"days_of_week":{"type":"array","description":"The days of the week included in the response data. Reflects the days_filter parameter if provided, otherwise includes all days. 1=Sunday through 7=Saturday.","items":{"type":"integer","minimum":1,"maximum":7}},"hour_range":{"$ref":"#/components/schemas/HourRange"},"data":{"type":"array","description":"The availability data points for the requested time range and interval.","items":{"$ref":"#/components/schemas/AvailabilityDataPoint"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"TimeRange":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"The start of the requested time range in UTC."},"end":{"type":"string","format":"date-time","description":"The end of the requested time range in UTC."}}},"HourRange":{"type":"object","required":["start","end"],"properties":{"start":{"type":"integer","description":"The start hour filter applied to the request. Defaults to the assigned operating hours for this location.","minimum":0,"maximum":23},"end":{"type":"integer","description":"The end hour filter applied to the request. Defaults to the assigned operating hours for this location.","minimum":0,"maximum":23}}},"AvailabilityDataPoint":{"type":"object","required":["timestamp","window_start","window_end","availability_percentage"],"properties":{"timestamp":{"type":"string","format":"date-time","description":"The start timestamp of the data point window in UTC."},"window_start":{"type":"string","format":"date-time","description":"The start of the aggregation window in UTC."},"window_end":{"type":"string","format":"date-time","description":"The end of the aggregation window in UTC."},"availability_percentage":{"type":"number","format":"float","nullable":true,"description":"The percentage of time the location was unoccupied during the window, expressed as a fraction between 0 and 1. Null if no data was available for this window, typically on days outside operating hours."}}},"Pagination":{"type":"object","required":["prev_cursor","next_cursor","has_more"],"properties":{"prev_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["type","title","status","detail","instance","request_id"],"description":"Error response following the RFC 7807 Problem Details standard","properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem, including relevant identifiers to help with debugging"},"instance":{"type":"string","format":"uri-reference","description":"The specific API path that generated the error"},"request_id":{"type":"string","format":"uuid","description":"A unique identifier for the request, useful for tracing and support"}}}}},"paths":{"/locations/{id}/availability":{"get":{"summary":"Get Availability metrics for a location","description":"Returns historical availability metrics for a specific location over a given date range and interval. Availability represents the percentage of time the location was unoccupied during each interval window. Null values indicate no data was available for that window, typically on days outside operating hours. Supports optional hour and day filters for daily, weekly, and monthly intervals.","tags":["Metrics"],"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the location.","schema":{"type":"integer"}},{"name":"start_date","in":"query","required":true,"description":"The start date of the requested time range in YYYY-MM-DD format.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":true,"description":"The end date of the requested time range in YYYY-MM-DD format.","schema":{"type":"string","format":"date"}},{"name":"interval","in":"query","required":false,"description":"The time interval to aggregate availability data by. Defaults to daily if not specified.","schema":{"type":"string","enum":["daily","hourly","weekly","monthly","60min"],"default":"daily"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of data points to return per page. Defaults to 1000 if not specified.","schema":{"type":"integer","default":1000}},{"name":"cursor","in":"query","required":false,"description":"Cursor value from the previous response's pagination object used to fetch the next or previous page of results.","schema":{"type":"string"}},{"name":"start_hour_filter","in":"query","required":false,"description":"Filter data to only include readings at or after this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"integer","minimum":0,"maximum":23}},{"name":"end_hour_filter","in":"query","required":false,"description":"Filter data to only include readings before or at this hour of the day. Valid values are 0-23. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"integer","minimum":0,"maximum":23}},{"name":"days_filter","in":"query","required":false,"description":"Filter data to only include specific days of the week. Provided as a string of day codes with no separator where 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday. For example '23456' means Monday through Friday. Only supported for daily, weekly, and monthly intervals.","schema":{"type":"string","pattern":"^[1-7]+$"}}],"responses":{"200":{"description":"Availability metrics for the location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityResponse"}}}},"400":{"description":"Bad request — one or more request parameters are invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Location not found or not accessible with the provided credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ```