# Store Ad Meta Ads Library Delivery Trend Analysis API

## API Information

- **API Name**: Store Ad Meta Ads Library Delivery Trend Analysis API
- **Request Method**: POST
- **API Endpoint**: `/open-api/v1/data`
- **API Path**: `/v3/api/open/ppspy/pp-stores/analysis/ad-trend`
- **API Description**: Retrieve ad delivery trend data for a specified store in the Meta Ads Library, including historical trends of active ad count, total ad count, and new ad count
- **Pricing**: `Free`

**Request Headers:**

- Content-Type: application/json
- Accept: application/json

## Request Parameters

### Request Structure

| Parameter | Type   | Description                        | Example                                              | Required | Default |
| --------- | ------ | ---------------------------------- | ---------------------------------------------------- | -------- | ------- |
| key       | string | User's external API request key    | "your_api_key_here"                                  | Yes      |         |
| uri       | string | API path                           | "/v3/api/open/ppspy/pp-stores/analysis/ad-trend"     | Yes      |         |
| params    | object | API input parameter object         | See parameter list                                   | Yes      |         |

### Request Body Parameters (params object)

| Parameter  | Type   | Required | Description                                                                                                                                  |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| id         | String | Yes      | Store unique identifier ID, a 13-character string (e.g., `c2d5b2547218a`), corresponds to the `store_id` field in the store ranking list API response |
| start_time | Long   | Yes      | Query start time, Unix timestamp (seconds). Used to specify the start date for statistics                                                    |
| end_time   | Long   | Yes      | Query end time, Unix timestamp (seconds). Used to specify the end date for statistics. Recommended time range should not exceed 90 days for optimal performance |

### Request Example

```bash
curl -X POST "https://www.pipispy.com/open-api/v1/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/open/ppspy/pp-stores/analysis/ad-trend",
    "params": {
        "id": "c2d5b2547218a",
        "start_time": 1700000000,
        "end_time": 1707776000
    }
  }'
```

## Response Parameters

### Response Body Structure

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "active_ad_count_history": [],
    "ad_count_history": [],
    "ad_started_history": [],
    "is_logged_in": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

### Response Field Description

| Field     | Type    | Description                              |
| --------- | ------- | ---------------------------------------- |
| code      | Integer | Response status code, 200 means success  |
| message   | String  | Response message                         |
| data      | Object  | Response data                            |
| version   | String  | API version                              |
| timestamp | String  | Response timestamp                       |
| sign      | String  | Response signature                       |
| remaining_credits | Long    | Current remaining available credits after this request |
| consumed_credits  | Long    | Credits consumed by this request                       |
| success   | Boolean | Whether the request was successful       |
| fail      | Boolean | Whether the request failed               |

### Ad Trend Analysis Data Fields (data.data)

| Field                    | Type    | Description                                                                                                                         |
| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| active_ad_count_history  | Array   | Historical data of active ad count, records the number of ads actively running each day. Active ads are ads still in delivery status on that day |
| ad_count_history         | Array   | Historical data of total ad count, records the cumulative total number of ads each day. This is a cumulative value including all historical ads (active + stopped) |
| ad_started_history       | Array   | Historical data of new ad count, records the number of ads that started running each day. Indicates new ads that went live on that day |
| is_logged_in             | Boolean | Whether the user is logged in, used to identify data permission status                                                              |

### Historical Data Item Fields (HistoryItem)

Each element in the active_ad_count_history, ad_count_history, and ad_started_history arrays contains the following fields:

| Field | Type   | Description                                                                                                              |
| ----- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| date  | String | Statistical date, format is yyyy-MM-dd (e.g., 2024-01-15)                                                                |
| count | Long   | Count value for that date. Depending on the array, it represents: active ad count, total ad count, or new ad count      |

## Response Example

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "active_ad_count_history": [
      {
        "date": "2024-01-01",
        "count": 125
      },
      {
        "date": "2024-01-02",
        "count": 138
      },
      {
        "date": "2024-01-03",
        "count": 145
      }
    ],
    "ad_count_history": [
      {
        "date": "2024-01-01",
        "count": 1500
      },
      {
        "date": "2024-01-02",
        "count": 1523
      },
      {
        "date": "2024-01-03",
        "count": 1548
      }
    ],
    "ad_started_history": [
      {
        "date": "2024-01-01",
        "count": 15
      },
      {
        "date": "2024-01-02",
        "count": 23
      },
      {
        "date": "2024-01-03",
        "count": 25
      }
    ],
    "is_logged_in": false
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

## Error Code Description

| Error Code | Description               |
| ---------- | ------------------------- |
| 200        | Success                   |
| 400        | Invalid request parameters|
| 401        | Unauthorized              |
| 403        | Insufficient permissions  |
| 500        | Internal server error     |