Audience API

Note: In order to use the Audience API, you first need a data integration added to your account. Discuss this with your Account Manager. When created, the providers can be enabled or disabled.

The Audience API allows you to retrieve audience data provider information. Audience targeting is a way to target certain audiences by requesting ads with specific audience parameters. A very typical case is age and gender, where age and gender are two different parameters of the same targeting.

Getting Started

  • Base URL: https://api.videoplaza.com/v0/audience.
  • Requests: GET requests are used. You pass parameters by using common REST parameters like PATH, as well as HTTP HEADERS. The body of the requests should be provided in JSON format and encoded using UTF-8.
  • Responses: All responses contain an HTTP status code in the header and the body is in JSON format.
  • Swagger documentation: https://api.videoplaza.com/v1/swagger
  • Related user documentation:
The Audience API allows you to retrieve audience data provider information:

List Audience Providers

Method GET
URL https://api.videoplaza.com/v0/audience
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: list of audience data providers and their corresponding information

[
    {
        "id": "<string>",
        "name": "<string>",
        "urlIdentifier": "<string>",
        "useSessionStore": <boolean>,
        "useCookies": <boolean>,
        "enabled": <boolean>,
        "audienceSegmentValues": [
            {
                "segmentId": "<string>",
                "segmentName": "<string>"
            },
            {
                "segmentId": "<string>",
                "segmentName": "<string>"
            }
        ]
    },
    {
        {
        "id": "<string>",
        "name": "<string>",
        "urlIdentifier": "<string>",
        "useSessionStore": <boolean>,
        "useCookies": <boolean>,
        "enabled": <boolean>,
        "audienceSegmentValues": [
            {
                "segmentId": "<string>",
                "segmentName": "<string>"
            },
            {
                "segmentId": "<string>",
                "segmentName": "<string>"
            }
        ]
    }
]

Example:

Request header:

POST /v0/audience HTTP/1.1
Host: api.videoplaza.com
Content-­type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  200 (OK)

Body:
[
    {
        "id": "8915b4ad-0572-4d88-acf9-7f0813c953b5",
        "name": "Audience",
        "urlIdentifier": "dmpAudience",
        "useSessionStore": false,
        "useCookies": true,
        "enabled": true,
        "audienceSegmentValues": [
            {
                "segmentId": "kv1002",
                "segmentName": "Age"
            },
            {
                "segmentId": "kv1002",
                "segmentName": "Age"
            },
            {
                "segmentId": "kv1002",
                "segmentName": "Age"
            },
            {
                "segmentId": "kv1002",
                "segmentName": "Age"
            },
            {
                "segmentId": "kv1002",
                "segmentName": "Age"
            },
            {
                "segmentId": "kv1002",
                "segmentName": "Age"
            },
            {
                "segmentId": "kv1002",
                "segmentName": "Age"
            },
            {
                "segmentId": "kv1001",
                "segmentName": "Gender"
            },
            {
                "segmentId": "kv1001",
                "segmentName": "Gender"
            }
        ]
    },
    {
        "id": "49de123e-0ebd-4aab-890d-de6aba6ca593",
        "name": "Lotame_Data",
        "urlIdentifier": "lotameParam",
        "useSessionStore": false,
        "useCookies": true,
        "enabled": true,
        "audienceSegmentValues": [
            {
                "segmentId": "aff_food",
                "segmentName": "aff"
            },
            {
                "segmentId": "aff_lifestyle",
                "segmentName": "aff"
            },
            {
                "segmentId": "aff_other",
                "segmentName": "aff"
            },
            {
                "segmentId": "aff_other",
                "segmentName": "aff"
            },
            {
                "segmentId": "aff_lifestyle",
                "segmentName": "aff"
            },
            {
                "segmentId": "aff_other",
                "segmentName": "aff"
            },
            {
                "segmentId": "aff_lifestyle",
                "segmentName": "aff"
            },
            {
                "segmentId": "aff_bati",
                "segmentName": "aff"
            },
            {
                "segmentId": "aff_other",
                "segmentName": "aff"
            },
            {
                "segmentId": "aff_other",
                "segmentName": "aff"
            }
        ]
    }
]

List Audience Providers by ID

Method GET
URL https://api.videoplaza.com/v0/audience/[id]
Header Authentication header (x-o-api-key)
Content type application/json
URL params ID of the audience provider
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: audience data provider information

{
    "id": "<string>",
    "name": "<string>",
    "urlIdentifier": "<string>",
    "useSessionStore": <boolean>,
    "useCookies": <boolean>,
    "enabled": <boolean>,
    "audienceSegmentValues": [
        {
            "segmentId": "<string>",
            "segmentName": "<string>"
        },
        {
            "segmentId": "<string>",
            "segmentName": "<string>"
        }
     ]
}

Example:

Request header:

POST /v0/audience/8915b4ad-0572-4d88-acf9-7f0813c953b5 HTTP/1.1
Host: api.videoplaza.com
Content-­type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  200 (OK)

Body:
{
    "id": "8915b4ad-0572-4d88-acf9-7f0813c953b5",
    "name": "Audience",
    "urlIdentifier": "dmpAudience",
    "useSessionStore": false,
    "useCookies": true,
    "enabled": true,
    "audienceSegmentValues": [
        {
            "segmentId": "kv1002",
            "segmentName": "Age"
        },
        {
            "segmentId": "kv1002",
            "segmentName": "Age"
        },
        {
            "segmentId": "kv1002",
            "segmentName": "Age"
        },
        {
            "segmentId": "kv1002",
            "segmentName": "Age"
        },
        {
            "segmentId": "kv1002",
            "segmentName": "Age"
        },
        {
            "segmentId": "kv1002",
            "segmentName": "Age"
        },
        {
            "segmentId": "kv1002",
            "segmentName": "Age"
        },
        {
            "segmentId": "kv1001",
            "segmentName": "Gender"
        },
        {
            "segmentId": "kv1001",
            "segmentName": "Gender"
        }
    ]
}

Was this article helpful?