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¶
Property Name |
Type |
Description |
|---|---|---|
urn |
String |
User identifier must conform to “urnType” specified in metadata. |
seg (segment inclusions and exclusions) |
Array |
A list of taxonomy entities, of type SEGMENT, that this user should now be qualified in or removed from. Each value in this array is an object with the following keys: Id [required] - It must be the “id” of a taxonomy-entity with type = “SEGMENT”. Call GET /taxonomy to fetch your active taxonomy. All new uploads are validated against the taxonomy version active at the time of processing. Ts [optional] - Timestamp associated with this qualification. It must be a UNIX epoch value expressed in seconds, e.g., 1376244670 for “Sun Aug 11 18:11:10 2013”. Its value must represent a time in the past. Exp: [optional] - It represents expiry associated with this qualification. must be a UNIX epoch value expressed in seconds, e.g., 1379234569 for “Sun Sep 15 08:42:49 2013”. Its value must represent a time in the future (upto 90 days), or 0 to expire immediately. For example, use value 0 to delete users from a segment or raw attributes associated with them. |
att (attributes) |
Array |
One or more sets of attribute id and value pairs for this user. Each value in this array is an object with the following keys: Id [required] - Same as “seg.id” above, except type of the taxonomy entity must be ATTRIBUTE. Ts [optional] - Same as “seg.ts” above. Exp [optional] - Same as “seg.exp” above. |
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_-"
}
]
}
}