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 number of impressions for a single spot instance. To convert impressions from per spot instance per 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 impressions per spot instance per 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.2/inventory/spot/ endpoint and the https://api.geopath.org/v2.2/inventory/search endpoint.
Call :
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 impressions for spot identifier 631042 received by any person living anywhere in the united states.
https://api.geopath.org/v2.2/inventory/spot/631042?hourly_measures=true&target_segment=9330
Response:
The response includes total_msg_impressions (aka impressions per spot 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.
{
"id": 631042,
...
"measures": {
...
},
"total_msg_impressions": {
"measures_type": "Hourly",
"target_segment": "9330",
"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 the request and response are the same, but in this case the ID is for a digital spot.
{
"id": 45821,
...
"share_of_voice": 0.125,
...
"measures": {
...
},
"total_msg_impressions": {
"measures_type": "Hourly",
"target_segment": "9330",
"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:
hourly impressions per spot = total_msg_impressions * ((3600*layout.share_of_voice)/(spots.length/spots.spot_share_of_voice))
In this case, 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.54875 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.
{
"parent_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":9330
}
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.
{
"inventory_summary": {
...
"inventory_items": [
{
...
"spot_references": [
{
"spot_id": 30982353,
....
"measures": {
...
},
...
"total_msg_impressions": {
"measures_type": "Hourly",
"target_segment": "9330",
"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
}
}
}
Add Comment