POST /AUDIENCE
  • 4 Minutes to read

    POST /AUDIENCE


      Article summary

      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_-"
                              }
                      ]
              }
      }


      Was this article helpful?