Partner Integration

Central offers two types of APIs: Polling APIs for querying specific information and Publish/Subscribe APIs for near real-time updates. The Polling API provides a current snapshot of the network environment. Thereafter, any real-time updates in the network are learned through Publish/Subscribe APIs. Publish/Subscribe APIs are recommended for location updates.

Polling or REST APIs

Among the many Polling APIs supported by Central are the Location, Presence, Geofence and Station REST APIs. These are some of the most commonly utilized APIs by analytics applications, and some of them are elaborated below.

Location API

The Location REST API can be used to access near real-time data around device location, status, and identity within a specific campus, building and its various floors. Customers can securely access the REST API using their credentials and an API key. They can make requests to specific endpoints on the API to retrieve data. For example, to retrieve the location of a specific client, the endpoint would be - /visualrf_api/v1/client_location/{macaddr}.

For more information on how to access the REST API using Central refer to the REST API developer docs.

The output for this message type displays the following information:

Example Response for Location REST API GET https://example.com/visualrf_api/v1/client_location/{macaddr}

{  
  "location": {  
    "x": "185.55978",  
    "y": "35.71597",  
    "units": "FEET",  
    "error_level": 61,  
    "campus_id":
"201610193176__1b99400c-f5bd-4a17-9a1c-87da89941381",  
    "building_id":
"201610193176__f2267635-d1b5-4e33-be9b-2bf7dbd6f885",  
    "floor_id":
"201610193176__39295d71-fac8-4837-8a91-c1798b51a2ad",  
    "associated": true,  
    "device_mac": "ac:37:43:a9:ec:10"  
  }  
}

Presence API

Retail customers can leverage the REST API data to create relevant applications by utilizing the various endpoints provided for Presence Analytics.

Visitor status

Endpoint: GET https://example.com/presence/v3/visitor_status

• Utilize this endpoint to retrieve the number of connected and non-connected visitors within a selected time range.

• If needed, filter data by passing the tag_id to retrieve information for a specific tag/site.

• Applications can display real-time visitor status, helping staff manage crowd control and understand store occupancy.

{  
  "data": {  
    "visitor_status": [  
      {  
        "count": 0,  
        "status": "Connected"  
      },  
      {  
        "count": 0,  
        "status": "Not Connected"  
      },  
      {  
        "total_visitors": 0  
      }  
    ]  
  }  
}

Visit frequency

Endpoint: GET https://example.com/presence/v3/visit_frequency

• Use this endpoint to get details for loyal visitors, including the number of visits made by a customer at a specific site or customer level.

• Applications can provide insights into customer loyalty, enabling targeted marketing campaigns or loyalty programs.

{  
  "result": [  
    {  
      "bucket": "2-10",  
      "count": 7  
    }  
  ],  
  "status": "success",  
  "unique_visitor_count": 0  
}

Analytics trends for loyal visitors

Endpoint: GET https://example.com/presence/v3/analytics/trends/loyal_visitors

• Retrieves discrete (samples) values for each time interval from start time to stop time, for presence indicators ( passerby, visitor, draw rate, dwell time) at a site or customer level based on input. The time interval depends on what timeframe is selected and if the sample value is aggregated value for that time interval. If 1 day is selected, the interval is 1 hour and the sample is aggregated value for each one hour.

• Applications can visualize trends in customer behavior, allowing retailers to optimize store layouts and offerings.

[  
  {  
    “allowed_frequency”: [  
      [  
        “hourly”,  
        “daily”,  
        “weekly”  
      ]  
    ],  
    “fields”: [  
      [  
        “time”,  
        “loyal_visitors”,  
        “unique_visitors”  
      ]  
    ],  
    “samples”: [  
      [  
        [  
          [  
            1590949800000,  
            0,  
            0  
          ],  
          [  
            1590953400000,  
            0,  
            0  
          ],  
          [  
            1590957000000,  
            0,  
            0  
          ],  
          [  
            1590962400000,  
            1,  
            1  
          ]  
        ]  
      ]  
    ]  
  }  
]

Analytics trends for passerby visitors

Endpoint: GET https://example.com/presence/v3/analytics/trends/passerby_visitors

• Similar to the endpoint for loyal visitors, retrieve discrete values for presence indicators for passerby visitors.
• Applications can analyze passerby trends to understand foot traffic and improve store marketing strategies.

{  
  "datapoints": [  
    {  
      "allowed_frequency": [  
        "hourly"  
      ],  
      "customer_id": "123456789",  
      "category": "visitor",  
      "xunits": "dwelltime",  
      "yunits": "visitor_count",  
      "data": {  
        "count": 35,  
        "sample": [  
          [  
            1591243200000,  
            2  
          ],  
          [  
            1591246800000,  
            2  
          ],  
          [  
            1591250400000,  
            4  
          ]  
        ]  
      }  
    }  
  ]  
}

Aggregate values for list of sites

Endpoint: GET https://example.com/presence/v3/insights/sites/aggregates

• Obtain aggregated/average values for various categories (passerby, visits, draw rate, dwell time, loyal visitors, visitors, connected visitors) at a site or customer level.

• Applications can present a comprehensive overview of key metrics, aiding in strategic decision-making for each site.

{  
  "category": "all",  
  "data": [  
    {  
      "drawrate_count": 76,  
      "dwelltime_count": 67,  
      "loyal_visitors": 45,  
      "new_visitors": 35,  
      "passerby_count": 35,  
      "site_id": 65,  
      "site_name": "c2cLab",  
      "store_id": 65,  
      "store_name": "c2cLab",  
      "total_connected": 55,  
      "visitor_count": 45,  
      "visits": 65  
    }  
  ],  
  "limit": 10,  
  "offset": 0,  
  "sort": "asc",  
  "total": 10  
}

Publish/Subscribe or streaming APIs

These are also called “Streaming APIs” and serve as the primary tool for subscribing to and receiving real-time updates from Central. They operate on the publish-subscribe model, ensuring that any message published on a specific topic is promptly distributed to all subscribers interested in that topic. These types of APIs find versatile applications in event-driven architecture and real-time monitoring.

Central adopts the Web Socket Secure (WSS) protocol for the Streaming API. In this setup, the publisher is represented by Central, functioning as the WebSocket Server, while the subscriber is the WebSocket client application designed and used by end-point applications.

Streaming APIs are categorized into different topics, some of the most popular ones being the Presence, Location and Geofence topics.

Presence topic

The Presence topic contains details of all associated and unassociated clients detected by Access Points. Event updates for each device are sent once every 60 seconds.

Below are descriptions of crucial parameters contained within the Presence topic that help enable some of the Presence Analytics use cases:

• Proximity—The pa_proximity_event reports which AP hears the client at the strongest RSSI, indicating which AP is closest to the client/station, and this event will be provided for each device once every 60 seconds.

• RSSI—The pa_rssi_event contains a list of RSSI information of all unassociated and associated clients/stations, detected by an AP device, and this event will be provided for each device once every 60 seconds.

The streaming API delivers data updates containing the following information for each client device:

Example of an event from the Presence topic:

sta_eth_mac {
addr: "B827EBD9CEB2"
}
radio_mac {
addr: "B45D5062FCF0"
}
rssi_val: -66
noise_floor: 92
associated: false
device_id: "CNCFJSS4WF"
ap_eth_mac {
addr: "B45D50CE2FCE"
}

Location topic

A location event is generated when the location of a client (station) is computed using RSSI values periodically reported by the Access Points. The event message includes the coordinates of the client on the Floorplan Manager and geofence notification, which contains information on when a device enters or leaves a geofence region (if Geofence is enabled). Therefore, updating a floor plan with AP location mapping is a prerequisite for the Location Streaming Events.

The output for this message type displays the following information:

Example of the location message:

 sta_location_x: 333.671569824
 sta_location_y: 220.563110352
 error_level: 92
 loc_algorithm: ALGORITHM_TRIANGULATION
 unit: FEET
 sta_eth_mac {
 addr: "320323340262p"
 }
 campus_id_string: "77d249ac35b548cab35fb48a8a1e7dd5__default"
 building_id_string: "77d249ac35b548cab35fb48a8a1e7dd5__1"
 floor_id_string:
 "77d249ac35b548cab35fb48a8a1e7dd5__ee80edb6-0476-4c9e-93a4-d79acd2c6f7a"
 target_type: TARGET_TYPE_STATION
 associated: false

Geofence notify

The Geofence Notify message returns information when a device enters or leaves a geofence region. Geofence Notify events are only available under the Location topic on Central.

The output for this message type displays the following information:

Decode data for customer location  
{'customer_id': '416bc832bc6111ed961e6aa14dbf31f1',  
'data': {'associated': False,  
          'dwell_time': 172,  
          'geofence_event': 'ZONE_OUT',  
          'geofence_id':
'NDE2YmM4MzJiYzYxMTFlZDk2MWU2YWExNGRiZjMxZjFfXzU2OTE2ZGUxLTg0MzgtNDNhYi04NTZhLTNkY2QwNDkwNTRjOQ==',  
          'geofence_name':
'416bc832bc6111ed961e6aa14dbf31f1__Zone-1',  
          'sta_eth_mac': {'addr': 'IEwDTSRj'}},  
'msp_ip': '',  
'timestamp': 1699915771139221492,  
'topic': 'location'}

Useful resources

• Overview of Foundation and Advanced Licenses

• REST API- Get Started with REST API for Configuration, on-demand polling, and monitoring data via HTTP Requests.

• Streaming API- Get Started with Streaming API to subscribe to selected topics, get statistics, and state changes over Secure WebSocket (WSS).

• Webhook - Get Started with Webhooks to integrate external applications and implement actions based on real-time alerts.