With the launch of Geopath's new measurement system there is now an enhanced ability to see impressions per hour.
Hourly impressions are available at the specific spot level for 0+ (2032), 5+(8923), 18+(7166) and 21+(8228) audiences. They are also available for 0+ (9330), 5+(2038), 18+(2035) and 21+(2036) core audiences that exclude Group Quarters Populations. They Geopath supports the ability to retrieve the estimated number of impressions per spot instance, per hour (i.e. the number of times a spot that contained an advertising message was shown on a screen, per hour) for a limited number of audience segments (i.e. P0+/P5+/P18+/P21+), among all persons residing in United States (i.e., without any specific target market geography).
This document will explain how to use Geopath’s API to retrieve hourly impression data regardless of whether the frame/spot is printed/static, tri-vision or digital. This explanation will be easier to understand if the reader has a clear understanding the relationship between frames, layouts, faces, spots and messages; we recommend reviewing OOH Inventory Data Model Hierarch: Frames, Layouts, Faces, and Spots.
A spot is an opportunity to display “creative content”. Creative content can be an image, a video, a textual message, audio, an ad or a combination of these. In Geopath’s terminology, we call “creative content” a message. Geopath does not provide audience measurement for a specific message but instead provides audience measurement for a spot (which may contain a message). For most practical purposes, spot impressions and message impressions are the same, but Geopath would like to ensure the reader understands the subtle distinction between a spot and a message.
Key to understanding how to get hourly impressions for both digital and static spots is understanding the difference between a spot and a spot instance. We can illustrate this concept using an example of a rotating frame. Rotating frames display multiple spots on the same frame by alternately displaying the spots in sequence, one after the other. Both digital frames and tri-vision frames are rotating frames. If we use a simple example of a digital frame with one layout and 6 spots, with each spot displaying for exactly 10 seconds before rotating to the next spot, then each spot would be displayed 60 times in an hour. In Geopath terminology, the duration of a single spot instance is the spot length. And in this example, each spot has a share of voice that is one sixth of the entire rotation time required for all spots to display exactly once.
The API attribute total_msg_impressions represents the average impressions per spot instanceper hour this is commonly referred to as the spot multiplier. To convert from average impressions per spot instanceper hour (i.e., total_msg_impressions) to impressions per spot per hour, we multiply the API value 'total_msg_impressions' by the number of times a spot is displayed per hour. In the above example for the digital sign, we would multiply total_msg_impressions by 60 (i.e., one time a minute or 60 times an hour).
For a static frame (a printed frame that does not have rotating spots), we can consider that frame as having a spot length (i.e., duration) of 3600 seconds per hour and a share of voice of 1.0, which allows the exact same formula to be used regardless of whether the spot is digital or static:
impressions per spot per hour = total_msg_impressions * number of times a spot is displayed per hour
For a static frame, the number of times the spot is displayed per hour is one. So, in the case of a static sign the average impressions per spot instanceper hour is the same as the impressions per spot per hour.
To determine total hourly impressions for a digital spot, we need to determine how many instances of the spot are displayed in an hour. Sticking to the above example with a rotating frame having one layout and one face, and each spot having a length (duration of display) of 10 seconds, the number of spot instances per hour can be calculated by:
spot instances per hour = 3600 / (spots.length * 1/spots.spot_share_of_voice)
so, applying this formula to our example:
3600 seconds / (10 seconds * 1/(1/6)) = 60 spot instances
Assuming the total_msg_impressions in this example were 100 impressions per spot instance per hour, then the hourly impressions for the spot (i.e., all spot instances in the hour) would be
60 * 100 impressions per spot instance per hour = 6000 impressions per spot instance per hour
This calculation holds for the common case where there is only one layout on a frame. To generalize the formula, the layout share of voice must also be used. As an example, let's add in the assumption that there are two layouts on the frame with each layout being displayed for 30 minutes of each hour. In this example, the layout share of voice is 0.5 and the calculation becomes:
spot instances per hour = 3600 / (spots.length * 1/spots.spot_share_of_voice) * layout.share_of_voice
or
30 = 3600 / (10 seconds * 1/(1/6)) * 0.5
Note that the layout.share_of_voice is 1.0 for a static sign, so we can multiply by 1.0 for the layout.share_of_voice for a static frame (or we can omit the multiplication by 1.0 altogether). The general formula for calculating hourly impressions is the same regardless of frame type.
In the 2023 Forecast, served on API v2.2, hourly impressions are currently available for the following core audience segments that include Group Quarters Populations:
All persons 0+ (9330),
All persons 5+ (2038),
All persons 18+ (2035) and
All persons 21+ (2036)
Per spot instance per hour impressions (a.k.a., hourly impressions) are only available for the Global market and are not yet available for local markets. They are available from the https://api.geopath.org/v2.12/inventory/spot/ endpoint and the https://api-docs.geopath.org/inventory-api-2-11/apis/postv2.2/inventory/search endpoint.
...
The GET call for hourly impressions requires two parameters get passed. hourly_measures = true and target_segment, which needs to be one of the 4 supported audiences. This call is asking for the hourly measures impressions for spot 631042 at the 0+ levelidentifier 631042 received by any person living anywhere in the united states.
https://api.geopath.org/v2.12/inventory/spot/631042?hourly_measures=true&target_segment=20329330
Response:
The response includes total_msg_impressions (aka impressions per playspot instance) for each hour of each day of the week as well as information about the spot. This response is for a static piece of inventory. This response has been edited for length.
| Code Block | ||
|---|---|---|
| ||
{
"id": 631042,
...
"measures": {
...
},
"total_msg_impressions": {
"measures_type": "Hourly",
"target_segment": "20329330",
"target_geo": "GLOBAL",
"market": "GLOBAL",
"mon": {
"16": 1085.6931,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 701.3269,
"7": 1254.0867,
"8": 1234.7464,
"9": 1143.7807,
"10": 563.7419,
"11": 614.2854,
"12": 666.9281,
"13": 680.2556,
"14": 767.6736,
"15": 1128.6376,
"17": 1053.4584,
"18": 800.686,
"19": 127.6515,
"20": 0.0,
"21": 0.0
},
"tue": {
"16": 1085.6931,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 701.3269,
"7": 1254.0867,
"8": 1234.7464,
"9": 1143.7807,
"10": 563.7419,
"11": 614.2854,
"12": 666.9281,
"13": 680.2556,
"14": 767.6736,
"15": 1128.6376,
"17": 1053.4584,
"18": 800.686,
"19": 127.6515,
"20": 0.0,
"21": 0.0
},
"wed": {
"16": 1085.6931,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 701.3269,
"7": 1254.0867,
"8": 1234.7464,
"9": 1143.7807,
"10": 563.7419,
"11": 614.2854,
"12": 666.9281,
"13": 680.2556,
"14": 767.6736,
"15": 1128.6376,
"17": 1053.4584,
"18": 800.686,
"19": 127.6515,
"20": 0.0,
"21": 0.0
},
"thu": {
"16": 1085.6931,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 701.3269,
"7": 1254.0867,
"8": 1234.7464,
"9": 1143.7807,
"10": 563.7419,
"11": 614.2854,
"12": 666.9281,
"13": 680.2556,
"14": 767.6736,
"15": 1128.6376,
"17": 1053.4584,
"18": 800.686,
"19": 127.6515,
"20": 0.0,
"21": 0.0
},
"fri": {
"16": 634.5248,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 781.2816,
"7": 1388.3406,
"8": 1392.8029,
"9": 1318.4193,
"10": 507.4781,
"11": 556.3312,
"12": 603.0401,
"13": 623.1213,
"14": 709.0846,
"15": 688.5293,
"17": 599.181,
"18": 452.4068,
"19": 144.4297,
"20": 0.0,
"21": 0.0
},
"sat": {
"16": 570.7711,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 250.2465,
"7": 498.294,
"8": 760.3759,
"9": 1009.3332,
"10": 683.2922,
"11": 742.2024,
"12": 756.2217,
"13": 731.2883,
"14": 704.7625,
"15": 632.9886,
"17": 514.4061,
"18": 435.6574,
"19": 81.7362,
"20": 0.0,
"21": 0.0
},
"sun": {
"16": 625.1799,
"0": 0.0,
"1": 0.0,
"22": 0.0,
"23": 0.0,
"2": 0.0,
"3": 0.0,
"4": 0.0,
"5": 0.0,
"6": 213.985,
"7": 415.7325,
"8": 675.519,
"9": 994.5795,
"10": 667.1454,
"11": 740.1086,
"12": 761.698,
"13": 747.6507,
"14": 718.2456,
"15": 690.226,
"17": 546.9185,
"18": 454.704,
"19": 98.223,
"20": 0.0,
"21": 0.0
}
}
} |
For digital inventory
...
Call:
The call is the same, in the case the ID is for a digital spot
...
the request and response are the same, but in this case the ID is for a digital spot.
| Code Block |
|---|
{
"id": 45821,
...
"share_of_voice": 0.125,
...
"measures": {
...
},
"total_msg_impressions": {
"measures_type": "Hourly",
"target_segment": "20329330",
"target_geo": "GLOBAL",
"market": "GLOBAL",
"mon": {
"16": 104.6652,
"0": 1.945,
"23": 8.9485,
"1": 1.9912,
"2": 2.466,
"3": 3.9021,
"4": 6.0057,
"5": 8.8542,
"6": 22.8732,
"7": 42.6404,
"8": 45.6513,
"9": 46.9673,
"10": 59.4017,
"11": 68.5243,
"12": 83.876,
"13": 94.2039,
"14": 121.6313,
"15": 108.7477,
"17": 88.507,
"18": 55.5707,
"19": 80.6602,
"20": 47.1325,
"21": 21.6295,
"22": 14.1046
},
"tue": {
"16": 104.6652,
"0": 1.945,
"23": 8.9485,
"1": 1.9912,
"2": 2.466,
"3": 3.9021,
"4": 6.0057,
"5": 8.8542,
"6": 22.8732,
"7": 42.6404,
"8": 45.6513,
"9": 46.9673,
"10": 59.4017,
"11": 68.5243,
"12": 83.876,
"13": 94.2039,
"14": 121.6313,
"15": 108.7477,
"17": 88.507,
"18": 55.5707,
"19": 80.6602,
"20": 47.1325,
"21": 21.6295,
"22": 14.1046
},
"wed": {
"16": 104.6652,
"0": 1.945,
"23": 8.9485,
"1": 1.9912,
"2": 2.466,
"3": 3.9021,
"4": 6.0057,
"5": 8.8542,
"6": 22.8732,
"7": 42.6404,
"8": 45.6513,
"9": 46.9673,
"10": 59.4017,
"11": 68.5243,
"12": 83.876,
"13": 94.2039,
"14": 121.6313,
"15": 108.7477,
"17": 88.507,
"18": 55.5707,
"19": 80.6602,
"20": 47.1325,
"21": 21.6295,
"22": 14.1046
},
"thu": {
"16": 104.6652,
"0": 1.945,
"23": 8.9485,
"1": 1.9912,
"2": 2.466,
"3": 3.9021,
"4": 6.0057,
"5": 8.8542,
"6": 22.8732,
"7": 42.6404,
"8": 45.6513,
"9": 46.9673,
"10": 59.4017,
"11": 68.5243,
"12": 83.876,
"13": 94.2039,
"14": 121.6313,
"15": 108.7477,
"17": 88.507,
"18": 55.5707,
"19": 80.6602,
"20": 47.1325,
"21": 21.6295,
"22": 14.1046
},
"fri": {
"16": 306.387,
"0": 3.1407,
"23": 10.9309,
"1": 3.0309,
"2": 3.4913,
"3": 4.9581,
"4": 7.4025,
"5": 11.168,
"6": 24.1409,
"7": 47.2611,
"8": 55.4073,
"9": 56.9931,
"10": 61.7784,
"11": 72.2067,
"12": 91.3343,
"13": 119.7118,
"14": 204.7374,
"15": 271.6335,
"17": 256.2942,
"18": 143.9799,
"19": 118.5306,
"20": 55.1501,
"21": 26.9983,
"22": 16.3649
},
"sat": {
"16": 119.0891,
"0": 5.9179,
"23": 10.6085,
"1": 5.4012,
"2": 4.9428,
"3": 5.3432,
"4": 7.1372,
"5": 7.2859,
"6": 15.8923,
"7": 34.9228,
"8": 60.0283,
"9": 79.9648,
"10": 94.3997,
"11": 106.9839,
"12": 121.1266,
"13": 142.5048,
"14": 146.1712,
"15": 147.0486,
"17": 87.826,
"18": 67.6795,
"19": 56.4296,
"20": 42.7292,
"21": 28.7425,
"22": 20.1187
},
"sun": {
"16": 74.8528,
"0": 6.1361,
"23": 5.0881,
"1": 5.5246,
"2": 4.8255,
"3": 4.6386,
"4": 5.8287,
"5": 4.695,
"6": 6.8126,
"7": 15.1275,
"8": 27.0525,
"9": 37.1368,
"10": 61.0023,
"11": 64.9546,
"12": 66.3299,
"13": 62.7938,
"14": 60.5499,
"15": 64.6325,
"17": 82.5353,
"18": 54.2426,
"19": 33.2299,
"20": 22.2203,
"21": 10.0552,
"22": 7.0277
}
}
} |
...
Using the above data, we can apply our equation to calculate the hourly impressions
...
per spot:
spot.measures.day.hour.impressions_per_play hourly impressions per spot = total_msg_impressions * ((3600*layout.share_of_voice)/(spotspots.length/spots.spot._share_of_voice))
In this case for FRI Hour 17 , for 5pm local time on Friday (Hour 17) "17": 256.2942, the equation would be as follows:
256.2942 * ((3600*1)/(8/.125))
Which equals 14416.54875Note that the layout share of voice is found as part of the frame object impressions per spot, per hour.
Use Case: Updating hourly measures for only recently updated inventory.
If you've previously requested hourly measures and stored them locally, you may want to update them after inventory has been re-audited and the measures may have changed. In this case, using the inventory/search endpoint will return hourly measures for multiple pieces of inventory.
Call:
This call is similar to other inventory/search calls, but adds the parameter "hourly_measures":true which tells the search that the request wants hourly measures. All other search parameters are available, which is why the request is able to narrow it down to a specific date range and operator. It is important to remember that the hourly_measures are still only available for core audiences and one of those audiences must be specified in the "target_segment" parameter.
| Code Block |
|---|
{
"operatorparent_account_name_list": [
"JCDecaux"
],
"updated_date_range": {
"start_date": "2020-06-01T00:00:00.000Z",
"end_date": "2020-06-26T23:59:59.000Z"
}
"measures_required":true,
"hourly_measures":true,
"target_segment":71669330
} |
Response:
The response includes the standard ````inventory/search``` response, but the measures object is expanded to include the "total_msg_impressions" object which details the impressions per play per hour per day of week.This response has been edited for length.
| Code Block |
|---|
{
"inventory_summary": {
...
"inventory_items": [
{
...
"spot_references": [
{
"spot_id": 30982353,
....
"measures": {
...
},
...
"total_msg_impressions": {
"measures_type": "Hourly",
"target_segment": "71669330",
"target_geo": "GLOBAL",
"market": "GLOBAL",
"mon": {
"16": 1131.2798,
"0": 94.3905,
"1": 79.6523,
"2": 70.3266,
"14": 1006.1432,
"15": 1112.6215,
"11": 973.2092,
"12": 997.1305,
"22": 223.6841,
"23": 153.9694,
"3": 75.6762,
"13": 949.5033,
"21": 257.0081,
"20": 299.2611,
"8": 1321.3751,
"9": 1274.8309,
"7": 1408.9048,
"6": 924.4157,
"17": 1054.1251,
"10": 911.1408,
"4": 99.1228,
"5": 167.5246,
"19": 313.1573,
"18": 792.7066
},
"tue": {
"16": 1131.2798,
"0": 94.3905,
"1": 79.6523,
"2": 70.3266,
"14": 1006.1432,
"15": 1112.6215,
"11": 973.2092,
"12": 997.1305,
"22": 223.6841,
"23": 153.9694,
"3": 75.6762,
"13": 949.5033,
"21": 257.0081,
"20": 299.2611,
"8": 1321.3751,
"9": 1274.8309,
"7": 1408.9048,
"6": 924.4157,
"17": 1054.1251,
"10": 911.1408,
"4": 99.1228,
"5": 167.5246,
"19": 313.1573,
"18": 792.7066
},
"wed": {
"16": 1131.2798,
"0": 94.3905,
"1": 79.6523,
"2": 70.3266,
"14": 1006.1432,
"15": 1112.6215,
"11": 973.2092,
"12": 997.1305,
"22": 223.6841,
"23": 153.9694,
"3": 75.6762,
"13": 949.5033,
"21": 257.0081,
"20": 299.2611,
"8": 1321.3751,
"9": 1274.8309,
"7": 1408.9048,
"6": 924.4157,
"17": 1054.1251,
"10": 911.1408,
"4": 99.1228,
"5": 167.5246,
"19": 313.1573,
"18": 792.7066
},
"thu": {
"16": 1131.2798,
"0": 94.3905,
"1": 79.6523,
"2": 70.3266,
"14": 1006.1432,
"15": 1112.6215,
"11": 973.2092,
"12": 997.1305,
"22": 223.6841,
"23": 153.9694,
"3": 75.6762,
"13": 949.5033,
"21": 257.0081,
"20": 299.2611,
"8": 1321.3751,
"9": 1274.8309,
"7": 1408.9048,
"6": 924.4157,
"17": 1054.1251,
"10": 911.1408,
"4": 99.1228,
"5": 167.5246,
"19": 313.1573,
"18": 792.7066
},
"fri": {
"16": 1158.0417,
"0": 110.9726,
"1": 92.3966,
"2": 80.0768,
"14": 1384.5434,
"15": 1157.2485,
"11": 1350.9833,
"12": 1378.5591,
"22": 261.1661,
"23": 180.4019,
"3": 84.0225,
"13": 1307.4858,
"21": 296.1627,
"20": 322.397,
"8": 1146.2829,
"9": 1132.8448,
"7": 1173.1396,
"6": 784.5024,
"17": 1077.6308,
"10": 1267.0019,
"4": 108.7172,
"5": 185.2344,
"19": 323.712,
"18": 841.4123
},
"sat": {
"16": 887.9549,
"0": 114.267,
"1": 96.9079,
"2": 83.0552,
"14": 1399.7035,
"15": 911.6171,
"11": 1639.0963,
"12": 1597.8309,
"22": 278.0859,
"23": 198.5225,
"3": 83.1713,
"13": 1464.7111,
"21": 323.2888,
"20": 377.6244,
"8": 811.7533,
"9": 944.6749,
"7": 596.1,
"6": 378.9719,
"17": 843.3488,
"10": 1586.5352,
"4": 104.0201,
"5": 157.6738,
"19": 403.5978,
"18": 718.2194
},
"sun": {
"16": 741.3594,
"0": 176.1774,
"1": 154.8591,
"2": 133.9085,
"14": 815.2282,
"15": 762.7699,
"11": 879.8753,
"12": 908.3486,
"22": 260.4141,
"23": 188.4866,
"3": 128.6869,
"13": 844.2384,
"21": 310.2316,
"20": 432.1372,
"8": 719.4149,
"9": 879.1185,
"7": 502.3611,
"6": 316.7723,
"17": 704.4131,
"10": 832.7391,
"4": 152.3037,
"5": 181.8324,
"19": 493.0984,
"18": 597.6113
}
},
...
}
],
....
},
.....
}
],
"pagination": {
"page": 1,
"page_size": 100,
"number_of_pages": 1,
"number_of_frames": 4,
"number_of_spots": 6
}
}
} |