3 - Impressions & Audience Concentration Data

We support 2 different types of audience data:

Hourly Impression Multipliers
Hourly Audience Concentration, or Hourly Audience Segments

Both of theses types of data are ingested and stored in our system as strings of 168 comma separated decimal values representing every hour in a week (24 * 7), 00:00-23:00 Monday-Friday.

1 - Impression Multipliers

impression multiplier data indicates the number of people who are exposed to an ad play. Most data providers provide the total number of impressions for a screen per hour. The calculation to obtain the impressions per play is typically hourly_impressions * (dwell_time_seconds / 3600).

Providing impression multipliers for your screens is the final step before your screens can be considered "playable". Without any impression multipliers, your screens are not considered by our ad server's algorithms based simply on the fact that we determine where to play an ad respecting the number of people around a screen. If your impression multipliers do not exist, or are 0 for a particular hour, what's the point delivering an ad to it if no one is around to see it?

2 - Audience Concentrations, or Audience Segments

Audience Concentrations and Audience Segments are interchangeable terms. They simply mean the percentage of people exposed to a screen per hour that fall into a particular grouping. By grouping, it can be something like Male, or female, or something more complex like people that visited Walmart at least twice in the last 3 months. Audience concentrations are used in tandem with Audience Impressions by multiplying the two to obtain the number of targeted impressions, rather than the total Impressions Multipliers.

Importing impression multiplier data

The process is relatively straightforward, however, formatting the data prior can be tricky sometimes. There are a few helpful things to note that may be of use to you:

Impression multipliers are stored in screen local time. So a screen in Montreal should have its data stored in EDT (America/Montreal) time.
Hourly data is always 168 consecutive hours (1 week), but can apply to multiple weeks using start and end dates.
An end date of null means it does not end. Simply omitting the field is sufficient

Audience data - Make the request

URL

https://apps.hivestack.com/api/v2/units/{unit_id}/impressions
Method:

POST
Data:

[
  {
    "hourly_impressions": "31.313333,26.033333,21.486667,15.400000,16.280000,18.480000,21.486667,31.313333,34.246667,27.866667,26.180000,27.793333,28.893333,28.453333,31.606667,32.046667,36.300000,35.786667,34.833333,39.160000,39.746667,44.586667,43.120000,40.846667,31.313333,26.033333,21.486667,15.400000,16.280000,18.480000,21.486667,31.313333,34.246667,27.866667,26.180000,27.793333,28.893333,28.453333,31.606667,32.046667,36.300000,35.786667,34.833333,39.160000,39.746667,44.586667,43.120000,40.846667,31.313333,26.033333,21.486667,15.400000,16.280000,18.480000,21.486667,31.313333,34.246667,27.866667,26.180000,27.793333,28.893333,28.453333,31.606667,32.046667,36.300000,35.786667,34.833333,39.160000,39.746667,44.586667,43.120000,40.846667,31.313333,26.033333,21.486667,15.400000,16.280000,18.480000,21.486667,31.313333,34.246667,27.866667,26.180000,27.793333,28.893333,28.453333,31.606667,32.046667,36.300000,35.786667,34.833333,39.160000,39.746667,44.586667,43.120000,40.846667,31.313333,26.033333,21.486667,15.400000,16.280000,18.480000,21.486667,31.313333,34.246667,27.866667,26.180000,27.793333,28.893333,28.453333,31.606667,32.046667,36.300000,35.786667,34.833333,39.160000,39.746667,44.586667,43.120000,40.846667,33.220000,25.520000,23.686667,16.133333,17.306667,12.540000,14.593333,19.800000,25.960000,33.513333,31.680000,35.053333,31.680000,36.446667,32.120000,36.006667,38.060000,39.160000,38.280000,37.546667,40.113333,37.546667,39.380000,38.060000,33.220000,25.520000,23.686667,16.133333,17.306667,12.540000,14.593333,19.800000,25.960000,33.513333,31.680000,35.053333,31.680000,36.446667,32.120000,36.006667,38.060000,39.160000,38.280000,37.546667,40.113333,37.546667,39.380000,38.060000"
  }
]

Response:

[
  {
    "demographic_id": 0,
    "from_date": "2019-01-01",
    "hourly_impressions": "31.313333,26.033333,21.486667,15.400000,16.280000,18.480000,21.486667,31.313333,34.246667,27.866667,26.180000,27.793333,28.893333,28.453333,31.606667,32.046667,36.300000,35.786667,34.833333,39.160000,39.746667,44.586667,43.120000,40.846667,31.313333,26.033333,21.486667,15.400000,16.280000,18.480000,21.486667,31.313333,34.246667,27.866667,26.180000,27.793333,28.893333,28.453333,31.606667,32.046667,36.300000,35.786667,34.833333,39.160000,39.746667,44.586667,43.120000,40.846667,31.313333,26.033333,21.486667,15.400000,16.280000,18.480000,21.486667,31.313333,34.246667,27.866667,26.180000,27.793333,28.893333,28.453333,31.606667,32.046667,36.300000,35.786667,34.833333,39.160000,39.746667,44.586667,43.120000,40.846667,31.313333,26.033333,21.486667,15.400000,16.280000,18.480000,21.486667,31.313333,34.246667,27.866667,26.180000,27.793333,28.893333,28.453333,31.606667,32.046667,36.300000,35.786667,34.833333,39.160000,39.746667,44.586667,43.120000,40.846667,31.313333,26.033333,21.486667,15.400000,16.280000,18.480000,21.486667,31.313333,34.246667,27.866667,26.180000,27.793333,28.893333,28.453333,31.606667,32.046667,36.300000,35.786667,34.833333,39.160000,39.746667,44.586667,43.120000,40.846667,33.220000,25.520000,23.686667,16.133333,17.306667,12.540000,14.593333,19.800000,25.960000,33.513333,31.680000,35.053333,31.680000,36.446667,32.120000,36.006667,38.060000,39.160000,38.280000,37.546667,40.113333,37.546667,39.380000,38.060000,33.220000,25.520000,23.686667,16.133333,17.306667,12.540000,14.593333,19.800000,25.960000,33.513333,31.680000,35.053333,31.680000,36.446667,32.120000,36.006667,38.060000,39.160000,38.280000,37.546667,40.113333,37.546667,39.380000,38.060000",
    "is_override": 0,
    "to_date": null,
    "unit_id": 27799
  }
]

You're all set! Wait a second... What about Audience Concentrations, or Audience Segments?

You have successfully set up the bare minimum to be able to make ad requests and receive ads from our ad server! But there's more...

Importing Audience Concentration data

Concentrations, like the word suggests, is a percentage that represents a subset of the total audience exposed to a screen. Concentrations are interesting and important because they give us/you data about who and when a particular demographic of people are around a given screen.

Example: At 4PM on a Tuesday there are 100 total audience (people) who will be exposed to board x over the course of the next hour. Among those 100 people, 65% of them are between the age of 18 and 24 inclusively. That means for this hour, the concentration of people aged 18-24 is 0.65.

Formatting of concentrations is almost exactly the same as audience data with the exception of the hourly values being values between 0 and 1 inclusively.

Note: the JSON key name also changes from hourly_impressions to hourly_concentrations.

Segments, sometimes "Demographics" - Why you need this

Before you can add concentrations, you must first add segment definitions to your organization. When we were adding audience data, we passed a demographic_id of 0 in our JSON request. 0 is defined in our system as the ALL segment, meaning everyone exposed to a screen. All other segment are user-definable and thus must be defined before they are used.

For example: you may have data that represents the concentration of people who play video games. You need to first define that video games is a segment that can be targeted before you can say "Hey! This screen over here at 7AM on Monday has a concentration of 0.04 for people that play video games".

Demographic - Make the request

Description

Internally, we refer to both Audience Impression objects, and Audience Segment objects as Demographics.
URL

https://privateurl.com/api/v2/demographics/
Method:

POST
Data:

{
  "organization_id": 6,
  "name": "Female",
  "type": "GDR",
  "code": "F 14+"
}

Response:

[
  {
    "demographic_id": 26,
    "organization_id": 6,
    "name": "Female",
    "type": "GDR",
    "code": "F 14+"
  }
]

Cool, we have an audience segment now! Time to move on to the concentration data.

Concentration - Make the request

URL

https://privateurl.com/api/v2/audiencedata/smartupdate/
Method:

POST
Data:

[
  {
    "demographic_id": 26,
    "unit_id": 27799,
    "hourly_concentrations": "0,0,0,0,0,0,0.128358620689655,0.246128735632184,0.230354022988506,0.297558620689655,0.580422988505747,0.325866666666667,0.142620689655172,0.172441379310345,0.314629885057471,0.254124137931034,0.0994022988505747,0.192970114942529,0.272275862068966,0.349420689655172,0.341425287356322,0.398905747126437,0.233379310344828,0,0,0,0,0,0,0,0.128358620689655,0.246128735632184,0.230354022988506,0.297558620689655,0.580422988505747,0.325866666666667,0.142620689655172,0.172441379310345,0.314629885057471,0.254124137931034,0.0994022988505747,0.192970114942529,0.272275862068966,0.349420689655172,0.341425287356322,0.398905747126437,0.233379310344828,0,0,0,0,0,0,0,0.128358620689655,0.246128735632184,0.230354022988506,0.297558620689655,0.580422988505747,0.325866666666667,0.142620689655172,0.172441379310345,0.314629885057471,0.254124137931034,0.0994022988505747,0.192970114942529,0.272275862068966,0.349420689655172,0.341425287356322,0.398905747126437,0.233379310344828,0,0,0,0,0,0,0,0.128358620689655,0.246128735632184,0.230354022988506,0.297558620689655,0.580422988505747,0.325866666666667,0.142620689655172,0.172441379310345,0.314629885057471,0.254124137931034,0.0994022988505747,0.192970114942529,0.272275862068966,0.349420689655172,0.341425287356322,0.398905747126437,0.233379310344828,0,0,0,0,0,0,0,0.128358620689655,0.246128735632184,0.230354022988506,0.297558620689655,0.580422988505747,0.325866666666667,0.142620689655172,0.172441379310345,0.314629885057471,0.254124137931034,0.0994022988505747,0.192970114942529,0.272275862068966,0.349420689655172,0.341425287356322,0.398905747126437,0.233379310344828,0,0,0,0,0,0,0,0.455089655172414,0.121227586206897,0.331485057471264,0.285889655172414,0.154289655172414,0.235972413793104,0.332781609195402,0.238133333333333,0.247209195402299,0.199668965517241,0.397609195402299,0.217604597701149,0.332781609195402,0.104372413793103,0.0907586206896552,0.162933333333333,0.350068965517241,0,0,0,0,0,0,0,0.455089655172414,0.121227586206897,0.331485057471264,0.285889655172414,0.154289655172414,0.235972413793104,0.332781609195402,0.238133333333333,0.247209195402299,0.199668965517241,0.397609195402299,0.217604597701149,0.332781609195402,0.104372413793103,0.0907586206896552,0.162933333333333,0.350068965517241,0",
    "is_override": 0
  }
]

Response:

[
  {
    "audiencedata_id": 337898,
    "demographic_id": 26,
    "demographic_id_2": null,
    "demographic_id_3": null,
    "from_date": null,
    "hourly_concentrations": "0,0,0,0,0,0,0.128358620689655,0.246128735632184,0.230354022988506,0.297558620689655,0.580422988505747,0.325866666666667,0.142620689655172,0.172441379310345,0.314629885057471,0.254124137931034,0.0994022988505747,0.192970114942529,0.272275862068966,0.349420689655172,0.341425287356322,0.398905747126437,0.233379310344828,0,0,0,0,0,0,0,0.128358620689655,0.246128735632184,0.230354022988506,0.297558620689655,0.580422988505747,0.325866666666667,0.142620689655172,0.172441379310345,0.314629885057471,0.254124137931034,0.0994022988505747,0.192970114942529,0.272275862068966,0.349420689655172,0.341425287356322,0.398905747126437,0.233379310344828,0,0,0,0,0,0,0,0.128358620689655,0.246128735632184,0.230354022988506,0.297558620689655,0.580422988505747,0.325866666666667,0.142620689655172,0.172441379310345,0.314629885057471,0.254124137931034,0.0994022988505747,0.192970114942529,0.272275862068966,0.349420689655172,0.341425287356322,0.398905747126437,0.233379310344828,0,0,0,0,0,0,0,0.128358620689655,0.246128735632184,0.230354022988506,0.297558620689655,0.580422988505747,0.325866666666667,0.142620689655172,0.172441379310345,0.314629885057471,0.254124137931034,0.0994022988505747,0.192970114942529,0.272275862068966,0.349420689655172,0.341425287356322,0.398905747126437,0.233379310344828,0,0,0,0,0,0,0,0.128358620689655,0.246128735632184,0.230354022988506,0.297558620689655,0.580422988505747,0.325866666666667,0.142620689655172,0.172441379310345,0.314629885057471,0.254124137931034,0.0994022988505747,0.192970114942529,0.272275862068966,0.349420689655172,0.341425287356322,0.398905747126437,0.233379310344828,0,0,0,0,0,0,0,0.455089655172414,0.121227586206897,0.331485057471264,0.285889655172414,0.154289655172414,0.235972413793104,0.332781609195402,0.238133333333333,0.247209195402299,0.199668965517241,0.397609195402299,0.217604597701149,0.332781609195402,0.104372413793103,0.0907586206896552,0.162933333333333,0.350068965517241,0,0,0,0,0,0,0,0.455089655172414,0.121227586206897,0.331485057471264,0.285889655172414,0.154289655172414,0.235972413793104,0.332781609195402,0.238133333333333,0.247209195402299,0.199668965517241,0.397609195402299,0.217604597701149,0.332781609195402,0.104372413793103,0.0907586206896552,0.162933333333333,0.350068965517241,0",
    "hourly_impressions": null,
    "is_override": 0,
    "realtime_multiplier": 1,
    "to_date": null,
    "unit_id": 27799
  }
]

Hivestack

The Hivestack Developer Hub

3 - Impression Multipliers