User and Audience Data
  • 2 Minutes to read

    User and Audience Data


      Article summary

      User data can be represented and uploaded in near real-time (~5 minutes) to suit your use case, preferences, and backend implementations.

      Format

      The DataX Real-Time API provides the following format:

      “datax-audience”: A “one-stop-shop” format to upload segments, attributes, and scores using the same JSON format via a single Payload POST on the /audience resource.

      Note

      Support of attribute uploads will be coming soon.

      Metadata

      User Data resource collectors define an extension over the Base DataX Online Metadata structure.

      JSON Structure

      Request body:

      {
                            (Base DataX Online Metadata)
      
       "Schema"  :  [
         "GPSAID",
         "IXID",
         "IDFA",
         "SEGMENTS"
       ],
      
       "Data"  :  [
         [
           "GPSAID1",
           "IXID1",
           "IDFA1",
           "exp=1376244671&seg_id=1234&ts=1376244670;seg_id=5678;seg_id=101112
         ],
         [
           "",
           "",
           "IDFA2",
           "seg_id=999;seg_id=12321;seg_id=8787"
         ]
       ]
      }

      Response body:

      {
        "totalRows": 8,
        "processedRows": 6,
        "invalidRows": 2,
        "exampleInvalidRows": [
          "[DXID3, IXID3]",
          "[DXID1, IXID1, IDFA1]"
        ]
      }

      Response headers

      content-type: application/json;charset=utf-8 date: Wed, 31 Dec 2019 19:28:51 GMT transfer-encoding: chunked

      Important points above payload

      • Providers can define their own schema to use for audience data ingestion.

      • Overall within payload there are NO JSON objects in order to make it as close as possible to a schema-less design.

      • By defining a “schema” a user specifies how every row in the key “data” of the JSON should be processed.

      • Possible URN values in the schema are:

        • “IDFA”

        • “GPSAID”

        • “AXID”

        • “IXID”

        • “EMAIL”

        • “PXID”

        • “SEGMENT_ID”

      • SEGMENT_ID should always be the last value in the schema list.

      • Any number of semi-colon separated segment ids can be sent in a row for an user.

      • 12345;01112;459393

      • If an expiration date needs to be passed (Optional) with a segment id, follow the format as below:

      • Start with expiration date prefixing it with “&exp=”, so date will be &exp=<UNIX epoch>

      • Then before the actual segment id prefix it with “&seg_id=”, so it becomes &seg_id=123456

      • exp=1376244671&seg_id=1234

      • Finally there will be the timestamp with “&ts=” (Optional).

      • So overall segment id with expiration will look like: exp=1376244670&seg_id=123456&ts=1376244670

      • The comma-separated values in each row of the key “data” will be read in the same order as the schema is defined and every row must have the same number of comma separated values.

      • Supported Values; null, “null” or “ ”)

      • This schema format gives users the flexibility to send multiple urn types as well segments with or without expiration in the same request.

      POST/audience

      POST  /online/audience
      HOST https://dataxonline.yahoo.com/
      -H “Authorization: bearer: <obtained token>”
      -H “Content-Type: application/json”
      {"schema":["IXID","IDFA","GPADVID","SEGMENTS"],"data":[["","IXID1","","exp=1576346458&seg_id=1234&ts=1376244670;6789;1010"],["","IXID2","IDFA2","seg_id=14444;8777;exp=15763464583&seg_id=2322"],["IXID3","IDFA3","GPADVID3","exp=1576346458&seg_id=4555;3333;9919"]]}

      Error Responses

      Error Code

      Error Message

      Description

      DXOL5xx

      UNABLE_TO_PROCESS_REQUEST

      Server was not available during the processing time.

      DXOL429

      Exceeded rate limit, calls are not permitted at this time, try again later.

      Hourly rate limit has been reached. Please wait and try again at the top of the hour.

      DXOL4xx

      INVALID_SCHEMA

      Missing SEGMENTS from schema.

      DXOL4xx

      DUPLICATE_URN_TYPE

      Duplicate URN type in schema.

      DXOL4xx

      TOO_MANY_DATA_ROWS

      More than 10k rows have been identified in this payload.

      DXOL4xx

      INVALID_ACCESS_TOKEN

      Oauth 2.0 access token has expired. Please generate a new token.


      Was this article helpful?

      What's Next