Add Datapoints API

This API is used to add datapoints to a previously submitted project. Subsequent calls will replace all previously added datapoints.

Command

"client/addDatapoints/1"

Datapoints Array

The datapoints array will contain a detailed description of the targeting. Each datapoint will have:

String  name    //Name of datapoint. Each datapoint has a unique name and corresponding type. See the datapoints API for details.
JSON[]  values   //Array of JSON objects. The data in each object depends on the 'type' of datapoint.

Single Selection and Multiple Selection targeting

{
     name : "Household Income",  
     values : [2, 3, 4, 5]  
}

The value field refers to the element in position i of the answers array, which is a zero-based array. In the above example, the survey is targeting the "Household Income" datapoint, and only looking for respondents who selected options 2,3,4,5 (15K-99K). An askOnly parameter may be optionally set for a datapoint. If true, this means that the datapoint will be asked of a panelist, but will not be used to (dis)qualify them. This feature is useful in cases where the domains of two or datapoints overlap. For example, you have added both "DMA (US)" and "State (US)" for different quotas, say a Houston DMA quota and a Virginia State quota. If the project-level datapoints were not ask-only, no one would qualify as you cannot live in both Houston and Virginia at the same time. If these are set to ask-only, a panelist's DMA and State would be acquired and they would be (dis)qualified on the individual quotas.

Age range

{  
     name : "Age",  
     values : [{  
          max : 35,  
          min : 18  
     }, {  
          max : 45,  
          min : 35  
     }]  
}  

Children

{  
     name : "Children"
     values : [{  
          gender : 1,  
          max : 10,  
          min : 5  
     }, {  
          gender : 2,  
          max : 10,  
          min : 5  
     }]
}

The Children datapoint values may include these fields in the elements of the array:

• gender. Gender of the child. 0=any, 1=male, 2=female. If missing, then it is any.
• max. Maximum age of the child.
• min. Minimum age of the child.
• unit. Unit in which max and min values are given. 0=years, 1=months. If missing, then it is years.

List of postal codes

{  
     name : "List of Zips",  
     values : [  
          {  
               title: "Seattle Zips",  
               list : ["98115","98116","98117"]  
          },  
          {  
               title: "Wildcard Seattle",  
               list: ["981*","982*","97234"]  
          }
     ]  
}

Postal codes may be optionally quoted. Wildcards can be used in a list of zips. Wildcards should only be used at the end of a zip code, meaning that you are looking for panelists whose zip code starts with the digits that occur before the wildcard. In the example, that would mean that you are looking for panelists whose zip code starts with 981 or with 982 or that is exactly 97234. The accepted formats for postcodes by country are:

Australia, South Africa: 4 digits

US, Egypt, France, Germany, Indonesia, Italy, Malaysia, Mexico, Saudi Arabia, Spain, Thailand, Turkey: 5 digits

China, South Korea, Russia, Singapore, Vietnam: 6 digits

Brazil: 8 digits

Canada: AnAnAn

Argentina: AnnnnAAA

UK: AAnAnAA, AnAnAA, AnnAA, AnnnAA, AAnnAA, AAnnnA

Other: anything

List of Canadian FSAs

{  
     name : "List of FSAs (CA)",  
     values : [  
          {  
               title: "Some FSAs",  
               list: ["H1B","L1X","L4E"]  
          }  
     ]  
}

Inputs

The following values are expected in the JSON body:

Outputs

The JSON output will always contain the original command and a result. If the result > 0, an error has occurred (refer to Error Codes) and a message field will describe the error. If result = 0, the command succeeded and there will not be response field.

Example Command

{  
     command: "client/addDatapoints/1",  
     rfg_id : "RFG12345-001",  
     datapoints: [  
          {  
               name:"Age",  
               values:[{"min":14, "max":17}],  
          },  
          {  
               name:"Ethnicity (US)",  
               values:[1,5,6]  
          },  
          {  
               name:"Gender",  
               values:[1,2]  
          },  
          {  
               name:"Television Movies_AC",  
               values:[3,4],  
               askOnly: true  
          }  
     ]  
}