{"_id":"56fd4bb9896b2c0e007160f6","__v":5,"githubsync":"","user":"56c39c05bc41330d009f25d7","version":{"_id":"56c35c56c0c4630d004e864f","project":"56c35c56c0c4630d004e864c","__v":8,"createdAt":"2016-02-16T17:28:54.864Z","releaseDate":"2016-02-16T17:28:54.864Z","categories":["56c35c57c0c4630d004e8650","56c7b9e5379b311700ed8fe3","56c7bab4606ee717003c4766","56c7bb3613e5400d001e8cbd","56cf3f5a5267d70b00494c4b","56cf3f866c5d7a13005ee894","56fd3956caad892200847bce","599da256e7742b002588bb02"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.5.0","version":"0.5"},"parentDoc":null,"project":"56c35c56c0c4630d004e864c","category":{"_id":"56fd3956caad892200847bce","__v":0,"project":"56c35c56c0c4630d004e864c","version":"56c35c56c0c4630d004e864f","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-03-31T14:51:02.977Z","from_sync":false,"order":1,"slug":"buzz-json-objects","title":"Buzz JSON Objects"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-31T16:09:29.537Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":9,"body":"Buzz uses the concept of [Targeting Modules and Strategies](doc:targeting-modules-and-strategies)  to determine valid keys and values for targeting. A list of valid keys and values can be found here: [List of Targeting Modules and Keys](doc:list-of-targeting-modules-and-keys).\n\nThe REST API supports two actions for Modules: A GET request will return the available targeting criteria for a module; and a POST request will validate whether the supplied JSON is valid targeting for the given module.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"GET\"\n}\n[/block]\nYou can easily get a description of all the supported `targeting keys` and valid values from a module by calling the API with a GET request and adding `/targeting/<module_key>` into the request as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/targeting/<module_key>\\\" -b cookies.txt -d '{}'\\n#A real example:\\ncurl -X GET \\\"[host]/rest/targeting/geo\\\" -b cookies.txt -d '{}'\\n#Specifying a key\\ncurl -X GET \\\"[host]/rest/targeting/geo\\\" -b cookies.txt -d '{\\\"key\\\":\\\"country\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThe results (truncated):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"success\\\": true,\\n    \\\"payload\\\": [\\n        {\\n            \\\"name\\\": \\\"country\\\",\\n            \\\"type\\\": \\\"list\\\",\\n            \\\"values\\\": [\\n                {\\n                    \\\"country_code_3\\\": \\\"ABW\\\",\\n                    \\\"country_code_2\\\": \\\"AW\\\",\\n                    \\\"country_name\\\": \\\"Aruba\\\"\\n                },\\n                {\\n                    \\\"country_code_3\\\": \\\"AFG\\\",\\n                    \\\"country_code_2\\\": \\\"AF\\\",\\n                    \\\"country_name\\\": \\\"Afghanistan\\\"\\n                }...\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nNote, the responses to the GET requests sometimes provide a string list of possible values (e.g. key=country), but in cases without a static list will provide help text (e.g. `\"key\"=\"zip\"` will return `“Postal code should be passed as a string\"`).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"POST\"\n}\n[/block]\nUsing the API you can validate a given JSON targeting statement with a targeting module and receive a useful error message if a mistake is detected.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\"[host]/rest/targeting/geo\\\" -b cookies.txt -d '{\\\"targeting\\\":[{\\\"geo\\\":[{\\\"include\\\":[{\\\"zip\\\":[\\\"11111\\\",\\\"11112\\\"]}]}]}]}'\\n\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Targeting JSON\"\n}\n[/block]\nTargeting is expressed as a JSON document with a specific syntax. Both the individual Targeting Modules and the Targeting Template module enforce this syntax to assure that any data sent to the ad server is properly validated and formatted.\nExample of valid targeting JSON:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n           \\\"geo\\\":\\n  \\t\\t\\t\\t\\t[\\n               {\\n                   \\\"include\\\":\\n                       {\\n                           \\\"country\\\": \\n                         \\t\\t\\t[\\n                                \\\"USA\\\"\\n                              ],\\n                           \\\"state\\\": \\n                         \\t\\t\\t[\\n                               \\\"NY\\\",\\n                               \\\"NJ\\\",\\n                               \\\"MA\\\",\\n                               \\\"MI\\\"\\n                           \\t]\\n                       }\\n               }\\n            ],\\n           \\\"time\\\":\\n  \\t\\t\\t\\t\\t[\\n               {\\n                   \\\"include_range\\\":\\n                       {\\n                           \\\"time_of_week\\\": \\n                         \\t\\t[\\n                              [0,1000],[2000,5000]\\n                            ]\\n                       }\\n               }\\n            ],\\n           \\\"site\\\": \\n  \\t\\t\\t\\t\\t[\\n               {\\n                   \\\"include\\\":\\n                       {\\n                           \\\"site_list\\\": \\n                         \\t\\t\\t[\\n                                \\\"1\\\"\\n                              ]\\n                       }\\n               }\\n            ],\\n            \\\"segment\\\": \\n  \\t\\t\\t\\t\\t[\\n               {\\n                   \\\"include\\\":\\n                       {\\n                           \\\"segment\\\":\\n                         \\t\\t\\t[\\n                                \\\"Women (Age > 25)\\\"\\n                              ]\\n                       }          \\n               },\\n               {\\n                   \\\"include\\\":\\n                       {\\n                          \\\"segment\\\":\\n                         \\t\\t\\t[\\n                                \\\"Women (Age < 40)\\\"\\n                              ]                                                  \\n                       }        \\n               }\\n            ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"JSON Structure\"\n}\n[/block]\nThe elements of the JSON targeting string is as follows:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key\",\n    \"h-1\": \"Example value\",\n    \"h-2\": \"Description\",\n    \"3-0\": \"values\",\n    \"3-1\": \"`\\\"start\\\": \\\"14:25\\\",\\\"end\\\": \\\"19:23\\\"`\",\n    \"3-2\": \"An array of JSON values corresponding to the key\",\n    \"0-0\": \"module_name\",\n    \"0-1\": \"`“time”: [{“include”: … }]`\",\n    \"0-2\": \"A list of sets with the key of a verb, generally `include` or `exclude`. The overall statement can include any number of modules, but each module may only appear once\",\n    \"1-0\": \"verb\",\n    \"1-1\": \"`“include”: {“key”: … }`\",\n    \"1-2\": \"Allowable verbs vary by module, but most commonly are “include” and “exclude”.\",\n    \"2-0\": \"key\",\n    \"2-1\": \"`“time_of_week”: [{ … }]`\",\n    \"2-2\": \"Keys are defined in the modules.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Boolean Expressions\"\n}\n[/block]\nBoolean expressions are supported for select targeting modules with support for `AND`, `NOT`, `OR` operators along with parentheses.\n\nFor example, the following boolean expression describes targeting a set of segments:\n\n```(segment=\"key-1\" AND segment=\"key-2\") OR (segment=\"key-3\" AND segment=\"key-4\") AND NOT segment=\"key-5\"```\n\nValidation of boolean expressions will confirm that the expression is valid (e.g. there aren't any un-matched parentheses or non-standard operators) and whether the individual key-value pairs are valid, but will not check to see if the expression is logically consistent.","excerpt":"","slug":"targeting","type":"basic","title":"Targeting Modules"}
Buzz uses the concept of [Targeting Modules and Strategies](doc:targeting-modules-and-strategies) to determine valid keys and values for targeting. A list of valid keys and values can be found here: [List of Targeting Modules and Keys](doc:list-of-targeting-modules-and-keys). The REST API supports two actions for Modules: A GET request will return the available targeting criteria for a module; and a POST request will validate whether the supplied JSON is valid targeting for the given module. [block:api-header] { "type": "basic", "title": "GET" } [/block] You can easily get a description of all the supported `targeting keys` and valid values from a module by calling the API with a GET request and adding `/targeting/<module_key>` into the request as follows: [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/targeting/<module_key>\" -b cookies.txt -d '{}'\n#A real example:\ncurl -X GET \"[host]/rest/targeting/geo\" -b cookies.txt -d '{}'\n#Specifying a key\ncurl -X GET \"[host]/rest/targeting/geo\" -b cookies.txt -d '{\"key\":\"country\"}'", "language": "curl" } ] } [/block] The results (truncated): [block:code] { "codes": [ { "code": "{\n \"success\": true,\n \"payload\": [\n {\n \"name\": \"country\",\n \"type\": \"list\",\n \"values\": [\n {\n \"country_code_3\": \"ABW\",\n \"country_code_2\": \"AW\",\n \"country_name\": \"Aruba\"\n },\n {\n \"country_code_3\": \"AFG\",\n \"country_code_2\": \"AF\",\n \"country_name\": \"Afghanistan\"\n }...", "language": "json" } ] } [/block] Note, the responses to the GET requests sometimes provide a string list of possible values (e.g. key=country), but in cases without a static list will provide help text (e.g. `"key"="zip"` will return `“Postal code should be passed as a string"`). [block:api-header] { "type": "basic", "title": "POST" } [/block] Using the API you can validate a given JSON targeting statement with a targeting module and receive a useful error message if a mistake is detected. [block:code] { "codes": [ { "code": "curl -X POST \"[host]/rest/targeting/geo\" -b cookies.txt -d '{\"targeting\":[{\"geo\":[{\"include\":[{\"zip\":[\"11111\",\"11112\"]}]}]}]}'\n", "language": "curl" } ] } [/block] [block:api-header] { "type": "basic", "title": "Targeting JSON" } [/block] Targeting is expressed as a JSON document with a specific syntax. Both the individual Targeting Modules and the Targeting Template module enforce this syntax to assure that any data sent to the ad server is properly validated and formatted. Example of valid targeting JSON: [block:code] { "codes": [ { "code": "{\n \"geo\":\n \t\t\t\t\t[\n {\n \"include\":\n {\n \"country\": \n \t\t\t[\n \"USA\"\n ],\n \"state\": \n \t\t\t[\n \"NY\",\n \"NJ\",\n \"MA\",\n \"MI\"\n \t]\n }\n }\n ],\n \"time\":\n \t\t\t\t\t[\n {\n \"include_range\":\n {\n \"time_of_week\": \n \t\t[\n [0,1000],[2000,5000]\n ]\n }\n }\n ],\n \"site\": \n \t\t\t\t\t[\n {\n \"include\":\n {\n \"site_list\": \n \t\t\t[\n \"1\"\n ]\n }\n }\n ],\n \"segment\": \n \t\t\t\t\t[\n {\n \"include\":\n {\n \"segment\":\n \t\t\t[\n \"Women (Age > 25)\"\n ]\n } \n },\n {\n \"include\":\n {\n \"segment\":\n \t\t\t[\n \"Women (Age < 40)\"\n ] \n } \n }\n ]\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "JSON Structure" } [/block] The elements of the JSON targeting string is as follows: [block:parameters] { "data": { "h-0": "Key", "h-1": "Example value", "h-2": "Description", "3-0": "values", "3-1": "`\"start\": \"14:25\",\"end\": \"19:23\"`", "3-2": "An array of JSON values corresponding to the key", "0-0": "module_name", "0-1": "`“time”: [{“include”: … }]`", "0-2": "A list of sets with the key of a verb, generally `include` or `exclude`. The overall statement can include any number of modules, but each module may only appear once", "1-0": "verb", "1-1": "`“include”: {“key”: … }`", "1-2": "Allowable verbs vary by module, but most commonly are “include” and “exclude”.", "2-0": "key", "2-1": "`“time_of_week”: [{ … }]`", "2-2": "Keys are defined in the modules." }, "cols": 3, "rows": 4 } [/block] [block:api-header] { "type": "basic", "title": "Boolean Expressions" } [/block] Boolean expressions are supported for select targeting modules with support for `AND`, `NOT`, `OR` operators along with parentheses. For example, the following boolean expression describes targeting a set of segments: ```(segment="key-1" AND segment="key-2") OR (segment="key-3" AND segment="key-4") AND NOT segment="key-5"``` Validation of boolean expressions will confirm that the expression is valid (e.g. there aren't any un-matched parentheses or non-standard operators) and whether the individual key-value pairs are valid, but will not check to see if the expression is logically consistent.