User/Audience Data

User data can be represented and uploaded in various formats to suit your use case, preferences, and backend implementations.

DataX provides the following format options:

1. “datax-audience”: This is the recommended “one-stop-shop” format to upload segments, attributes, and scores using the same JSON format via a single POST on the /audience resource. You can upload any possible mix of segments and attributes on a per-user (urn) basis using this format and API.

2. “datax-segment”: An alternate way of uploading a single segment, if you don’t prefer the more versatile “datax-audience” format. This is a simple text format - essentially a list of users (urn) provided against a POST on /audience/segment/{your-segment-id}

3. “datax-attribute”: An alternate way of uploading a single attribute, if you don’t prefer the more versatile “datax-audience” format. This format is a JSON key-value pair of user-id (urn) and attribute-value provided via a POST on /audience/attribute/{your-attribute-id}

The tables below provide examples and format for each of these APIs.

Note

1. Timestamp (ts) can also be provided at a meta data level, for the entire upload, in all three formats.

2. Expiry (exp) can also be provided at a meta data level, for the entire upload, in all three formats.

Example: Post user/audience data using curl

Once the taxonomy is established, “YaRetail” could upload user updates as shown below, using the curl http client as an example:

curl -X POST -H "Content-Type: multipart/form-data" \
-F 'metadata={"description":"Hourly Refresh","extensions":{"urnType":"IXID"}}' \
-F '[email protected];type=application/octet-stream' \ datax.yahooapis.com/v1/audience

Where yahooUpdate201305050515.bz2 may have the following updates (records for 5 users shown):

{"urn":"df32sx-","seg":[{"id":"YA1"},{"id":"YA2"}],"att":[{"id":"MA1","val":"25"}]}
{"urn":"hnsu72-","seg":[{"id":"YA3"}],"att":[{"id":"MA1","val":"35"}]}
{"urn":"zq23n7-","seg":[{"id":"YA4"},{"id":"YA2"},{"id":"YA1"}]}
{"urn":"quufy2-","seg":[{"id":"YA3"},{"id":"YA1"}],"att":[{"id":"MA1","val":"22"}]}
{"urn":"x.224k-","seg":[{"id":"YA2"}],"att":[{"id":"MA2","val":"3","ts":1376329529}]}

DataX will send back a 202 Accepted response with the following sample MetaData+ in JSON:

{
        "resourceType" : "datax-audience",
        "resourceId" : "130815T013759Z232589138",
        "createTime" : "2013-15-06T12:26:12Z",
        "description" : "YaRetail Refresh",
        "links" : [{
                        "rel"   : "self",
                        "href" : "https://datax.yahooapis.com/v1/link/s/y1G8sE9foJgj7tGEJV-"
                },{
                        "rel"   : "describes",
                        "href" : "https://datax.yahooapis.com/v1/link/uy5fasadda13kqojrtunwd-"
                }],
                "status" : {
                        "state" : "PROCESSING",
                        "lastUpdateTime" : "2013-15-06T12:26:12Z"
                },
                "extensions" : { "urnType" : "IXID",
                        "view" : "INCREMENTAL",
                        "links" : [{
                                "rel"   : "https://datax.yahooapis.com/rels/taxonomy",
                                "href" : "https://datax.yahooapis.com/v1/link/rw5fasr4akqoawjrtkhaQ-"
                                },{
                                "rel"   : "https://datax.yahooapis.com/rels/audience-stats",
                                "href" : "https://datax.yahooapis.com/v1/link/op54asr4akawjr87jhaQ-"
                                },{
                                "rel"   : "https://datax.yahooapis.com/rels/process-failed",
                                "href" : "https://datax.yahooapis.com/v1/link/anutnd782kaddliyn92F-"
                                }]
        }
}

You could use the “self” link to re-fetch this metadata for an updated status. The metadata structure also provides an error list on failure (not shown in this example).