# Matrix API

## 获取 Matrix 结果

<mark style="color:blue;">`GET`</mark> `https://penguin-stats.io/PenguinStats/api/v2/result/matrix`

此 Endpoint 允许您获取 Matrix 结果。

#### Query Parameters

| Name                | Type    | Description                                                  |
| ------------------- | ------- | ------------------------------------------------------------ |
| server              | string  | 说明欲请求的服务器代码。目前我们支持 4 个服务器："CN", "US", "JP" 和 "KR"。默认值为 "CN"。 |
| show\_closed\_zones | boolean | 是否显示已经关闭的 Zone 与 Stage。 默认值为 false。                          |
| is\_personal        | boolean | 使用全平台数据或个人数据。若提供了 true，请确保 Cookie 中有对应的 userID。 默认值为 false。  |

{% tabs %}
{% tab title="200 Get result matrix successfully." %}

```javascript
{
  "matrix":[
    {
      "stageId":"main_01-07",
      "itemId":"30012",
      "quantity":164303,
      "times":131916,
      "start":1556676000000,
      "end":1589529600000
    },
    {
      "stageId":"main_01-07",
      "itemId":"30031",
      "quantity":7822,
      "times":131916,
      "start":1556676000000,
      "end":1589529600000
    },
    {
      "stageId":"sub_03-1-2",
      "itemId":"30032",
      "quantity":3162,
      "times":2079,
      "start":1556676000000,
      "end":1589529600000
    },
    {
      "stageId":"sub_03-1-2",
      "itemId":"randomMaterial_2",
      "quantity":20,
      "times":68,
      "start":1581105600000,
      "end":1582315200000
    }
  ]
}
```

{% endtab %}

{% tab title="500 Exceptions happen during the query." %}

```
```

{% endtab %}
{% endtabs %}

## 什么是 Drop Matrix?

Suppose there is a matrix using stageId as row and itemId as column. Each element in the matrix represents the statistical data for that item in the stage. We will have a huge sparse matrix for all the items and stages, and for each server.

## Drop Matrix 构成元素说明

### Model

```javascript
{
  stageId: string,
  itemId: string,
  quantity: number,
  times: number,
  start: number,
  end: number
}
```

### Properties

`stageId` and `itemId` are internal ids of stages and items. They can be found in [this repository](https://github.com/Kengxxiao/ArknightsGameData).

`start` is the left end (inclusive) of the interval. Time unit is millisecond.

`end` is the right end (exclusive) of the interval. Time unit is millisecond.

`quantity` means the number of dropped items during the interval.

`times` means the number of times this stage was played during the interval. **The value may be 0**, so please be careful when calculating the drop rate.

### Interval

Not all submitted drop samples will be used in the calculation of this matrix. As you can see above, each matrix element has its own interval. We design a special mechanism to decide what each interval should be.

Let's take stage `main_01-07` as an example. We have four time ranges A to D:

| Time Range | Meaning                                             | start         | end           |
| ---------- | --------------------------------------------------- | ------------- | ------------- |
| A          | Arknights CN released \~ Chapter 6 released         | 1556676000000 | 1577174400000 |
| B          | Chapter 6 released \~ 应急理智小样 event ended            | 1577174400000 | 1578340800000 |
| C          | 应急理智小样 event ended \~ 1st anniversary event started | 1578340800000 | 1589529600000 |
| D          | 1st anniversary event                               | 1589529600000 | 1590696000000 |

Consider the following two items:

* `30012`: Chinese name is "固源岩". It shows up in the drop list of `main_01-07` across all time ranges from A to D.
* `ap_supply_lt_010`: Chinese name is "应急理智小样". It only shows up in the drop list of `main_01-07` during time range B and D.

The calculation is assuming that the drop of `ap_supply_lt_010` is independent from other items in `main_01-07`. The `quantity` and `times` of `30012` can be summed up across time range A to D. So the summation interval of `30012` will be A to D, which means `[1556676000000, 1590696000000)`. Here we say all ranges for `30012` in `main_01-07`is **accumulatable**. (Maybe we should use the term "accumulable", however in the code and database we are using the former one, so we want to keep it as it is.)

For `ap_supply_lt_010`, we are not sure if the drop rate in time range D is different from  the one in B. Thus, we think that samples from B and D should not be summed up together.  We would like to say `ap_supply_lt_010` in `main_01-07` is non-accumulatable during time range B and D. Our matrix API is designed to reveal the latest drop rates, so the interval of `ap_supply_lt_010` in `main_01-07` in the matrix will be `[1589529600000, 1590696000000)`.

Although the data of `ap_supply_lt_010` in `main_01-07` is not showing in the matrix result, you can still use Advanced Query to get them.

The interval may be varies for different items in one stage. That is why we show it using `start` and `end` in the drop matrix element.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.penguin-stats.io/public-api/zh/api-v2-instruction/matrix-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.