Segment API

1. Get Specifies All Mediation Groups Under The Placement ID

1.1 Request URL

https://api.toponad.net/v3/mediation_group/:placement_id

1.2 Request method

GET

1.3 Request params

None

1.4 Return data

fields	type	required	notes
data	Object	Y	-
data.mediation_group_id	Int	Y	Mediation Group ID
data.mediation_group_name	String	Y	A/B test group name
data.abtest_group_item_id	Int	Y	A/B test group id
data.traffic_variation	Int	Y	A/B test group weight
data.is_pending	Bool	Y	Whether a group is to take effect false test-in-process true Group to Take Effect
data.timezone	Int	Y	Time zone of the start time -12~12 = West 12 to East 12 It has a value when it takes effect
data.start_time	Int	Y	Start time, timestamp It has a value when it takes effect

1.5 Sample

Request sample：

https://api.toponad.net/v3/mediation_group/b60f6e9480e4ba

Return sample：

{
    "data": [
        {
            "mediation_group_id": 116112,
            "mediation_group_name": "A\u7ec4",
            "abtest_group_item_id": 10000080,
            "traffic_variation": 2,
            "is_pending": false,
            "time_zone": 0,
            "start_time": 0
        },
        {
            "mediation_group_id": 116113,
            "mediation_group_name": "B\u7ec4",
            "abtest_group_item_id": 10000081,
            "traffic_variation": 1,
            "is_pending": false,
            "time_zone": 0,
            "start_time": 0
        },
        {
            "mediation_group_id": 116114,
            "mediation_group_name": "C\u7ec4",
            "abtest_group_item_id": 10000082,
            "traffic_variation": 1,
            "is_pending": false,
            "time_zone": 0,
            "start_time": 0
        }
    ]
}

2. Get Specifies All Segment Groups In a Mediation Group

2.1 Request URL

https://api.toponad.net/v3/mediation_segment/:mediation_group_id

2.2 Request method

GET

2.3 Request params

None

2.4 Return data

fields	type	required	notes
data	Array[Object]	Y	-
data.segment_id	Int	Y	Segment ID
data.segment_name	String	Y	Segment name
data.priority	Int	Y	Segment weight
data.parallel_request_number	Int	Y	Number of parallel requests
data.auto_load	Int	Y	Default 0: off, only 0 or positive integer   for Banner, automatic refresh time can be set, and greater than 0 means automatic refresh time  for RV and plug-in screen, only the switch status of automatic request is controlled, and non-zero means on
data.hour_cap	Int	Y	-1: indicates off
data.day_cap	Int	Y	-1: indicates off
data.pacing	Int	Y	-1: indicates off
data.rules	Array[Object]	Y	Segment rules
data.rules.type	Int	Y	Segment rule type.Default 0, Enumeration Value Description： 0: country code(set) 1: time(interval) 2: weekday(set) 3: network_type(set 4: hour/1225/2203(interval) 5: custom rule(custom) 8: app version (set) 9: sdk version (set) 10: device_type (set) 11: device brand(set) 12: os version (set) 16: timezone (value) 17: Device ID (set) 19: city code (set)
data.rules.rule	Int	Y	Segment rule action.Default 0, Enumeration Value Description： 0: include(set) 1: exclude(set) 2: Greater than or equal(value) 3: Less than or equal(value) 4: in interval(interval) 5: not in interval(interval) 6: custom rule(custom) 7: Greater than(value) 8: Less than(value)
data.rules.content	Object	Y	See the appendix (Segment rule enum)

2.5 Sample

Request sample：

https://api.toponad.net/v3/mediation_segment/116112

Return sample：

{
    "data": [
        {
            "segment_id": 600270,
            "segment_name": "sdk_and_brand",
            "priority": 8,
            "parallel_request_number": 1,
            "auto_load": 0,
            "hour_cap": -1,
            "day_cap": -1,
            "pacing": -1,
            "rules": [
                {
                    "type": 9,
                    "rule": 7,
                    "content": "5.2.1"
                },
                {
                    "type": 11,
                    "rule": 1,
                    "content": [
                        "apple",
                        "acer",
                        "advan"
                    ]
                }
            ]
        },
        {
            "segment_id": 600262,
            "segment_name": "sdk",
            "priority": 9,
            "parallel_request_number": 1,
            "auto_load": 20,
            "hour_cap": 2,
            "day_cap": 3,
            "pacing": 4,
            "rules": [
                {
                    "type": 9,
                    "rule": 7,
                    "content": "5.2.1"
                }
            ]
        },
        {
            "segment_id": 0,
            "segment_name": "Default Segment",
            "priority": 10,
            "parallel_request_number": 1,
            "auto_load": 0,
            "hour_cap": -1,
            "day_cap": -1,
            "pacing": -1,
            "rules": []
        }
    ]
}

3. Creating a Segment Group

3.1 Request URL

https://api.toponad.net/v3/mediation_segment

3.2 Request method

POST

3.3 Request params

params	type	required	notes
app_id	String	Y	App ID
placement_id	String	Y	Placement ID
mediation_group_id	Int	Y	Mediation Group ID
segment_name	String	Y	Segment name
rules	Array[Object]	Y	Segment rules
rules.type	Int	Y	Segment rule type.Default 0, Enumeration Value Description： 0: country code(set) 1: time(interval) 2: weekday(set) 3: network_type(set 4: hour/1225/2203(interval) 5: custom rule(custom) 8: app version (set) 9: sdk version (set) 10: device_type (set) 11: device brand(set) 12: os version (set) 16: timezone (value) 17: Device ID (set) 19: city code (set)
rules.rule	Int	Y	Segment rule action.Default 0, Enumeration Value Description： 0: include(set) 1: exclude(set) 2: Greater than or equal(value) 3: Less than or equal(value) 4: in interval(interval) 5: not in interval(interval) 6: custom rule(custom) 7: Greater than(value) 8: Less than(value)
rules.content	Object	Y	See the appendix (Segment rule enum)

3.4 Return data

fields	type	required	notes
id	int	Y	Segment ID

3.5 Sample

Request sample：

{
    'app_id'             : 'a60f54770a583d',
    'placement_id'       : 'b60f6e9480e4ba',
    'mediation_group_id' : 116112,
    'segment_name'       : 'sdk_and_brand',
    'rules'              : [
        {
            "rule"    : 7,
            "type"    : 9,
            "content" : "5.2.1",
        },
        {
            "type"    : 11,
            "rule"    : 1,
            "content" : [
                "apple",
                "acer",
                "advan",
            ],
        },

    ],
}

Return sample：

{
    "id": 600271
}

4. Set Segment Priority

4.1 Request URL

https://api.toponad.net/v3/mediation_segment_priority/:mediation_group_id

4.2 Request method

PUT

4.3 Request params

params	type	required	notes
app_id	String	Y	App ID
placement_id	String	Y	Placement ID
segment_ids	Array[Int]	Y	Multiple segment is an array

4.4 Return data

fields	type	required	notes
segment_ids	Array[int]	Y	Multiple segment is an array

4.5 Sample

Request address sample：

https://api.toponad.net/v3/mediation_segment_priority/116112

Sample request parameter：

{
    'app_id'       : 'a60f54770a583d',
    'placement_id' : 'b60f6e9480e4ba',
    'segment_ids'  : [
        600269,
        600268,
        600265,
        600264,
        600263,
        600261,
        600258,
        600270,
        600262
    ],
}

Return sample：

{
    "ids": [
        600269,
        600268,
        600265,
        600264,
        600263,
        600261,
        600258,
        600270,
        600262
    ]
}

5. Update Segment Group

5.1 Request URL

https://api.toponad.net/v3/mediation_segment/:segment_id

5.2 Request method

PUT

5.3 Request params

params	type	required	notes
app_id	String	Y	App ID
placement_id	String	Y	Placement ID
mediation_group_id	Int	Y	Mediation Group ID
segment_name	String	Y	Segment name
rules	Array[Object]	Y	Segment rules
rules.type	Int	Y	Segment rule type.Default 0, Enumeration Value Description： 0: country code(set) 1: time(interval) 2: weekday(set) 3: network_type(set 4: hour/1225/2203(interval) 5: custom rule(custom) 8: app version (set) 9: sdk version (set) 10: device_type (set) 11: device brand(set) 12: os version (set) 16: timezone (value) 17: Device ID (set) 19: city code (set)
rules.rule	Int	Y	Segment rule action.Default 0, Enumeration Value Description： 0: include(set) 1: exclude(set) 2: Greater than or equal(value) 3: Less than or equal(value) 4: in interval(interval) 5: not in interval(interval) 6: custom rule(custom) 7: Greater than(value) 8: Less than(value)
rules.content	Object	Y	See the appendix (Segment rule enum)

5.4 Return data

fields	type	required	notes
id	Int	Y	Segment ID

5.5 Sample

Request address sample：

https://api.toponad.net/v3/mediation_segment/600262

Sample request parameter：

{
    'app_id'             : 'a60f54770a583d',
    'placement_id'       : 'b60f6e9480e4ba',
    'mediation_group_id' : 116112,
    'segment_name'       : 'new_CHINA_update',
    'rules'              : [
        {
            "rule"    : 7,
            "type"    : 9,
            "content" : "5.2.1",
        },
    ],
}

Return sample：

{
    "id": 600262
}

6. Delete Segment Group

6.1 Request URL

https://api.toponad.net/v3/mediation_segment/:segment_id

6.2 Request method

DELETE

6.3 Request params

params	type	required	notes
placement_id	String	Y	Placement ID
mediation_group_id	Int	Y	Mediation Group ID

6.4 Return data

fields	type	required	notes
id	Int	Y	Segment ID

6.5 Sample

Request address sample：

https://openapi.toponad.com/v3/mediation_segment/600267

Sample request parameter：

{
    'placement_id'       : 'b60f6e9480e4ba',
    'mediation_group_id' : 116112,
}

Return sample：

{
    "id": 600267
}

7. Set Attributes of Segments in Waterfall

7.1 Request URL

https://api.toponad.net/v3/mediation_segment/:mediation_group_id/segment_id/:segment_id/attributes

7.2 Request method

POST

7.3 Request params

params	type	required	notes
parallel_request_number	Int	Y	Parallel Request Number
auto_load	Int	N	Default 0: off, only 0 or positive integer  for Banner, automatic refresh time can be set, and greater than 0 means automatic refresh time  for RV and plug-in screen, only the switch status of automatic request is controlled, and non-zero means on.
hour_cap	Int	N	Do not pass or pass -1 means unlimited, pass in a positive integer means the specific Cap value
day_cap	Int	N	Do not pass or pass -1 means unlimited, pass in a positive integer means the specific Cap value
pacing	Int	N	Do not pass or pass -1 means unlimited, pass in a positive integer means the specific Pacing value

7.4 Return data

fields	type	required	notes
id	Int	Y	Segment ID

7.5 Sample

Request address sample：

https://api.toponad.net/v3/mediation_segment/116112/segment_id/600262/attributes

Sample request parameter：

{
    "id" : 600262
    "auto_load" : 20,
    "hour_cap" : 2,
    "day_cap" : 3,
    "pacing" : 4,
}

Return sample：

{
    "id": 600262
}

8. Get Setting of Placement Segment

8.1 Request URL

https://api.toponad.net/v3/mediation_segment/strategies

8.2 Request method

GET

8.3 Request Params

8.4 Return Params

8.5 Sample

Request Sample：

curl --location --request GET https://api.toponad.net/v3/mediation_segment/strategies?currency=USD&placement_id=b648a83d80eaxx' \
--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：

[
    {
        "mediation_group_id": 273566,
        "segment_id": 0,
        "segment_name": "",
        "bid_floor": 1.25，
        "parallel_req_type": 1,
        "parallel_req_num": 7,
        "auto_refresh_time": -1,
        "hour_cap": 100,
        "day_cap": 200,
        "pacing": 300,
        "intel_opt_cache": 1
    },
    {
        "mediation_group_id": 273566,
        "segment_id": 652072,
        "segment_name": "渠道",
        "bid_floor": -1，
        "parallel_req_type": 2,
        "auto_refresh_time": 15,
        "hour_cap": 100,
        "day_cap": 200,
        "pacing": 300,
        "intel_opt_cache": 1
    }
]

9. Edit Setting of Placement Segment

9.1 Request URL

https://api.toponad.net/v3/mediation_segment/strategies

9.2 Request method

PUT

9.3 Request params

params	type	required	notes
placement_id	String	Y	Taku's placement ID. It can be obtained after creating a placement through [Placement API 1]
currency	String	Y	The currency unit of the currency-related attributes in the items data, such as the bid_floor
items	Array[Object]	Y	Setting item list
items.mediation_group_id	Int	Y	Taku mediation group ID
items.segment_id	Int	Y	Segment ID under Taku mediation group, 0 represents the default group
items.bid_floor	Double	N	Bidding floor price, enum description:  -1: no limit (default) other: The maximum value is 10000. The minimum value is 0.01 for US dollars and 0.1 for RMB Notes: No parameter or 0 means no modification. Notes: For specific networks supported by the bid floor, please check the Header Bidding Integration instructions. Set a bid floor for the bidding ad sources so that the bids with relatively low price will be filtered out.Please also pay attention that it will decrease the fill rate and revenue of this ad source.If a bid floor is set for both the traffic group and the AD source, the bid floor for the AD source will be used.(CNY = ￥0.1, USD= $ 0.01 for minimum changes).
items.parallel_req_type	Int	N	Request Type, enum description： 1：fixed request number 2：parallel request by price Notes: No parameter or 0 means no modification. Notes: This is for parallel request type specifying. Fixed request number: the exact number of parallel requests will be sent out simultaneously (you need to set the number in request number column). Parallel request by price (supported by Taku SDK v5.9.20 and above): parallel requests will be sent out for the ad sources with the same price. Note, parallel requests will not affect the priorities of the impressions which will be executed strictly by the sequence of the waterfall configuration.
items.parallel_req_num	Int	N	Request Number, the recommended value is 2, the default value refer to the publisher backend, notes：return only when parallel_req_type choose fixed request number Notes: No parameter or 0 means no modification. Notes: Request number is set to 1 means serial request (one request a time). If set to n (n>1), we will send out n requests to the top n ad sources in your waterfall at the same time. If all of them failed then we will send out requests to n+1 - 2n ad sources. This could potentially bring you better performance for placements which show ads with high frequency.
items.auto_refresh_time	Int	N	Auto Refresh(Auto Request), enum description for different formats: Notes: No parameter or 0 means no modification. Banner (automatic refresh when refresh mode is [Manual Optimization]): -1 (auto refresh off); range [1,1000], default = 15 (auto refresh interval, unit: seconds). (Notes: Set the interval between regular automatic refresh of advertisements. It is recommended that the interval should be 10 to 150 seconds. If it is not filled, the automatic refresh function will not be enabled. Note: before enabling Taku automatic refresh, make sure that the automatic refresh or rotation function of third-party advertising sources is turned off, otherwise the display and revenue of advertisements will be affected.) Rewarded video/interstitial /Splash Ads (automatic request): -1 (auto refresh off); 1 (auto refresh on). (Notes: Once the ad is shown, closed or isReady is False, the Taku SDK will automatically request the ad for the next impression.If the client has processed the pre-loading logic as suggested in the integrated documentation, it is not recommended to turn on this function.) Native ads and other formats: no auto refresh function, ignore, just set 0
items.hour_cap	Int	N	Display cap (per hour), enum description: -1: no limit (default) Positive integer: the maximum number of displays Notes: No parameter or 0 means no modification.
items.day_cap	Int	N	Display cap (per day), enum description: -1: no limit (default) Positive integer: the maximum number of displays Notes: No parameter or 0 means no modification.
items.pacing	Int	N	Display interval (seconds), enum description:  -1: no limit (default) Positive integer: the number of seconds for the interval Notes: No parameter or 0 means no modification.
items.intel_opt_cache	Int	N	Smart optimization, enumeration description: 1: Off(default) 2: Price Priority 3: Display Priority Notes: No parameter or 0 means no modification. Notes: Taku's Smart Optimized Cache function will automatically increase the ad cache according to the ad cache of the current placement. Smart Optimized Caching supports two modes: Price priority: Taku will automatically optimize the ad cache according to the current ad cache to improve the filling price. Impression priority : Taku will automatically optimize the ad cache based on the current ad cache situation to increase the per capita impressions . You can choose the Smart Optimized Cache mode suitable for your placement through AB experiment. Smart Optimized Cache mode needs to update Taku Android SDK v6.2.16 and above, Taku iOS SDK v6.2.48 and above.
items.bf_ldf_rf_sw	Int	N	Request Fails Retry Switch, enum description： 1：On 2：Off Notes: No parameter or 0 means no modification. Notes: Automatically resent the request if it fails. This will increase the numbers of requests and attempts. Supported by Taku SDK v5.9.40 and above.

9.4 Return data

fields	type	required	notes
items	Array[Object]	N	Error list of ad source information, note: If the list is empty, it indicates the operation is successful. If the list is not empty, it indicates which items failed validation, and all items (including those that passed validation) have failed the operation.
items.index	Int	Y	Index of the error item, starting from 0
items.err_code	Int	Y	Error code
items.err_msg	String	Y	Error message

9.5 Sample

Sample request parameter：

curl --location --request PUT 'https://api.toponad.net/v3/mediation_segment/strategies' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "placement_id" : "b648a83d80eaxx",
    "currency" : "CNY",
    "items" : [
        {
            "mediation_group_id":273566,
            "segment_id":0,
            "bid_floor": -1,
            "parallel_req_type":1,
            "parallel_req_num": 7,
            "auto_refresh_time":-1,
            "hour_cap":100,
            "day_cap":200,
            "pacing":300,
            "intel_opt_cache":1,
           "cached_offers_num"：5
        }
    ]
}'

Return data：

{}