Pemberton Digital API Documentation (v1.0)

A list of available organisations and sites accessible by this client, in the format:

[
    {
        "organisation_code": "abc1e",
        "organisation_name": "Organisation 1",
        "site_slug": "site1",
        "site_name": "Site 1",
    },
    ...
]

Footfall entries time-series data.

[
    {"x": time_iso8601, "y": entries},
    ...
]

where

• time_iso8601 is the time of the bucket is ISO 8601 format. The timezone is always UTC.
• entries is the integer number of entries in that bucket.

Footfall entries calendar-week time-series data.

Returns exactly one week of footfall data (Monday-Sunday) for the most recently completed calendar week. If called on a Wednesday, returns data for the previous Monday-Sunday (approximately 9 days ago to 2 days ago).

[
    {"x": time_iso8601, "y": entries},
    ...
]

where

• time_iso8601 is the timestamp in ISO 8601 format (UTC timezone).
• entries is the footfall entry count for that bucket. If average > 1, this is the average across the previous average weeks.

The total entries to the site over the specified time range.

If precise_counts is false, the response is given as a list of 1 or 2 items based on the number of entries recorded at the site by all configured sensors. When two items are returned (when the entries to the site are non-zero), this specifies the minimum and maximum true values for entries based on the expected sensor error rate. For example, a response of

[25, 30]

indicates that the number of entries to the site is between 25 and 30.

Typical sensor error rates are +/- 2% in counting entries.

If zero entries were detected and precise_counts is false, the response is a single item list:

[0]

If precise_counts is true, the response is always a single item list with the number of entries recorded. No error estimate is given:

[27]

The percentage change in entries to the given site vs the previous period.

The response is a single float representing the percentage change in entries vs the period period recorded at the site by all configured sensors. For example, if a one-week period is requested, a response of

92.3076923076923

indicates that the number of entries to the site during the requested week has increased ~92.3% vs the previous week.

Occupancy time-series data.

[
    {"x": time_iso8601, "y": occupancy_count},
    ...
]

where

• time_iso8601 is the time of the bucket is ISO 8601 format. The timezone is always UTC.
• occupancy_count is the floating-point average number of people observed at the site during the bucket period.

Scaled and normalised occupancy time-series data.

[
    {"x": time_iso8601, "y": scaled_occupancy_count},
    ...
]

where

• time_iso8601 is the time of the bucket is ISO 8601 format. The timezone is always UTC.
• scaled_occupancy_count is a scaled floating-point value from 0-100 representing the number of people observed at the site during the bucket period, normalised to the 95th / 10th percentile observed occupancy over the trailing 5 periods.

Zone-based occupancy time-series data.

{
    "zone_name": {
        "colour": "#ff0000",
        "data": [
            {"x": time_iso8601, "y": occupancy},
            ...
        ]
    },
    ...
}

where

• zone_name is the name of the zone.
• colour is the hex colour code for visualization of the zone.
• time_iso8601 is the time of the bucket in ISO 8601 format. The timezone is always UTC.
• occupancy is the average number of people detected in the zone during that bucket.

Zone-based path statistics.

{
    "zone_name": {
        "colour": "#ff0000",
        "total_unique_paths": 100,
        "total_path_points": 1000
    },
    ...
}

where

• zone_name is the name of the zone.
• colour is the hex colour code for visualization of the zone.
• total_unique_paths is the total number of unique paths that entered the zone (used for calculating impressions).
• total_path_points is the total number of path points within the zone (used for calculating average dwell time).

Queue length time-series data.

[
    {"x": time_iso8601, "y": queue_length},
    ...
]

where

• time_iso8601 is the time of the bucket in ISO 8601 format. The timezone is always UTC.
• queue_length is the integer sum of average occupancy across all devices with QUEUE capability at the site.

Queue time time-series data.

[
    {"x": time_iso8601, "y": queue_time_minutes},
    ...
]

where

• time_iso8601 is the time of the bucket in ISO 8601 format. The timezone is always UTC.
• queue_time_minutes is the average time spent in the queue in minutes, calculated as queue length divided by exits per minute.

Note: Buckets with fewer than 0.25 exits per minute are excluded as the calculation becomes inaccurate at low throughput.

Wait time time-series data.

[
    {"x": time_iso8601, "y": wait_time_minutes},
    ...
]

where

• time_iso8601 is the time of the bucket in ISO 8601 format. The timezone is always UTC.
• wait_time_minutes is the average wait time in minutes, or null if insufficient data.

Note: Wait time is calculated from occupancy and footfall data. Buckets with fewer than 6 entries or fewer than 3 occupancy are excluded.

Site-wide heatmap data.

{
    "scaling": 1.234,
    "offset": -0.567,
    "data": [0.0, 5.2, 12.4, 8.3, ...]
}

where

• scaling is the scaling factor applied to normalize values to 0-100 range.
• offset is the offset applied before scaling.
• data is a flat array of heatmap values in row-major order for the requested grid dimensions (grid_x × grid_y).

Values represent averaged movement/dwell intensity across all devices at the site, projected onto a common floorplan grid. Each device's heatmap is transformed to floorplan coordinates and weighted by distance for smooth aggregation.

Zone-based dwell totals.

{
    "zone_name": 1234.5,
    ...
}

where each key is a zone name and the value is the total dwell intensity summed across all heatmap grid cells within that zone's boundary.

Site-wide path data transformed to floorplan coordinates.

Returns a list of paths from all devices at the site, where each path is a list of coordinate pairs in floorplan pixel coordinates:

[
    [[x1, y1], [x2, y2], [x3, y3], ...],
    [[x1, y1], [x2, y2], ...],
    ...
]

where coordinates are transformed from device-local coordinates to floorplan coordinates, accounting for device position, rotation, and bounding box configuration.

Seat occupancy data bucketed by time intervals.

[
    {
        "bucket_start": unix_timestamp,
        "bucket_end": unix_timestamp,
        "seats": {
            "seat_label": {
                "avg_occupancy": 0.85,
                "data_points": 5,
                "total_occupancy_minutes": 4.25,
                "seat_type": "desk",
                "max_occupancy": 1
            },
            ...
        },
        "seat_groups": {
            "group_label": {
                "occupancy_percent": 75.0,
                "group_type": "booth",
                "occupied_count": 3,
                "total_count": 4,
                "avg_occupancy": 2.8
            },
            ...
        }
    },
    ...
]

where

• bucket_start and bucket_end are unix timestamps in Europe/London timezone.
• avg_occupancy is the average occupancy (0-1 for single occupancy, up to max_occupancy for shared seats).
• data_points is the number of 1-minute rollup records in this bucket.
• total_occupancy_minutes is the sum of occupancy across all minutes in the bucket.
• seat_type is the type of seat (e.g., "desk", "meeting_room").
• max_occupancy is the maximum number of people that can occupy this seat.
• seat_groups contains occupancy statistics for each seat group (booth, table, etc.).
• occupancy_percent is the percentage of seats within the group that have occupancy (e.g., 75% means 3 out of 4 seats occupied).
• occupied_count is the number of seats in the group with any occupancy.
• total_count is the total number of seats in the group.
• avg_occupancy is the average total number of people sitting across all seats in the group (sum of avg occupancy for each seat).

Total seat occupancy time-series data.

[
    {"x": time_iso8601, "y": total_occupied_seats},
    ...
]

where

• time_iso8601 is the time of the bucket in ISO 8601 format (Europe/London timezone).
• total_occupied_seats is the count of unique seats that were occupied for at least min_occupied_minutes during that bucket.
• If count_groups_as_single=true, all seats in a group are counted as occupied if any seat in the group is occupied (useful for restaurant booth capacity).

Total seat occupancy time-series data grouped by seat type.

{
    "seat_type_name": [
        {"x": time_iso8601, "y": total_occupied_seats},
        ...
    ],
    ...
}

where

• seat_type_name is the name of the seat type (e.g., "desk", "meeting_room"). Seats with no type are grouped under the key "none".
• time_iso8601 is the time of the bucket in ISO 8601 format (Europe/London timezone).
• total_occupied_seats is the count of unique seats of that type that were occupied for at least min_occupied_minutes during that bucket.
• If count_groups_as_single=true, all seats in a group are counted as occupied if any seat in the group is occupied (useful for restaurant booth capacity).

Seat occupancy percentage time-series data.

[
    {"x": time_iso8601, "y": occupancy_percent},
    ...
]

where

• time_iso8601 is the time of the bucket in ISO 8601 format (Europe/London timezone).
• occupancy_percent is the percentage of seats occupied (0-100), calculated as the average of 1-minute occupied seat counts divided by total available seats in each bucket.
• If count_groups_as_single=true, all seats in a group are counted as occupied if any seat in the group is occupied (useful for restaurant booth capacity).

Average stay length time-series data.

[
    {"x": time_iso8601, "y": avg_stay_minutes},
    ...
]

where

• time_iso8601 is the time of the bucket in ISO 8601 format (Europe/London timezone).
• avg_stay_minutes is the average length of occupancy spans (in minutes) that cross or end in this bucket.

Average group size time-series data.

[
    {
        "x": time_iso8601,
        "total_groups": 12,
        "min_group_size": 1,
        "max_group_size": 4,
        "avg_group_size": 2.3,
        "median_group_size": 2
    },
    ...
]

where

• time_iso8601 is the time of the bucket in ISO 8601 format (Europe/London timezone).
• total_groups is the total number of distinct groups (occupied seats not in groups count as size-1 groups).
• min_group_size is the minimum group size in this bucket.
• max_group_size is the maximum group size in this bucket.
• avg_group_size is the average group size in this bucket.
• median_group_size is the median group size in this bucket.

For each occupied seat:

• If the seat is not in a SeatGroup, it counts as a group of size 1
• If the seat is in a SeatGroup, the group size is the number of occupied seats in that group at that moment

Site metrics summary containing footfall and seat occupancy data.

{
    "site": "liverpool-street",
    "total_footfall": 1234,
    "footfall_percent_change": 12.5,
    "seat_metrics": {
        "max_seats": 45,
        "avg_occupancy_percent": 45.2,
        "avg_occupancy_percent_change": 5.1
    },
    "period": {
        "since": "2025-10-01T00:00:00+00:00",
        "until": "2025-10-31T23:59:59+00:00",
        "days": 31
    }
}

• seat_metrics is null if the site has no configured seats
• footfall_percent_change is null if no data exists for the previous period
• avg_occupancy_percent_change is null if insufficient data for comparison

Pre-calculated average footfall by weekday for a historical period.

{
    "weekday_averages": {
        "monday": 142.5,
        "tuesday": 138.2,
        "wednesday": 156.8,
        "thursday": 149.3,
        "friday": 187.4,
        "saturday": 203.1,
        "sunday": 98.7
    },
    "period": {
        "weeks_analysed": 8,
        "start_date": "2025-08-05",
        "end_date": "2025-09-29"
    },
    "sample_counts": {
        "monday": 8,
        "tuesday": 8,
        "wednesday": 8,
        "thursday": 8,
        "friday": 8,
        "saturday": 8,
        "sunday": 7
    }
}

• weekday_averages maps lowercase weekday names to average daily footfall
• sample_counts shows how many days of each type were included (useful for identifying incomplete data)

Footfall entries time-series data.

[
    {"x": time_iso8601, "y": entries},
    ...
]

where

• time_iso8601 is the time of the bucket is ISO 8601 format. The timezone is always UTC.
• entries is the integer number of entries in that bucket.

Footfall entries calendar-week time-series data.

Returns exactly one week of footfall data (Monday-Sunday) for the most recently completed calendar week. If called on a Wednesday, returns data for the previous Monday-Sunday (approximately 9 days ago to 2 days ago).

[
    {"x": time_iso8601, "y": entries},
    ...
]

where

• time_iso8601 is the timestamp in ISO 8601 format (UTC timezone).
• entries is the footfall entry count for that bucket. If average > 1, this is the average across the previous average weeks.

The total entries to the site over the specified time range.

If precise_counts is false, the response is given as a list of 1 or 2 items based on the number of entries recorded at the site by all configured sensors. When two items are returned (when the entries to the site are non-zero), this specifies the minimum and maximum true values for entries based on the expected sensor error rate. For example, a response of

[25, 30]

indicates that the number of entries to the site is between 25 and 30.

Typical sensor error rates are +/- 2% in counting entries.

If zero entries were detected and precise_counts is false, the response is a single item list:

[0]

If precise_counts is true, the response is always a single item list with the number of entries recorded. No error estimate is given:

[27]

The percentage change in entries to the given site vs the previous period.

The response is a single float representing the percentage change in entries vs the period period recorded at the site by all configured sensors. For example, if a one-week period is requested, a response of

92.3076923076923

indicates that the number of entries to the site during the requested week has increased ~92.3% vs the previous week.

Footfall entries time-series data.

[
    {"x": time_iso8601, "y": entries},
    ...
]

where

• time_iso8601 is the time of the bucket is ISO 8601 format. The timezone is always UTC.
• entries is the integer number of entries in that bucket.