1. Get Specify All Adsources Under Segment Group
Note: Retrieving adsources under segment currently running A/B Test is not supported. Attempting to do so will result in the error: {“errors”:“code: 4602, msg: the mediation connection not found”}. If required, please use API6 instead.
1.1 Request URL
https://api.toponad.net/v3/waterfall/:mediation_group_id/segment_id/:segment_id/units
1.2 Request method
GET
1.3 Request params
| params | type | required | notes |
|---|---|---|---|
| ecpm_currency | String | N | eCPM currency unit, default USD when not transmitting, optional CNY |
1.4 Return data
| fields | type | required | notes |
|---|---|---|---|
| offer_list_switch | Int | Y | |
| ecpm_currency | String | Y | eCPM currency unit, corresponding to the parameter ecpm_currency when requesting, Returns the ecpm and auto_ecpm prices in the ad_source_list parameter based on the corresponding unit value of this field |
| parallel_request_number | Int | Y | Parallel request number |
| offer_list | Array[Object] | Y | My offer list in used |
| offer_list.offer_id | String | Y | Offer id |
| offer_list.offer_name | String | Y | Offer name |
| ad_source_list | Array[Object] | Y | Adsources list in used |
| ad_source_list.ad_source_id | Int | Y | Adsource ID |
| ad_source_list.name | String | Y | Adsource name |
| ad_source_list.header_bidding_switch | Int | Y | If support Header Bidding, The unit was identified when it was created 1: not support, 2: support |
| ad_source_list.ecpm | String | Y | eCPM |
| ad_source_list.auto_ecpm_switch | Int | Y | Automatically optimize the ECPM 1: not open auto eCPM sort switch, 2: open auto eCPM sort switch |
| ad_source_list.auto_ecpm | String | Y | Auto eCPM |
| ad_source_list.hour_cap | Int | Y | -1 : close |
| ad_source_list.day_cap | Int | Y | -1 : close |
| ad_source_list.pacing | Int | Y | -1 : close |
| free_ad_source_list | Array[Object] | Y | Adsource list not in used |
| free_ad_source_list.ad_source_id | Int | Y | Adsource ID |
| free_ad_source_list.name | String | Y | Adsource name |
| free_ad_source_list.header_bidding_switch | Int | Y | If support Header Bidding, The unit was identified when it was created 1: Not support 2: Support |
| free_ad_source_list.ecpm | String | Y | eCPM |
| free_ad_source_list.auto_ecpm_switch | Int | Y | Automatically optimize the ECPM 1: not open auto eCPM sort switch, 2: open auto eCPM sort switch |
| free_ad_source_list.auto_ecpm | String | Y | Auto eCPM |
1.5 Sample
Request address sample:
https://api.toponad.net/v3/waterfall/116112/segment_id/600262/units
Sample request parameter:
{
"ecpm_currency" : "USD"
}
Return sample:
{
"offer_list_switch": 2,
"ecpm_currency": "USD",
"parallel_request_number": 2,
"offer_list": [],
"ad_source_list": [
{
"ad_source_id": 681853,
"name": "Chartboost_int_2",
"header_bidding_switch": 1,
"ecpm": "66",
"auto_ecpm_switch": 1,
"auto_ecpm": "0",
"hour_cap": -1,
"day_cap": -1,
"pacing": -1
},
{
"ad_source_id": 681852,
"name": "Sigmob_int_2",
"header_bidding_switch": 1,
"ecpm": "20",
"auto_ecpm_switch": 1,
"auto_ecpm": "0",
"hour_cap": 4,
"day_cap": 5,
"pacing": 6
}
],
"free_ad_source_list": [
{
"ad_source_id": 681851,
"name": "Kuaishou Ads_int_2",
"header_bidding_switch": 1,
"ecpm": "50",
"auto_ecpm_switch": 1,
"auto_ecpm": "0"
},
{
"ad_source_id": 681850,
"name": "Mintegral_int_1",
"header_bidding_switch": 1,
"ecpm": "100",
"auto_ecpm_switch": 1,
"auto_ecpm": "0"
},
{
"ad_source_id": 681854,
"name": "Facebook_int_2",
"header_bidding_switch": 1,
"ecpm": "22",
"auto_ecpm_switch": 1,
"auto_ecpm": "0"
}
]
}
2. Set Waterfall's Adsources(Expired, Please use API 5)
2.1 Request URL
https://api.toponad.net/v3/waterfall/:mediation_group_id/segment_id/:segment_id/units
2.2 Request method
PUT
2.3 Request params
| params | type | required | notes |
|---|---|---|---|
| parallel_request_number | Int | Y | Parallel request number |
| offer_switch | Int | N | Offer switch |
| ad_source_list | Array[Object] | Y | Adsources need to binding |
| ad_source_list.ad_source_id | Int | Y | Adsource ID |
| ad_source_list.header_bidding_switch | Int | N | If support Header Bidding, The unit was identified when it was created 1: not support, 2: support |
| ad_source_list.ecpm | String | Y | eCPM |
| ad_source_list.auto_ecpm_switch | Int | Y | 1: not open auto eCPM sort switch 2: open auto eCPM sort switch |
| ad_source_list.hour_cap | Int | N | Do not pass or pass -1 means unlimited |
| ad_source_list.day_cap | Int | N | Do not pass or pass -1 means unlimited |
| ad_source_list.pacing | Int | N | Do not pass or pass -1 means unlimited |
| unbind_ad_source_list | Array[Int] | N | Unbind the adsource and send only the adsource id |
| ecpm_currency | String | N | eCPM currency unit, corresponding to the parameter ecpm_currency when requesting, Returns the ecpm and auto_ecpm prices in the ad_source_list parameter based on the corresponding unit value of this field |
2.4 Return data
| fields | type | required | notes |
|---|---|---|---|
| mediation_group_id | Int | Y | Mediation Group ID |
| segment_id | Int | Y | Segment ID |
2.5 Sample
Request address sample:
https://api.toponad.net/v3/waterfall/116112/segment_id/600262/units
Sample request parameter:
{
"parallel_request_number" : 1,
"offer_switch" : 1,
"ad_source_list": [
{
"ad_source_id": 681853,
"name": "Chartboost_int_2",
"header_bidding_switch": 1,
"ecpm": "66",
"auto_ecpm_switch": 1,
"auto_ecpm": "0",
"hour_cap": -1,
"day_cap": -1,
"pacing": -1
},
{
"ad_source_id": 681852,
"name": "Sigmob_int_2",
"header_bidding_switch": 1,
"ecpm": "20",
"auto_ecpm_switch": 1,
"auto_ecpm": "0",
"hour_cap": 4,
"day_cap": 5,
"pacing": 6
}
],
"unbind_adsource_list" : [
681851,
681850,
681854
]
}
Return sample:
{
"mediation_group_id": 116112,
"segment_id": 600262
}
3. Batch enable/disable Waterfall's Adsources
3.1 Request URL
https://api.toponad.net/v3/waterfall/units/status
3.2 Request method
GET
3.3 Request params
| params | type | required | notes |
|---|---|---|---|
| placement_id | String | Y | Placement ID |
| mediation_group_id | Int | Y | Mediation Group ID |
| segment_id | Int | Y | Segment ID, where 0 represents the default group |
| abtest_group_item_id | Int | N | Segment A/B Test Group ID: When no A/B Testis conducted for the segment, pass in 0 or leave it empty. |
| ad_source_ids | Array[Int] | Y | Adsources ID List |
| status | Int | Y | Operation Status, Note: When enabling or disabling an operation, the Adsource ID passed must be bound to a segment_id (i.e., only enabled or disabled for bound adources). Enumeration description: 1: Disable 3: Enable 11: Unbind |
3.4 Return data
| fields | type | required | notes |
|---|---|---|---|
| items | Array[Object] | Y | List of invalid adsource information. Note: 1. If the list is empty, the operation was successful. 2. If the list is not empty, it indicates which adsource failed validation. All adsources (including those that passed validation) failed the operation. |
| items.id | Int | Y | Adsource ID |
| items.err_code | Int | Y | Error Code |
| items.err_msg | String | Y | Error messages, partial descriptions as follows: 1. “The unit is not yet bound to the segment”: When enabling or disabling operations, parameters contain unbound adsources. |
3.5 Sample
Request address sample:
https://api.toponad.net/v3/waterfall/units/status
Sample request parameter:
{
"placement_id" : "34343943uucce33",
"mediation_group_id" : 100000,
"segment_id" : 100000,
"abtest_group_item_id": 0,
"ad_source_ids": [232,435],
"status": 1
}
Return sample:
{
"items": [
{
"id": 232,
"err_code": 4000
"err_msg": "the unit not found"
}
]
}
4. Retrieve all Waterfall properties from the Adsources
Note: Segment currently running A/B Test. A single segment_id may correspond to multiple entries (associated with different test groups abtest_group_item_id).
4.1 Request URL
https://api.toponad.net/v3/waterfall/units
4.2 Request method
GET
4.3 Request params
| params | type | required | notes |
|---|---|---|---|
| ids | Array[Int] | Y | Adsource ID List: Maximum quantity limit is 100, minimum quantity limit is 1. |
| currency | String | Y | The currency units corresponding to ecpm, bid_floor, etc., can be set to USD or CNY. |
4.4 Return data
| fields | type | required | notes |
|---|---|---|---|
| id | Int | Y | Adsource ID |
| items | Array[Object] | Y | List of all Waterfall information for adsource |
| items.mediation_group_id | Int | Y | Mediation Group ID |
| items.segment_id | Int | Y | Segment ID |
| items.abtest_group_item_id | Int | Y | Segment A/B Test Group ID, where 0 indicates the current segment is not undergoing experimentation. |
| items.ecpm | Double | Y | eCPM price, currency unit specified by the request parameter currency |
| items.ecpm_rank | Int | Y | Adsource display priority at the same price, value range: [1,99], where a higher value indicates higher priority. |
| items.auto_ecpm_switch | Int | Y | Enable automatic eCPM optimization 1: Disable 2: Enable |
| items.auto_ecpm | Double | Y | Enable automatic eCPM optimization Automatic eCPM, where 0 indicates disabled |
| items.show_delay | Int | Y | Delay show time, in milliseconds, range [5000]. Note: Only available for certain ad formats, such as interstitial ads. For non-interstitial ads or when not applicable, pass 0. |
| items.show_delay_rate | Int | Y | Delayed show probability, range [1,100]. Note: Only available for certain formats, such as interstitial ads. For non-interstitial or non-display formats, pass 0. |
| items.bid_floor | Double | Y | Bid Floor Price, currency unit specified by the request parameter ‘currency’. For non-bidding or no interest, pass 0. |
| items.setup_sw | Int | Y | Adsource enabled for this segment. Enumeration description: 1: Yes 2: No |
| items.cap_hour | Int | Y | Maximum show limit per hour. -1 indicates no restriction. Note: This attribute is only available for enabled adsource. Pass -1 when disabled. |
| items.cap_day | Int | Y | Maximum show limit per day. -1 indicates no restriction. Note: This attribute is only available for enabled adsource. Pass -1 when disabled. |
| items.pacing | Int | Y | Show interval, -1 indicates no restriction. Note: This property is only available for enabled adsource. Pass -1 when disabled. |
4.5 Sample
Request address sample:
https://api.toponad.net/v3/waterfall/units?ids=417018,2280206¤cy=CNY
Sample request parameter:
curl --location --request GET 'https://api.toponad.net/v3/waterfall/units?ids=417018,2280206¤cy=CNY' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0===b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626056011000' \
--header 'Content-Type: application/json' \
--data-raw ''
Return sample:
[
{
"id": 2280206,
"items": [
{
"mediation_group_id": 273234,
"segment_id": 0,
"abtest_group_item_id": 0,
"ecpm": 2,
"ecpm_rank": 1,
"remark": "",
"setup_sw": 1,
"auto_ecpm_switch": 1,
"auto_ecpm": 0,
"cap_hour": -1,
"cap_day": -1,
"pacing": -1,
"show_delay": 0,
"show_delay_rate": 100,
"bid_floor": 0
}
]
}
]
5. Edit (Bind + Enable) All Waterfall Properties for Adsources
5.1 Request URL
https://api.toponad.net/v3/waterfall/units
5.2 Request method
PUT
5.3 Request params
| fields | type | required | notes |
|---|---|---|---|
| placement_id | String | Y | Placement ID |
| currency | String | Y | The currency units corresponding to ecpm, bid_floor, etc., can be set to USD or CNY. |
| items | Array[Object] | Y | List of all Waterfall information for multiple adsources. Note: If the default adsource is not yet bound to a segment_id, modify the property while simultaneously binding it to the segment. |
| items.id | Int | Y | Adsource ID |
| items.items | Array[Object] | Y | List of all Waterfall information under each Adsource ID Note: Since these are identical attributes, items must either be modified together or left unchanged altogether. |
| items.items.mediation_group_id | Int | Y | Mediation Group ID |
| items.items.segment_id | Int | Y | Segment ID |
| items.items.abtest_group_item_id | Int | Y | Segment A/B Test Group ID, where 0 indicates the current segment is not undergoing experimentation. |
| items.items.ecpm | Double | Y | eCPM price, currency unit specified by the request parameter currency |
| items.items.ecpm_rank | Int | Y | Adsource display priority at the same price, value range: [1,99], where a higher value indicates higher priority. |
| items.items.auto_ecpm_switch | Int | Y | Enable automatic eCPM optimization 1: Disable 2: Enable |
| items.items.show_delay | Int | Y | Delay show time, in milliseconds, range [5000]. Note: Only available for certain ad formats, such as interstitial ads. For non-interstitial ads or when not applicable, pass 0. |
| items.items.show_delay_rate | Int | Y | Delayed show probability, range [1,100]. Note: Only available for certain formats, such as interstitial ads. For non-interstitial or non-display formats, pass 0. |
| items.items.bid_floor | Double | Y | Bid Floor Price, currency unit specified by the request parameter ‘currency’. For non-bidding or no interest, pass 0. |
| items.items.setup_sw | Int | Y | Adsource enabled for this segment. Enumeration description: 1: Yes 2: No |
| items.items.cap_hour | Int | Y | Maximum show limit per hour. -1 indicates no restriction. Note: This attribute is only available for enabled adsource. Pass -1 when disabled. |
| items.items.cap_day | Int | Y | Maximum show limit per day. -1 indicates no restriction. Note: This attribute is only available for enabled adsource. Pass -1 when disabled. |
| items.items.pacing | Int | Y | Show interval, -1 indicates no restriction. Note: This property is only available for enabled adsource. Pass -1 when disabled. |
5.4 Return data
| fields | type | required | notes |
|---|---|---|---|
| items | Array[Object] | Y | List of invalid adsource information. Note: 1. If the list is empty, the operation was successful. 2. If the list is not empty, it indicates which adsource failed validation. All adsources (including those that passed validation) failed the operation. |
| items.index | Int | Y | The index of the item containing the error, starting from 0. |
| items.err_code | Int | Y | Error Code |
| items.err_msg | String | Y | Error Message |
5.5 Sample
Request address sample:
https://api.toponad.net/v3/waterfall/units
Sample request parameter:
{
"placement_id":"qdfji3434====",
"currency":"USD",
"items":[
{
"id": 2280206,
"items": [
{
"mediation_group_id": 273234,
"segment_id": 0,
"abtest_group_item_id": 0,
"ecpm": 2,
"ecpm_rank": 1,
"remark": "",
"setup_sw": 1,
"auto_ecpm_switch": 1,
"auto_ecpm": 0,
"cap_hour": -1,
"cap_day": -1,
"pacing": -1,
"show_delay": 0,
"show_delay_rate": 100,
"bid_floor": 0
}
]
}
]
}
Return sample:
{
"items": [
{
"index": 0,
"err_code": 4602,
"err_msg": "the mediation connection not found"
}
]
}
6. Get all adsources under the specified segment's A/B Test Group
Note: When the specified segment is not running an A/B Test, pass 0 for `abtest_group_item_id`. If an A/B Test is active, pass the corresponding A/B Test Group ID. If the parameter is incorrect or the current segment is running an A/B Test but the passed test group ID is 0, an error will be returned: {“errors”:“code: 4602, msg: the mediation connection not found”}
6.1 Request URL
6.2 Request method
GET
6.3 Request params
| params | type | required | notes |
|---|---|---|---|
| ecpm_currency | String | N | eCPM currency unit, default USD when not transmitting, optional CNY |
6.4 Return data
| fields | type | required | notes |
|---|---|---|---|
| offer_list_switch | Int | Y | |
| ecpm_currency | String | Y | eCPM currency unit, corresponding to the parameter ecpm_currency when requesting, Returns the ecpm and auto_ecpm prices in the ad_source_list parameter based on the corresponding unit value of this field |
| parallel_request_number | Int | Y | Parallel request number |
| offer_list | Array[Object] | Y | My offer list in used |
| offer_list.offer_id | String | Y | Offer id |
| offer_list.offer_name | String | Y | Offer name |
| ad_source_list | Array[Object] | Y | Adsources list in used |
| ad_source_list.ad_source_id | Int | Y | Adsource ID |
| ad_source_list.name | String | Y | Adsource name |
| ad_source_list.header_bidding_switch | Int | Y | If support Header Bidding, The unit was identified when it was created 1: not support, 2: support |
| ad_source_list.ecpm | String | Y | eCPM |
| ad_source_list.auto_ecpm_switch | Int | Y | Automatically optimize the ECPM 1: not open auto eCPM sort switch, 2: open auto eCPM sort switch |
| ad_source_list.auto_ecpm | String | Y | Auto eCPM |
| ad_source_list.hour_cap | Int | Y | -1 : close |
| ad_source_list.day_cap | Int | Y | -1 : close |
| ad_source_list.pacing | Int | Y | -1 : close |
| free_ad_source_list | Array[Object] | Y | Adsource list not in used |
| free_ad_source_list.ad_source_id | Int | Y | Adsource ID |
| free_ad_source_list.name | String | Y | Adsource name |
| free_ad_source_list.header_bidding_switch | Int | Y | If support Header Bidding, The unit was identified when it was created 1: Not support 2: Support |
| free_ad_source_list.ecpm | String | Y | eCPM |
| free_ad_source_list.auto_ecpm_switch | Int | Y | Automatically optimize the ECPM 1: not open auto eCPM sort switch, 2: open auto eCPM sort switch |
| free_ad_source_list.auto_ecpm | String | Y | Auto eCPM |
6.5 Sample
Request address sample:
https://api.toponad.net/v3/waterfall/116112/segment_id/600262/abtest_group_item_id/0/units
Sample request parameter:
{
"ecpm_currency" : "USD"
}
Return sample:
{
"offer_list_switch": 2,
"ecpm_currency": "USD",
"parallel_request_number": 2,
"offer_list": [],
"ad_source_list": [
{
"ad_source_id": 681853,
"name": "Chartboost_int_2",
"header_bidding_switch": 1,
"ecpm": "66",
"auto_ecpm_switch": 1,
"auto_ecpm": "0",
"hour_cap": -1,
"day_cap": -1,
"pacing": -1
},
{
"ad_source_id": 681852,
"name": "Sigmob_int_2",
"header_bidding_switch": 1,
"ecpm": "20",
"auto_ecpm_switch": 1,
"auto_ecpm": "0",
"hour_cap": 4,
"day_cap": 5,
"pacing": 6
}
],
"free_ad_source_list": [
{
"ad_source_id": 681851,
"name": "Kuaishou Ads_int_2",
"header_bidding_switch": 1,
"ecpm": "50",
"auto_ecpm_switch": 1,
"auto_ecpm": "0"
},
{
"ad_source_id": 681850,
"name": "Mintegral_int_1",
"header_bidding_switch": 1,
"ecpm": "100",
"auto_ecpm_switch": 1,
"auto_ecpm": "0"
},
{
"ad_source_id": 681854,
"name": "Facebook_int_2",
"header_bidding_switch": 1,
"ecpm": "22",
"auto_ecpm_switch": 1,
"auto_ecpm": "0"
}
]
}