Pipispy API中文

Data usage rules: 1. Obtaining a data result consumes 1 data. Obtaining more detailed information about a data result does not consume data. 2. Ad Tracker: Each monitoring session costs $1/month. Each monitoring session is valid for one month and automatically expires after one month. Deleting a monitoring session does not restore the monitoring session, so please delete with caution. Monitoring sessions can be accessed at any time and are unlimited.

Create Monitor Task

This document explains how to create monitor tasks using advertiser accounts. There are four ways to create monitor tasks:

Method Parameter Description Example
1. Advertiser ID facebook_page_id_list Obtained via Advertiser Search API ["614178972053891"]
2. Advertiser URL facebook_page_url_list Enter Facebook advertiser page URL directly ["https://www.facebook.com/example"]
3. Public Page Number facebook_public_page_number_list Enter Facebook public page number ["123456789"]
4. Store/Website URL facebook_shop_url_list Enter store, website, or landing page URL ["https://example.com"]

Priority Note: If multiple parameters are submitted simultaneously, the system uses them in the following priority: facebook_page_id_list > facebook_page_url_list > facebook_public_page_number_list > facebook_shop_url_list


API Information

  • API Name: Advertiser Search
  • Request Method: POST
  • API URL: open-api/v1/monitor/data
  • Endpoint Path: /v3/api/ad-monitor-task/search-fb-ads-advertiser
  • Description: Search advertiser information by keyword and return a list of matching advertisers. Users can create monitor tasks using the returned facebook_page_id.
  • Usage Note: 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 Endpoint path "/v3/api/ad-monitor-task/search-fb-ads-advertiser" Yes
params object Request parameters object See parameter list Yes

Request Body Parameters (params object)

Parameter Type Required Description
name String Yes Advertiser name keyword

Request Example

curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/search-fb-ads-advertiser",
    "params": {
      "name": "example"
    }
  }'

Response Parameters

Response Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "facebook_page_id": "714739975064116",
        "name": "Example Advertiser",
        "avatar_url": "https://example.com/avatar.jpg",
        "category": "Digital creator",
        "country": null
      }
    ]
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}

Response Field Description

Field Name 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 Request success status
fail Boolean Request failure status

Response Data Fields

Field Name Type Description
data[].facebook_page_id string Advertiser ID, used to create monitor tasks
data[].name string Advertiser name
data[].avatar_url string Advertiser avatar
data[].category string Category
data[].country string Country

API 2: Create Monitor Task

API Information

  • API Name: Create Monitor Task
  • Request Method: POST
  • API URL: open-api/v1/monitor/data
  • Endpoint Path: /v3/api/ad-monitor-task/create-monitor-task
  • Description: Batch create monitor tasks for advertisers or stores/websites, supports four input methods, and returns the creation result for each task.
  • Usage Note: 1 credit will be deducted for each successfully created monitor task

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 Endpoint path "/v3/api/ad-monitor-task/create-monitor-task" Yes
params object Request parameters object See parameter list Yes

Request Body Parameters (params object)

Parameter Type Required Description
facebook_page_id_list array[string] No Advertiser ID list (can be obtained via Advertiser Search API)
facebook_page_url_list array[string] No Advertiser page URL list
facebook_public_page_number_list array[string] No Public page number list
facebook_shop_url_list array[string] No Store/website/landing page URL list

Important Notes:

  1. At least one of the four parameters above must be provided (cannot all be null or empty)
  2. Maximum 50 monitor objects can be added per request
  3. If multiple parameters are submitted simultaneously, the system uses them in priority order: facebook_page_id_list > facebook_page_url_list > facebook_public_page_number_list > facebook_shop_url_list

Request Examples

Method 1: Create via Advertiser ID (Recommended)

curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/create-monitor-task",
    "params": {
      "facebook_page_id_list": ["614178972053891", "714739975064116"]
    }
  }'

Method 2: Create via Advertiser URL

curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/create-monitor-task",
    "params": {
      "facebook_page_url_list": ["https://www.facebook.com/example"]
    }
  }'

Method 3: Create via Public Page Number

curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/create-monitor-task",
    "params": {
      "facebook_public_page_number_list": ["123456789"]
    }
  }'

Method 4: Create via Store/Website URL

curl -X POST "https://www.pipispy.com/open-api/v1/monitor/data" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here",
    "uri": "/v3/api/ad-monitor-task/create-monitor-task",
    "params": {
      "facebook_shop_url_list": ["https://example.com"]
    }
  }'

Response Parameters

Response Structure

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "task_id": "1005",
      "facebook_page_id": "614178972053891",
      "facebook_page_url": null,
      "facebook_public_page_number": null,
      "facebook_shop_url": null,
      "error_message": null
    }
  ],
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "fail": false,
  "success": true
}

Response Field Description

Field Name Type Description
code Integer Response status code, 200 means success
message String Response message
data Array Response data (task creation result list)
version String API version
timestamp String Response timestamp
sign String Response signature
success Boolean Request success status
fail Boolean Request failure status

Response Data Fields

Field Name Type Description
task_id string Monitor task ID
facebook_page_id string Advertiser ID
facebook_page_url string Advertiser URL
facebook_public_page_number string Public page number
facebook_shop_url string Store/website URL
error_message string Error message (if any)

Error Codes

Error Code Description
200 Success
400 Invalid request parameters
500 Internal server error