# Introduction

This API exposes analytical, aggregated, near-realtime data collected by Placewise systems.

## Reports

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

Report can return data in three different data formats:
* `records` - cursor-paginated API records
* `timeseries` - formatted in a way that is easily usable to build charts
* `statistics` - aggregated value over timeseries data

You can find reports specification in `Reports` folder.

## Rate limiting

Reporting API is rate limited by [generic Placewise API rate limits](https://docs.mpc.placewise.com/doc-344019).

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](https://docs.mpc.placewise.com/doc-343954)
* `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](https://docs.mpc.placewise.com/doc-342139) for more details.

## Timezones

Time from our Reporting API is returned in most of cases in UTC-based format.

You can distinguish that by looking at the returned timestamp. If it includes `Z` or `+<offset>` then this is UTC-based timestamp.

Examples:
```
"2024-04-30T00:00:00.000+02:00" - UTC-based time ("2024-04-29T22:00:00.000Z" UTC)
"2024-04-30T00:00:00.000Z" - UTC time
"2024-04-30T00:00:00.000" - local time for given customer
```

### Querying over timeseries data

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:
```json
{
    "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:
```json
{
    "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.