V9 Server API

This section describes the list of available cubes and their dimensions and measures. The cubes are callable from cube.footfallcam.com using REST API or SQL API. The returned data is governed by data storage policy: Appendix C - Metrics Definition V2 - FootfallCam.

The returned data is also limited to 1,000,000 rows.

Please refer to the REST API and SQL API Example below for an example on how to send an API request.

---

ffc_site_info

This cube provides information for each main entrance area of each site. It returns all value combinations of selected dimensions and aggregates the selected measures.

Dimensions

Dimension	Description
CompanyName	The name of the company which owns the site.
SiteName	The name of the site.
SiteId	The identifier of the site.
SiteCode	The code name of the site.
SiteGroupName	The name of the group of the site.
SiteVerifiedDate	Verified datetime of the site. Returns 1900-01-01 00:00:00 if the site is not verified.

---

ffc_site_summary

This cube provides information for each main entrance area of each site. Users can narrow down site selection and time range for faster query load time. It returns all value combinations of selected dimensions and aggregates the selected measures.

Dimensions

Dimension	Description
CompanyName	The name of the company which owns the site.
SiteName	The name of the site.
SiteId	The identifier of the site.
SiteCode	The code name of the site.
SiteGroupName	The name of the group of the site.
Time	Local time of the site. Time granularity respects metric documentation. Valid granularity inputs are day, hour, minute. Default granularity is day. This dimension cannot be used together with Time15Minute.
Time15Minute	Local time of the site rounded down to a 15-minute interval period. This dimension cannot be used together with Time.
IsOperating	1 if the site is operating, 0 otherwise.
IsSiteVerified	1 if the site is verified, 0 otherwise.
AggregationStatus	Complete if there is no data hole. Missing Data if there is a data hole. Precheck if pending for checking. Late Data if there is late data and will be updated to Complete or Missing Data in the future.
AggregationStatus_A04	Status applicable for day granularity. Values include Complete, Missing Data, Data Not Enough, and Precheck.

Measures

All measures below are considered at main entrance only. For further details refer to Appendix C - Metrics Definition V2 - FootfallCam.

Measure	Description
A01 (Total Footfall In Count)	Number of footfalls counted entering the main entrance area of the site.
A02 (Total Footfall Out Count)	Number of footfalls counted exiting the main entrance area of the site.
A03 (Average Occupancy)	Average number of people detected on that site.
A04 (Average Dwell Time)	Average time spent by people on that site.
A18 (Total Children Footfall In Count)	Number of children entering the main entrance area of the site.
A05 (Total Outside Traffic Count)	Number of visitors detected outside the site.
B01 (Average Turn-in Rate)	Fraction of total footfall traffic that visits the site.
B02 (Average Visitor Returning Rate)	Fraction of visitors that return to the site in the past 60 days.

---

ffc_area_summary

This cube provides information for each area within a site. Users can narrow down site, area, and time range for faster query load time. It returns all value combinations of selected dimensions and aggregates the selected measures.

Dimensions

Dimension	Description
CompanyName	The name of the company that owns the area.
SiteName	The name of the site that owns the area.
AreaName	The name of the area of the site.
AreaGroupName	The name of the group that the area belongs in.
AreaGroupTypeName	The type name of the group that the area belongs in.
Time	Local time of the site. Time granularity respects metric documentation. Valid granularity inputs are day, hour, minute. Default granularity is day.

Measures

For further details about the measures, refer to Appendix C - Metrics Definition V2 - FootfallCam.

Measure	Description
A01 (Total Footfall In Count)	Number of visitors that enter the area.
A02 (Total Footfall Out Count)	Number of visitors that exit the area.
A03 (Average Occupancy)	Number of visitors detected within the area.
Understaff_A03 (Understaffed)	Number of staff is lower than the lower threshold.
Overstaff_A03 (Overstaffed)	Number of staff is higher than the upper threshold.
Optimalstaff_A03 (Optimal Staffing)	Number of staff is higher than the upper threshold and lower than the lower threshold.
A04 (Average Visit Duration)	Average time spent by visitors within the area.
A18 (Total Children Footfall In Count)	Number of children that enter the area.
A05 (Total Outside Traffic Count)	Number of visitors detected outside the area.
B01 (Average Turn-in Rate)	Fraction of total footfall traffic that visits the site.
B02 (Average Visitor Returning Rate)	Fraction of visitors that return to the area in the past 60 days.

---

ffc_device_summary

This cube provides information for each device. Users can narrow down site and time range for faster query load time. It returns all value combinations of selected dimensions and aggregates the selected measures.

Dimensions

Dimension	Description
CompanyId	The Id of the company which owns the device.
CompanyName	The name of the company which owns the device.
SiteId	The Id of the site which device is allocated to.
SiteName	The name of the site which device is allocated to.
CompanySerial	A serial assigned to the device.
CameraId	The identifier of the camera device in integer format.
CameraName	The assigned name for the camera device.
Time	Local time of the site. Time granularity respects metric documentation. Valid granularity inputs are day, hour, minute. Default granularity is day.

Measures

For further details about the measures, refer to Appendix C - Metrics Definition V2 - FootfallCam.

Measure	Description
A01 (Total Footfall In Count)	Number of visitors that pass through the IN line of the device.
A02 (Total Footfall Out Count)	Number of visitors that pass through the OUT line of the device.
A03 (Average Occupancy)	Number of visitors detected within the device sensor's range.
A04 (Average Visit Duration)	Time spent by visitors within the device sensor's range.
A18 (Total Children Footfall In Count)	Number of children who pass through the IN line of the device.
A05 (Total Outside Traffic Count)	Number of visitors detected by device's Wi-Fi sensor.

---

patrol_summary

This view provides patrol-related metrics for each site and session instance. It returns all value combinations of selected company, site, and session dimensions, and aggregates patrol compliance measures such as completed patrols and missed patrols.

Dimensions

Dimension	Description
CompanyId	The Id of the company which owns the device.
CompanyName	The name of the company which owns the device.
SiteName	The name of the site which the device is allocated to.
SiteId	The identifier of the site.
SiteCode	The code name of the site.
StoreType	Type of the store.
SessionId	The id of the patrol session.
SessionInstanceStartDateTime	The scheduled start time of the patrol session.
SessionInstanceEndDateTime	The scheduled end time of the patrol session.
ActualStartTime	The actual start time of the patrol session.
ActualEndTime	The actual end time of the patrol session.
ZoneCovered	The zones that are covered in the particular patrol session.
ZoneCoveragePercentage	The percentage of zones covered out of all existing zones under the patrol session.

Measures

Measure	Description
J01 (Completed Patrols)	Total number of completed patrols.
J02 (Missing Patrols)	Total number of missing patrols.

---

occupancy_summary

This view provides occupancy metrics for each area within a site, along with related configurations, groupings, and operational context. It enables analysis of occupancy levels across time and space.

Dimensions

Dimension	Description
CompanyId	The Id of the company which owns the device.
CompanyName	The name of the company which owns the device.
SiteName	The name of the site which the device is allocated to.
SiteId	The identifier of the site.
SiteCode	The code name of the site.
StoreType	Type of the store.
AreaId	The identifier of the area.
AreaCode	The code name of the area.
AreaName	Name of the area.
AreaGroupName	Group name of the area.
ConfigurationId	Id based on role.
ConfigurationName	Name of configuration.
Time	Timestamp of the occupancy data.
OperateDate	Operating date of the occupancy record.

Measures

Measure	Description
CA03 (Average Occupancy with Configuration)	Average occupancy based on Configuration Id (Staff).

---

REST API Example

This section explains how to obtain data through REST API.

Users can use applications such as Postman to call the API. The query body is in JSON format.

The REST API requires a bearer token header which can be obtained via Access Token - FootfallCam.

The example below shows how to obtain total daily visitors count of Site A and Site B from the ffc_site_summary cube from 1 October 2024 to 25 October 2024.

The example limits the returned rows to 10,000.

---

Request

Field	Value
Endpoint	https://cube.footfallcam.com/API/v1/load
Method	POST
Header	Bearer [Access Token]

Payload

{
  "query": {
    "measures": [
      "ffc_site_summary.A01",
      "ffc_site_summary.A05"
    ],
    "dimensions": [
      "ffc_site_summary.SiteName"
    ],
    "timeDimensions": [
      {
        "dimension": "ffc_site_summary.Time",
        "granularity": "day",
        "dateRange": [
          "2024-10-01",
          "2024-10-25"
        ]
      }
    ],
    "filters": [
      {
        "member": "ffc_site_summary.SiteName",
        "operator": "equals",
        "values": [
          "Site A",
          "Site B"
        ]
      }
    ],
    "order": [
      [
        "ffc_site_summary.SiteName",
        "asc"
      ],
      [
        "ffc_site_summary.Time",
        "asc"
      ]
    ],
    "limit": 10000
  }
}

---

Response

{
  "data": [
    {
      "ffc_site_summary.SiteName": "Site A",
      "ffc_site_summary.Time.day": "2024-10-01T00:00:00.000",
      "ffc_site_summary.Time": "2024-10-01T00:00:00.000",
      "ffc_site_summary.A01": 62,
      "ffc_site_summary.A05": 92
    },
    {
      "ffc_site_summary.SiteName": "Site A",
      "ffc_site_summary.Time.day": "2024-10-02T00:00:00.000",
      "ffc_site_summary.Time": "2024-10-02T00:00:00.000",
      "ffc_site_summary.A01": 46,
      "ffc_site_summary.A05": 58
    },
    ...
    {
      "ffc_site_summary.SiteName": "Site B",
      "ffc_site_summary.Time.day": "2024-10-25T00:00:00.000",
      "ffc_site_summary.Time": "2024-10-25T00:00:00.000",
      "ffc_site_summary.A01": 92,
      "ffc_site_summary.A05": 148
    }
  ]
}

---

SQL API Example

This section describes how to obtain data from V9 Server using SQL API.

Popular applications such as PowerBI and DBeaver use this method.

The example below shows how to obtain total daily visitors count from ffc_site_summary cube with branch name dimension from 1 October 2024 to 25 October 2024.

It also limits the number of returned rows to 10000.

Field	Value
Connection URL	cube.footfallcam.com:6432
Driver	PostgreSQL

SQL Statement

SELECT BranchName, DATE_TRUNC('day', Time), A01
FROM ffc_site_summary
WHERE Time BETWEEN '2024-10-01' AND '2024-10-25'
LIMIT 10000

ServiceNow Integration (REST API endpoints)

Ticket creation

Create support ticket to FootfallCam (outbound from ServiceNow)

Description	Value
Endpoint	https://support.footfallcam.com/SupportTicket/CreateSupportTicketExternal
Method	POST
Headers	AToken - Refer to this guide on how to generate access token

Payload

{
    "TicketSubject":"Ticket Subject",
    "CategoryId":1,
    "MessageContent":"testing",
    "TicketSource":3,
    "IssueLevel":"company",
    "BranchIDs":"",
    "BranchID":0,
    "ThirdPartyTicketId":"INC0053746",
    "RequesterEmailAddress": "[email protected]"
}

Parameter description

Field	Description
Ticket subject	- DataType: string - Subject of the ticket
MessageContent	- DataType: string - Message that will be sent into support ticket chat section
TicketSource	- DataType: long - 3
IssueLevel	- DataType: string - site: to report site issue - company: to report company issue
BranchIDs	- DataType: string - Mandatory when reporting multiple site issues.
TicketReferenceId	- DataType: string - Unique identifier of the ticket from ServiceNow

---

Create support ticket to ServiceNow (inbound to ServiceNow)

Description	Value
Endpoint	ServiceNow REST API endpoint
Method	POST
Headers	Please specify if any

Payload

{
    "u_ticketreferenceid":"Test123",
    "u_ticket_subject":"Testing Integration",
    "u_category":"Technical Question",
    "u_sub_category":"High In Out Discrepancy",
    "u_messagecontent":"Testing Integration Description",
    "u_state":"open"
}

Parameter description

Field	Description
Ticket subject	- DataType: string - Subject of the ticket
MessageContent	- DataType: string - Message that will be sent into support ticket chat section
TicketReferenceId	- DataType: string - Unique identifier of the ticket from FootfallCam

---

Ticket status

Update support ticket (outbound from ServiceNow)

Description	Value
Endpoint	https://support.footfallcam.com/SupportTicket/UpdateTicketExternal
Method	POST
Headers	AToken - Refer to this guide on how to generate access token

Payload

{
    "TicketReferenceId": "3001-0123",
    "Status": "Closed",
    "CCEmailAddress": "[email protected]|[email protected]",
    "ETA": "2022-10-11 03:00:00",
    "TicketSource":3,
    "Category": 132,
    "SubCategory":226,
    "ResolutionCode":13,
    "ResolutionNote": "close",
    "EmailAddress": "[email protected]"
}

Parameter description

Field	Description
TicketReferenceId	- DataType: string - Unique identifier of the ticket from ServiceNow
Status	- DataType: string - List of status: - open - closed
CCEmailAddress	- DataType: array of string - Email address updated in the ticket will receive notification when there’s update to the ticket - Add | in between emails if there is more than 1 email address for FFC’s support portal to identify.
ETA	- DataType: datetime - Format: yyyy-MM-dd HH:mm:ss
TicketSource	- DataType: long - 3
Category (subcategory in FFC ticket)	- DataType: int - 132 (Technical Question)
SubCategory	- DataType: int

SubCategory Mapping

SNOW Ticket Sub-Category	FFC Support Portal Ticket SubCategory ID	FFC Support Portal Ticket Subcategory
Data Discrepancy	226	High In Out Discrepancy
Missing Data	284	Missing Counting Data
Device Issue	293	Uncategorised Device Issue

ResolutionCode

Field	Description
ResolutionCode	- DataType: int

Resolution Code Mapping

SNOW Resolution Codes	FFC Resolution Codes ID	FFC Resolution Codes
Mislogged	14	Propose to Close - Request Denied
Solved (Work Around)	6	Propose to Close - Issue(s) Solved
Not Solved (Not Reproducible)	13	Propose to Close - No Issue Found
Solved (Permanently)	6	Propose to Close - Issue(s) Solved
Not Solved (Too Costly)
Duplicate	9	Propose to Close - Duplicated Ticket
Solved Remotely (Work Around)	6	Propose to Close - Issue(s) Solved
Closed/Resolved by Caller	6	Propose to Close - Issue(s) Solved
Resolved after 3 contact attempts	12	Propose to Close - No Reply from Customer
Solved Remotely (Permanently)	6	Propose to Close - Issue(s) Solved

ResolutionNote

Field	Description
ResolutionNote	- DataType: string

---

Update support ticket (inbound to ServiceNow)

Description	Value
Method	POST
Endpoint	ServiceNow REST API endpoint
Headers	Please specify if any

Payload

Subject to change base on payload required by Service Now

Sample JSON

{
  "u_number":"INC0053775",
  "u_comments":"Adding Comments"
}

{
  "u_number":"INC0053775",
  "u_state":"closed",
  "u_resolution_code":"Propose to Close - No Issue Found",
  "u_resolution_notes":"Testing Resolution"
}

Parameter description

Field	Description
TicketReferenceId	- DataType: string - Unique identifier of the ticket from FootfallCam
Status	- DataType: string - Status of the ticket

---

Ticket message

Add message into support ticket to FootfallCam (outbound from ServiceNow)

Description	Value
Endpoint	https://support.footfallcam.com/TicketChat/SendMessageExternal?tt=1
Method	POST
Headers	AToken - Refer to this guide on how to generate access token

Payload

{
    "TicketReferenceId": "3001-0123",
    "MessageDetails": "message for ticket",
    "AttachmentInBase64Format": "base 64 encode result",
    "AttachmentName": "testing.png",
    "TicketSource": 3,
    "PendingAction": 2,
    "GuestEmailAddress": "",
    "EmailAddress": ""
}

Parameter description

Field	Description
TicketReferenceId	- DataType: string - Unique identifier of the ticket from ServiceNow
MessageDetails	- DataType: string - Message for the ticket
AttachmentInBase64Format	- Optional, if there’s attachment of file to be included in the message
AttachmentName	- DataType: string - Optional, if there’s attachment of file to be included in the message (need to include the file type like .png)
TicketSource	- DataType: long - 3
PendingAction	- DataType: int - enum PendingAction   - pendingCustomerAction = 1   - pendingFootfallCamAction = 2
GuestEmailAddress	- DataType: string

---

Add message into support ticket to ServiceNow (inbound to ServiceNow)

Description	Value
Endpoint	ServiceNow REST API endpoint
Method	POST
Headers	Please specify if any

Payload

Form-data

{
    "u_number":"INC0000001",
    "u_attachment_data":"attachment_data in base64v format",
    "u_attachment_type":"attachment content",
    "u_attachment_name":"attachment name"
}

Parameter description

Field	Description
TicketReferenceId	- DataType: string - Unique identifier of the ticket from FootfallCam
MessageDetails	- DataType: string - Message for the ticket
Attachments	- DataType: file - Optional, if there’s attachment of file to be included in the message

---

Health check

Get company’s health check

Description	Value
Endpoint	https://v9.footfallcounter.com/HealthCheck?healthCheckType=device_online_status,site_in_out_discrepancy
Method	GET
Headers	AToken - Refer to this guide on how to generate access token

Parameter description

Field	Description
healthCheckType	- DataType: array of string - Indicate the health check type   - device_online_status: device connection status to the server for the past 1 hour   - site_in_out_discrepancy: site in and out visitor discrepancy for yesterday

Response sample

{
    "site_in_out_discrepancy": [
        {
            "SiteCode": "SiteCode123",
            "SiteName": "Site Name 123",
            "InOutDiscrepancy": true,
            "InOutDiscrepancyValue": 30
        },
        {
            "SiteCode": "SiteCode456",
            "SiteName": "Site Name 456",
            "InOutDiscrepancy": false,
            "InOutDiscrepancyValue": 0
        }
    ],
    "device_online_status": [
        {
            "Serial": "15F00001234",
            "IsOnline": false,
            "LastOnlineDateTime": "2022-01-01 00:00:00"
        },
        {
            "Serial": "15F00004567",
            "IsOnline": true,
            "LastOnlineDateTime": "2022-05-31 00:00:00"
        }
    ]
}