/v2/merchant/report/query

2023-04-28 21:00

POST /v2/merchant/report/query

With this API call, a merchant can query the performance data of a mini program from Mini Program Platform. The merchant then can download the data report to perform analysis, which helps the merchant to learn users' needs, make predictions, and develop business plans.

Note: Before calling this API, you must add the mini_program_report feature to your mini program in Mini Program Platform to access the API. For detailed instructions, refer to Add features.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field	Data type	Required	Description	Example
startDate	String	Yes	Indicates the start date of the data query. Note: The date should be in yyyyMMdd format. startDate should be earlier than or equal to endDate.	"20210901"
endDate	String	Yes	Indicates the end date of the data query. Note: The date should be in yyyyMMdd format. Maximum date range: 90 days	"20210908"
reportCode	String	Yes	Indicates the code to query data. The valid value is: `AIGENS_BK_PERFORMANCE` See More information for details.	"AIGENS_BK_PERFORMANCE"
appId	String	Yes	Indicates the unique ID assigned by Mini Program Platform to identify a mini program. Maximum length: 32 characters. Characters not allowed: special characters such as @ # ?	"P000000000000001xxxx"
customerBelongsTo	String	Yes	Indicates the super app that a user uses. Valid values are: `ALIPAY_CN`: Alipay CN `ALIPAY_HK`: Alipay HK `ALIPAY_MO`: Alipay MO `TNG`: Touch 'n Go `GCASH`: Gcash `DANA`: Dana `KAKAOPAY`: KakaoPay `BKASH`: bKash `CHOPE`: Chope `TRUEMONEY`: TrueMoney	"TNG"

Response parameters

Field

Data type

Required

Description

Example

result

Result

Yes

Indicates the request result such as status and error codes.

copy

{
    "resultCode": "SUCCESS",
    "resultMessage": "query report success",
    "resultStatus": "S"
}

dataList

Array

Yes

Indicates the specific data you queried.

Maximum size: 90 elements

Note: The data is returned in JSON format.

copy

[
    {
        "appId": "appId1",
        "report_dt": "20210901",
        "Daily_UV": 10,
        "Daily_PV": 20 
    }
]

More information

Report code

Description

Data list

Sample

AIGENS_BK_PERFORMANCE

Indicates querying data of Mini Program Performance.

Pass the AIGENS_BK_PERFORMANCE to obtain the data of the following metrics:

Appid: indicates the unique ID assigned by Mini Program Platform to identify a mini program.
Mini_App_Name: indicates the name of the mini program.

Country: indicates the country where a user is located.
report_dt: indicates dates within the selected date range: startDate-endDate.

Unique Visitor by User: indicates the number of users (counted by user ID) who visit the mini program on thereport_dt .
Unique Visitor by Device: indicates the number of users (counted by user's device ID) who visit the mini program on the report_dt .

Page View: indicates the number of visits to the mini program on thereport_dt.
New Users: indicates the number of new users who visit the mini program on thereport_dt.

7-Day Active Users: indicates the number of users who visit the mini program in the last 7 days from thereport_dt.
Accumulated Users: indicates the accumulated number of users who visit a mini program. This metric calculates data from the release date of the mini program to thereport_dt.

Page Visit Time : indicates the length of time that a user spends in the mini program on thereport_dt.

copy

{
    "appId": "2102010055290001",
    "startDate": "20211221",
    "endDate": "20211225",
    "reportCode": "AIGENS_BK_PERFORMANCE",
    "customerBelongsTo": "CHOPE"
}

Result process logic

In the response, the result.resultStatus field indicates the result of processing a request. The following table describes each result status:

Result status	Description
S	The query is successful. The corresponding result.resultCode is `SUCCESS` and the result.resultMessage is `Success`.
U	The status of the query is unknown. The corresponding result.resultCode is `UNKNOWN_EXCEPTION` and result.resultMessage is "An API calling is failed, which is caused by unknown reasons.". For details, see the Common error codes section.
F	The query is failed. The corresponding result.resultCode and result.resultMessage are various based on different situations. For details, see the following Error codes section.

Error codes

Error codes are usually classified into the following categories:

Common error codes are common across all mini programs' openAPIs.
API-specific error codes are listed in the following table:

Error code	Result status	Error message	Further action
REPORT_CODE_NOT_EXIST	F	The report code does not exist.	Use a valid report code such as `AIGENS_BK_PERFORMANCE`.
APP_ID_NOT_ALLOWED	F	The mini program has no permission to access the data.	Contact technical support to troubleshoot this issue.
INVALID_REPORT_CODE	F	The report code is invalid.	Use a valid report code such as `AIGENS_BK_PERFORMANCE`.
DATE_RANGE_EXCEEDS_LIMIT	F	The date range of the data query exceeds 90 days.	Reduce the date range of data query to 1-90 days and try again.
CLIENT_NOT_ALLOWED	F	The merchant has no permission to access this mini program.	Check if the app ID belongs to you.

Samples

The data flow for quering data is illustrated as below:

The merchant server calls this API to request to query the performance data of a mini program.
Mini Program Platform verifies whether the merchant has permission to access the mini program.
If the merchant has access permission, Mini Program Platform will query the corresponding data.
Mini Program Platform returns the data in JSON format.

Request

copy
{
    "appId": "2102010055290001",
    "startDate": "20211222",
    "endDate": "20211223",
    "reportCode": "AIGENS_BK_PERFORMANCE",
    "customerBelongsTo": "CHOPE"
}

Query the performance data of the mini program (2102010055290001) from 20211222 to 20211223.
The mini program (2102010055290001) is released to the super app CHOPE.

Response

copy
{
    "dataList": [
        {
            "7-Day Active Users": "5",
            "Accumulated Users": "0",
            "Appid": "2102010055290001",
            "Country": "Singapore",
            "Mini_App_Name": "testAppName",
            "New Users": "0",
            "Page View": "0",
            "Page Visit Time": "0",
            "Unique Visitor by Device": "2",
            "Unique Visitor by User": "2",
            "report_dt": "20211222"
        },
        {
            "7-Day Active Users": "1",
            "Accumulated Users": "0",
            "Appid": "2102010055290001",
            "Country": "Singapore",
            "Mini_App_Name": "testAppName",
            "New Users": "0",
            "Page View": "0",
            "Page Visit Time": "0",
            "Unique Visitor by Device": "0",
            "Unique Visitor by User": "0",
            "report_dt": "20211223"
        }
    ],
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "query report success",
        "resultStatus": "S"
    }
}

result.resultStatus is S, which shows the data query is successful.
The merchant gets the performance data of the mini program (2102010055290001) from 20211222 to 20211223. The metrics on these two days are the same, including New Users, Page View, Page Visit Time, Unique Visitor by Device, and Unique Visitor by User.