Data Science Toolkit - Custom model service

Article
02/22/2024

The Custom Model service lets you add and maintain custom predictive models (decision trees) for use in campaigns. For background information, see Custom Models.

Tip

Before adding a custom model, use the Custom Model Parser Service to check the validity and size of your decision tree.

REST API

Add a new custom model:

POST https://api.appnexus.com/custom-model  
(new_model JSON)

Modify a custom model:

PUT https://api.appnexus.com/custom-model?id=ID
(model_update JSON)

View all custom models:

GET https://api.appnexus.com/custom-model

View a specific custom model:

GET https://api.appnexus.com/custom-model?id=ID

Delete a custom model:

DELETE https://api.appnexus.com/custom-model?id=ID

Note

You cannot delete a custom model that is used by one or more campaigns.

Find out which fields you can filter and sort by:

GET https://api.appnexus.com/custom-model/meta

JSON fields

Field	Type (Length)	Description
`active`	Boolean	If `true`, the custom model is active and available for use in campaigns. Default: `true`
`advertiser_id`	int	The ID of the advertiser to which the custom model belongs. Required on: `POST`
`code`	string	A custom code that is used as an external ID or as a look-up value for an object. This value must be unique within your member.
`custom_model_structure`	enum	The structure of the custom model. Currently, the only allowed structure is `"decision_tree"`. Required on: `POST`
`id`	int	The ID of the custom model. Default: Auto-generated number Required On: `PUT/ DELETE`, in query string
`last_modified`	date	Read-only. The date and time when the custom model was last modified.
`member_id`	int	Read-only. The ID of the member to which the custom model belongs. Default: Member's ID
`model_output`	enum	The type of custom model. Possible values: - `"bid"`: The Bid Price model outputs a CPM bid. This type of model serves as a campaign's third-party buying strategy in place of standard CPM strategies. To use this type of model in a campaign, set `cpm_bid_type` to `"custom_model"` and then specify the custom model ID in the `bid_model` object. - `"bid_modifier"`: The Bid Modifier model applies a multiplier to a campaign's optimization-derived CPM bid. This type of model is used in conjunction with a Xandr optimization-based buying strategy (when `cpm_bid_type` is `"predicted"` or `"margin"`). To use this type of model in a campaign, specify the custom model ID in the `bid_modifier_model` object. Required on: `POST`
`model_text`	string	The logic of the model, expressed as a decision tree. You must write your decision tree in our Bonsai Language and then include a base64-encoded version here. Default: `null` Note: - Size limit: Your tree must be smaller than 3 MB, or 3,145,728 bytes. If it is larger than that, you will not be able to add your tree. - GET queries: In a GET query, the `model_text` will ONLY be returned if you provide a model ID in the query string. It will not be returned for unfiltered queries. - Check the Validity and Size of Your Tree. - Before adding a custom model, use the Custom Model Parser Service to check the validity and size of your decision tree. See that service for details about validation and error messages.
`name`	string (191)	The name of the custom model. This must be unique and must be no more than 191 characters. Required On: `POST`
`original_text`	string	Read-only. The decision tree in plain text. We provide this in the response so that you can retrieve and review your tree's original format whenever necessary to iterate on tree design. Note that tabs are replaced with `\t` and new lines are replaced with `\n`. Default: `null` Note: In a GET query, the `original_text` will ONLY be returned if you identify a specific model ID in the query string. It will not be returned for unfiltered queries.

Examples

View all custom models

$ curl -b cookies -c cookies 'https://api.appnexus.com/custom-model'
 
{
    "response": {
        "status": "OK",
        "count": 10,
        "start_element": 0,
        "num_elements": 100,
        "custom_models": [
            {
                "id": 327,
                "name": "Bid by Region/Hour of Day",
                                "code": "code1_abc12345",
                "member_id": 958,
                "advertiser_id": 39776,
                "custom_model_structure": "decision_tree",
                "model_output": "bid",
                "active": true,
                "last_modified": "2015-09-22 19:52:57"
            },
            {
                "id": 329,
                "name": "Bid by Device Type/Hour of Day",
                                "code": "code2_abc12345",
                "member_id": 958,
                "advertiser_id": 39776,
                "custom_model_structure": "decision_tree",
                "model_output": "bid",
                "active": true,
                "last_modified": "2015-09-22 20:52:53"
            },
            ...  
        ]
    }
}

View a specific custom model

$ curl -b cookies -c cookies 'https://api.appnexus.com/custom-model?id=327'
 
{
    "response": {
        "status": "OK",
        "count": 1,
        "start_element": 0,
        "num_elements": 100,
        "custom_model": {
            "id": 327,
            "name": "Bid by Region/Hour of Day",
                        "code": "code1_abc12345",
            "member_id": 1234,
            "advertiser_id": 39776,
            "custom_model_structure": "decision_tree",
            "model_output": "bid",
            "model_text": "aWYgZXZlcnkgcmVnaW9uID0gIlVTOkNBIiwgdXNlcl9ob3VyIHJhbmdlICgxMiwxNCk6CgkxLjUKZWxpZiBldmVyeSByZWdpb24gPSAiVVM6TlkiLCB1c2VyX2hvdXIgcmFuZ2UgKDEsMyk6CgkwLjEKZWxzZToKCTAuNQ==",
            "original_text": "if every region = \"US:CA\", user_hour range (12,14):\n\t1.5\nelif every region = \"US:NY\", user_hour range (1,3):\n\t0.1\nelse:\n\t0.5",
            "active": true,
            "last_modified": "2015-09-22 19:52:57"
        }
    }
}

Add a custom model

$ curl -b cookies -c cookies -X POST -d @custom_model.json 'https://api.appnexus.com/custom-model?member_id=1234'
$ cat custom_model.json
 
{
    "custom_model": {
        "name": "Bid by Device Type/Hour of Day", 
        "advertiser_id": 39776,
        "custom_model_structure": "decision_tree",
        "model_output": "bid",
                "model_text": "aWYgZXZlcnkgZGV2aWNlX3R5cGUgPSAiT3RoZXJzIChpbmNsdWRpbmcgUEMpIiwgdXNlcl9ob3VyIHJhbmdlICg5LDE4KToKCTEuNQplbGlmIGV2ZXJ5IGRldmljZV90eXBlIGluICgiVGFibGV0IiwgIlBob25lIiksIHVzZXJfaG91ciBpbiAoNSw2LDcsOCwxOSwyMCwyMSwyMik6CgkyCmVsc2U6CgkwLjU="
    }
}
 
$ curl -b cookies -c cookies -X POST -d @custom_model.json 'https://api.appnexus.com/custom-model'
 
{
    "response": {
        "status": "OK",
        "count": 1,
        "id": "329",
        "start_element": 0,
        "num_elements": 100,
        "custom_model": {
            "id": 329,
            "name": "Bid by Device Type/Hour of Day",
                        "code": null,
            "member_id": 1234,
            "advertiser_id": 39776,
            "custom_model_structure": "decision_tree",
            "model_output": "bid",
            "model_text": "aWYgZXZlcnkgZGV2aWNlX3R5cGUgPSAiT3RoZXJzIChpbmNsdWRpbmcgUEMpIiwgdXNlcl9ob3VyIHJhbmdlICg5LDE4KToKCTEuNQplbGlmIGV2ZXJ5IGRldmljZV90eXBlIGluICgiVGFibGV0IiwgIlBob25lIiksIHVzZXJfaG91ciBpbiAoNSw2LDcsOCwxOSwyMCwyMSwyMik6CgkyCmVsc2U6CgkwLjU=",
            "original_text": "if every device_type = \"Others (including PC)\", user_hour range (9,18):\n\t1.5\nelif every device_type in (\"Tablet\", \"Phone\"), user_hour in (5,6,7,8,19,20,21,22):\n\t2\nelse:\n\t0.5",
            "active": true,
            "last_modified": "2015-09-22 20:52:53"
        }
    }
}

Modify a custom model

$ cat custom_model_update.json 
 
{
    "custom_model": {
        "model_text": "aWYgc2VnbWVudCAxMjM0Og0KwqDCoMKgwqBpZi..."    
    }
}
 
$ curl -b cookies -c cookies -X PUT -d @custom_model_update.json 'https://api.appnexus.com/custom-model?id=3'
 
{
    "response": {
        "status": "OK",
        "count": 1,
        "start_element": 0,
        "num_elements": 100,
        "custom_model": {
            "id": 3,
            "name": "User Hour Model",
                        "code": null,
            "member_id": 1234,
            "advertiser_id": 83736,
            "custom_model_structure": "decision_tree",
            "model_output": "bid",
            "model_text": "aWYgc2VnbWVudCAxMjM0Og0KwqDCoMKgwqBpZi...",
            "original_text": "if every region = \"US:CA\", user_hour range (12,16):\n\t1.5\nelif every region = \"US:NY\", user_hour range (1,5):\n\t0.1\nelse:\n\t0.5",
            "active": true
        }
    }
}

Delete a custom model

$ curl -b cookies -c cookies -X DELETE 'https://api.appnexus.com/custom-model?id=3'
 
{
    "response": {
        "status": "OK",
        "count": 1,
        "start_element": null,
        "num_elements": null
    }
}

Share via

Data Science Toolkit - Custom model service

REST API

JSON fields

Examples

Additional resources

Share via

Data Science Toolkit - Custom model service

REST API

JSON fields

Examples

Related topics

Additional resources