POST /AUDIENCE

Use this API to upload any and all types of user data. This is a “one stop shop” for uploading data. Use it to upload one or more segments, scores and/or a set of attributes, or a disjoint mixture of all of these in a single upload for a set of users.

DataX also provides use-case specific APIs to upload a single segment as a list of users, or a score (or any attribute defined in the taxonomy) as a simple key value pair for a set of users. We recommend that you use this API, if possible.

Note

A taxonomy request should be sent before the audience request. Also there should be a 30 minute delay between the taxonomy and audience request.

JSON Representation

Data in this representation is organized as a set of segment qualifications and attribute values on a per-user basis. Each user record is treated as an independent data unit, i.e., each user may have a completely different set of segment & attribute data specified in the same upload. A single record in the payload must be represented as the following JSON object:

{
        "urn":{string}, "seg":[{"id":{string},"ts":{number},"exp":{number}}],
        "att":[{"id":{string},"ts":{number},"exp":{number}, "val":{string}}]
}

ResourceType for this representation is “datax-audience”.

JSON Key Descriptions

Representation Example 1 – Upload segment inclusions, exclusions and attributes

Individual rows of an upload may represent the following JSON objects. Every row represents a single user record. Two different user records should be formatted in two different rows (separated by a new line). Qualifications/attributes specified for one user can be completely different from those specified for a different user within the same upload. (Please note: each row must be formatted as a single line of input.)

Row 1:

{
        "urn" : "99ff2333f3fe7659c38b3674bc927f32",
        "seg" : [{"id":"OH224"},{"id":"AB288"},{"id":"OH228"}],
        "att" : [{"id":"R2345","val":"Modern"},{"id":"R2453","val":32}]
}

Row 2:

{
        "urn" : "043f2e01b8f170ae7ae60bee17df199c",
        "seg" : [{"id":"AB288"},{"id":"TX333"}],
        "att" : [{"id":"YaRetail-Zipcode","val":"94089"}]
}

Representation Example 2 – Upload user qualifications for segment OH224

A three row sample for a segment with taxonomy Id “OH224”:

{"urn" : "99ff2333f3fe7659c38b3674bc927f32","seg" : [{"id":"OH224"}]}
{"urn" : " 07feb252623ad6302bd64ff0885339d3","seg" : [{"id":"OH224"}]}
{"urn" : " f10d53af308a12eb4d9bbd07a68067e6","seg" : [{"id":"OH224"}]}

Representation Example 3 – Upload a score file

A three row sample for an attribute with taxonomy Id “YaScore”:

{"urn":"07feb252623ad6302bd64ff039d3","att":[{"id":"YaScore","val":28}]}
{"urn":"99ff2333f3fe7659c38b36747f32","att":[{"id":"YaScore","val":99}]}
{"urn":"f10ad53af308a12eb4d9bbd067e6","att":[{"id":"YaScore","val":2}]}

POST Call Example

Request

POST /v1/audience HTTP/1.1
Host: datax.yahooapis.com
Content-Type: multipart/form-data;boundary=xyz

--xyz
Content-Type: application/json;charset=UTF-8 Content-Disposition: form-data; name="metadata"
{
        "description" : "user qualifications – daily bucket 05/19/2013",
        "extensions" : { "urnType" : "IXID" }
}
--xyz
Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: form-data; name="data"

< bz2 compressed data >
--xyz--

Successful Response

HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8 Date: Sun, 19 May 2013 12:29:09 GMT

{
        "resourceType" : "datax-audience",
        "resourceId" : "130815T013759Z662589033",
        "description" : "user qualifications – daily bucket 05/19/2013",
        "createTime" : "2013-19-05T12:19:17Z",
        "links" : [
                {
                        "rel"   : "self",
                        "href" : "https://datax.yahooapis.com/v1/link/s/mJF90HlzC0618PRm-"
                },
                {
                        "rel"   : "describes",
                        "href" : "https://datax.yahooapis.com/v1/link/5qMQo4h4c2zi-"
                }
        ],
        "status" : {
                "state" : "PROCESSING",
                "lastUpdateTime" : "2013-19-05T12:22:17Z "
        },
        "extensions" : { "urnType" : "IXID",
        "view" : "INCREMENTAL",
                "links" : [
                        {
                                "rel"   : "https://datax.yahooapis.com/rels/taxonomy",
                                "href" : "https://datax.yahooapis.com/v1/link/O3stRliZAT.G.oqiu-"
                        },
                        {
                                "rel"   : "https://datax.yahooapis.com/rels/stats",
                                "href" : "https://datax.yahooapis.com/v1/link/VJbGt6S0hiqECL_-"
                        }
                ]
        }
}