Introduction

Reporting API exposes analytical, aggregated, near-realtime data.

Reports

Available data is divided into various reports with filtering/aggregation options.

Report can return data in two different formats:

records - cursor-paginated API records

timeseries - formatted in a way that is easily usable to build charts

You can find reports specification in Reports folder.

Rate limiting

Reporting API is rate limited by generic Placewise API rate limits.

Reporting API uses different number of tokens based on selected report, aggregation and filter parameter.

Each report has specified number of tokens that will be used during the request

Filter parameter uses additional number of tokens. For details see Filter parameter specification

Metadata endpoint always cost 1 token in total

Endpoints

There are 3 endpoints:

Metadata - it returns basic information about report including fields that you can filter by, available aggregates and format of returned data

Field metadata - it allows to fetch more information about given field (for example it can be used to build dynamic filter selector with available values in given timeframes)

Query - it is the main endpoint which queries the data

Note that there are differences between those endpoints based on returned data format.

API Permits

In order to make queries, API client must have:

Reporting:Api:Query permit which grants general access to Reporting API

report specific permit

Additionally, when report depends on Customer's feature it needs to be enabled.

Customer context

Queries can be done in both single customer and cross-customer context. See X-Customer header specification for more details.

Timezones

Time from our API is returned in UTC in most of cases.

It's a bit different when it comes to timeseries data. In order to support cross-customer queries with correct comparisons and bucketing of data, we have decided to keep timeseries events in customer's timezone.

To understand how querying the timeseries report works with timezones, we need to separate two cases:

querying over customers which all have same timezone (including querying over single customer)

querying over customers with different timezones

Customers having same timezone

from and to request parameters are translated to the timezone.

Example query response:

{
    "interval": "1d",
    "range_timezone": "Europe/Oslo",
    "time_buckets": [
        "2024-04-30T00:00:00.000+02:00",
        "2024-05-01T00:00:00.000+02:00",
    ],
    "series": [
        { "label": {}, "values": [20, 10] }
    ],
    "result_type": "timeseries"
}

query response includes range_timezone parameter with computed timezone

time_buckets are returned as ISO8601 time as an offset from UTC

Customers having different timezones

from and to request parameters are assumed to be UTC time.

Example query response:

{
    "interval": "1d",
    "range_timezone": "local",
    "time_buckets": [
        "2024-04-30T00:00:00.000",
        "2024-05-01T00:00:00.000",
    ],
    "series": [
        { "timezone": "Europe/Oslo", "label": { "
loyalty_club_id": 10 }, "values": [20, 10] },
        { "timezone": "America/Denver", "label": { "loyalty_club_id": 11 }, "values": [10, 20] }
    ],
    "result_type": "timeseries"
}

query response includes range_timezone parameter with local value

time_buckets are returned as UTC time

series include additional parameter - timezone

Loyalty club with ID 10 has value 20 on 2024-04-30T00:00:00 - 2024-04-30T23:59:00 CEST time.
Loyalty club with ID 11 has value 10 on 2024-04-30T00:00:00 - 2024-04-30T23:59:00 MDT time.

Data lag/freshness

Unless stated otherwise, data is processed within analytical pipelines in near-realtime manner. Keep in mind that in some circumstances slight delays may happen.

Some of reports or aggregations may include data computed periodically (e.g. every 15 minutes), instead of strictly near-realtime, due to their complexity.

Reports#

Rate limiting#

Endpoints#

API Permits#

Customer context#

Timezones#

Customers having same timezone#

Customers having different timezones#

Data lag/freshness#